@htilabs/platform-common-models 0.68.0 → 0.69.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.
@@ -0,0 +1,706 @@
1
+ /**
2
+ * @htilabs/platform-common-models — folding a copy into the real organization
3
+ *
4
+ * The logic behind `fill-org-registry --apply-merges`. Runbook:
5
+ * `scripts/FILL_ORG_REGISTRY_RUNBOOK.md`, "Folding a copy into the real
6
+ * organization".
7
+ *
8
+ * ## Why
9
+ *
10
+ * One record per real-world organization (UDD Org Data Object, 2026-10-02).
11
+ * Where the same organization was typed in twice, the steward (HTI Labs)
12
+ * reconciles the two by hand: a person names the copy and the row that is
13
+ * kept. Nothing here works out which rows are copies.
14
+ *
15
+ * ## What a merge is (ruled 2026-10-20, the prototype's ORG-MERGE)
16
+ *
17
+ * Pure re-pointing. Every stored reference to the copy's `_id` is changed to
18
+ * the kept organization's `_id`. Nothing on the kept row is combined or
19
+ * rewritten: not its name, type, VSP answer, list or programs, and no
20
+ * Account's sharing rule. The copy is then deleted, and its id is recorded on
21
+ * the kept row as `legacy_ids.merged_from`, so an old reference found later
22
+ * can be traced.
23
+ *
24
+ * ## Where references live
25
+ *
26
+ * {@link ORG_REFERENCES} is the list, read from the models of this package,
27
+ * Thread, PAVE 2.0, the Platform app and auth (2026-11-10). Thread and PAVE
28
+ * keep their case records in databases of their own. The copy is deleted only
29
+ * when nothing in the platform database points at it AND every Thread and
30
+ * PAVE database was named on the command line and nothing there points at it
31
+ * either. Otherwise the copy stays, marked inactive (`status` 2, which every
32
+ * app already reads as "not offered", `isListedOrganization`), and the line
33
+ * says why.
34
+ *
35
+ * ## What it never does
36
+ *
37
+ * It never writes a fact of the kept row, never moves an identifier (`key`:
38
+ * identifiers never change), never moves a sharing grant, never merges an
39
+ * Agency's own organization (that is not a copy) or a copy that has programs,
40
+ * and never re-points a copy of an id kept inside a sent share, a session
41
+ * draft or a sealed field (see the runbook).
42
+ */
43
+
44
+ /*
45
+ * Moved here from scripts/ in 0.69.0, where the 100-column lint rule does not
46
+ * run. The reference table below reads as one line per place an id is stored;
47
+ * the long lines are kept so the move stays a move. The one change: nothing
48
+ * here imports mongoose or the driver. The handles are typed structurally and
49
+ * the caller passes its own ObjectId class and EJSON ({@link MergeDriver}), so
50
+ * an id built here is the same class the caller's driver stores and reads.
51
+ */
52
+ /* eslint-disable max-len */
53
+
54
+
55
+ import { ORGANIZATION_STATUS, isListedOrganization } from "../orgDirectory/orgRecord.js";
56
+ import { AGENCIES_COLLECTION, ORGANIZATIONS_COLLECTION } from "../orgDirectory/read.js";
57
+ import { directoryIdString } from "../orgDirectory/rules.js";
58
+ import { POINTS_OF_CONTACT_COLLECTION } from "../pointsOfContact/schemas.js";
59
+ import { SERVICE_LISTINGS_COLLECTION } from "../serviceListings/read.js";
60
+ import { comparableName, sheetText } from "./support.js";
61
+ import type {
62
+ MergeBeforeImages,
63
+ MergeDbLike,
64
+ MergeDocument,
65
+ MergeDriver,
66
+ MergeImage,
67
+ MergeRefImage,
68
+ } from "./types.js";
69
+
70
+ type Db = MergeDbLike;
71
+ type Document = MergeDocument;
72
+ type Row = Record<string, unknown>;
73
+
74
+ const text = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
75
+ const blank = (v: unknown): boolean => v == null || (typeof v === "string" && v.trim() === "");
76
+ const idText = (v: unknown): string => directoryIdString(v) ?? String(v);
77
+ const HEX_24 = /^[0-9a-fA-F]{24}$/;
78
+ const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
79
+
80
+ /** An id's lower-case text when the value is an id (a string or an ObjectId), else null. Never a sub-record. */
81
+ const idOf = (driver: MergeDriver, v: unknown): string | null =>
82
+ typeof v === "string" ? v.trim().toLowerCase() : v instanceof driver.ObjectId ? v.toHexString() : null;
83
+
84
+ /** Every stored form of an id: the ObjectId and the lower-case text when it is 24-hex, else the text. */
85
+ function idForms(driver: MergeDriver, id: unknown): unknown[] {
86
+ const s = idText(id);
87
+ return HEX_24.test(s) ? [new driver.ObjectId(s.toLowerCase()), s.toLowerCase()] : [s];
88
+ }
89
+ /** The kept id in the same stored form as the value it replaces. */
90
+ function inFormOf(driver: MergeDriver, from: unknown, keptId: unknown): unknown {
91
+ const s = idText(keptId);
92
+ return from instanceof driver.ObjectId && HEX_24.test(s) ? new driver.ObjectId(s.toLowerCase()) : s.toLowerCase();
93
+ }
94
+
95
+ /**
96
+ * Thread's development sample rows (`apps/api/src/seed/index.ts`: the
97
+ * "Thread Prototype Agency" and its organizations, ids `64e4ff1c2a7dcd9cb5f4a0xx`
98
+ * and `…a1xx`). Some reached production. They are never a kept row or a copy.
99
+ */
100
+ export const THREAD_SAMPLE_ID_PREFIX = "64e4ff1c2a7dcd9cb5f4a";
101
+
102
+ // ─── Where an organization's `_id` is stored ────────────────────────────────
103
+
104
+ /** Which database a reference lives in: the platform database, or an app's own. */
105
+ export type ReferenceApp = "platform" | "thread" | "pave";
106
+ export const APP_LABEL: Record<ReferenceApp, string> = { platform: "the platform", thread: "Thread", pave: "PAVE" };
107
+
108
+ export interface OrgReference {
109
+ app: ReferenceApp;
110
+ collection: string;
111
+ /**
112
+ * `value`: `path` holds the id. `list`: `path` is a list of ids. `rows`:
113
+ * `path` is a list of sub-records and `field` in each holds the id.
114
+ * `answers`: `path` is a list of form answers and `field` in each is a list
115
+ * of values, any of which may be the id. `count`: counted, never moved: a
116
+ * copy it names is kept, not deleted.
117
+ */
118
+ kind: MergeRefImage["kind"] | "count";
119
+ path: string;
120
+ field?: string;
121
+ /** Who writes it, for the runbook's table. */
122
+ writtenBy: string;
123
+ }
124
+
125
+ /**
126
+ * Every place an organization's `_id` is stored, from the code (2026-11-10).
127
+ * `agencies.organizationId` is not here: an organization an Agency points at
128
+ * is that Agency's own and is never merged. A reference by an Org's `key`
129
+ * (the Platform app's sharing-rule attachments) is not here either: a merge
130
+ * moves ids, and identifiers never move. Program ids (`programs[].programId`)
131
+ * are not here: a copy with programs is refused.
132
+ */
133
+ export const ORG_REFERENCES: readonly OrgReference[] = Object.freeze([
134
+ { app: "platform", collection: "personnelpeople", kind: "value", path: "organizationId", writtenBy: "auth at a first sign-in; Thread's staff records" },
135
+ { app: "platform", collection: ORGANIZATIONS_COLLECTION, kind: "value", path: "parentOrgId", writtenBy: "an Org that is a unit of this one" },
136
+ { app: "platform", collection: SERVICE_LISTINGS_COLLECTION, kind: "value", path: "org_id", writtenBy: "service listings" },
137
+ { app: "platform", collection: POINTS_OF_CONTACT_COLLECTION, kind: "value", path: "org_id", writtenBy: "points of contact" },
138
+ { app: "platform", collection: POINTS_OF_CONTACT_COLLECTION, kind: "value", path: "subject_id", writtenBy: "an Org's own point of contact" },
139
+ { app: "platform", collection: "personnelmergefolds", kind: "value", path: "survivorBefore.organizationId", writtenBy: "Thread's staff-record merge log" },
140
+ { app: "platform", collection: "personnelmergefolds", kind: "value", path: "survivorChange.liftedOrganizationId", writtenBy: "Thread's staff-record merge log" },
141
+ { app: "platform", collection: "surveyedOrganizations", kind: "value", path: "directoryOrganizationId", writtenBy: "the Platform app's agency survey link" },
142
+ { app: "platform", collection: "accountPolicies", kind: "value", path: "orgRef", writtenBy: "the Platform app's account-policy seed" },
143
+ { app: "platform", collection: AGENCIES_COLLECTION, kind: "list", path: "reportingDestinations.designated.mandatory_reporting", writtenBy: "the Platform app's reporting destinations" },
144
+ { app: "platform", collection: AGENCIES_COLLECTION, kind: "list", path: "reportingDestinations.designated.authority_reporting", writtenBy: "the Platform app's reporting destinations" },
145
+
146
+ { app: "thread", collection: "caserecords", kind: "value", path: "referralOrganizationId", writtenBy: "a case's referring organization" },
147
+ { app: "thread", collection: "caserecords", kind: "rows", path: "identifierEntries", field: "usedByOrgId", writtenBy: "a case number's organization" },
148
+ { app: "thread", collection: "submissions", kind: "answers", path: "answers", field: "val", writtenBy: "a form answer naming an organization (the referring-organization question)" },
149
+ { app: "thread", collection: "casesessions", kind: "list", path: "relevantOrganizationIds", writtenBy: "organizations added in a session" },
150
+ { app: "thread", collection: "serviceinstances", kind: "value", path: "referralToOrganizationId", writtenBy: "a service's referral" },
151
+ { app: "thread", collection: "serviceinstances", kind: "value", path: "serviceProviderOrganizationId", writtenBy: "a service's provider" },
152
+ { app: "thread", collection: "personnelpeople", kind: "value", path: "organizationId", writtenBy: "staff records" },
153
+ { app: "thread", collection: "personinteracteds", kind: "value", path: "organizationId", writtenBy: "people a case interacted with" },
154
+
155
+ { app: "pave", collection: "protectedpeople", kind: "value", path: "organizationId", writtenBy: "a person's organization" },
156
+ { app: "pave", collection: "relevantpersons", kind: "value", path: "organizationId", writtenBy: "a relevant person's organization" },
157
+ { app: "pave", collection: "serviceinstances", kind: "value", path: "serviceProviderOrgId", writtenBy: "a service's provider" },
158
+ { app: "pave", collection: "serviceinstances", kind: "value", path: "referralToOrganizationId", writtenBy: "a service's referral" },
159
+ { app: "pave", collection: "programhousingenrollments", kind: "value", path: "providerOrgId", writtenBy: "a housing program's provider" },
160
+ { app: "pave", collection: "householdpets", kind: "value", path: "providerOrgId", writtenBy: "a pet program's provider" },
161
+ { app: "pave", collection: "disclosure_records", kind: "value", path: "recipientOrg", writtenBy: "a disclosure's recipient" },
162
+ { app: "pave", collection: "reportingdestinationconfigs", kind: "list", path: "organizationIds", writtenBy: "reporting destinations" },
163
+ { app: "pave", collection: "casesessions", kind: "list", path: "relevantOrganizationIds", writtenBy: "organizations added in a session" },
164
+ { app: "pave", collection: "sharingsettings", kind: "count", path: "organizationId", writtenBy: "a sharing grant to a partner organization (never moved: sharing rules are not merged)" },
165
+ ] as const);
166
+
167
+ /** The apps that keep references in a database of their own. A copy is deleted only when each was checked. */
168
+ export const APP_DATABASE_KINDS = ["thread", "pave"] as const;
169
+ export type AppDatabaseKind = (typeof APP_DATABASE_KINDS)[number];
170
+
171
+ /** One database a merge reads and re-points in. */
172
+ export interface MergeDatabase {
173
+ app: ReferenceApp;
174
+ name: string;
175
+ db: Db;
176
+ }
177
+
178
+ /** A collection only that app's database has: how a mistyped database name is caught. */
179
+ const APP_MARKER: Record<AppDatabaseKind, string> = { thread: "caserecords", pave: "protectedpeople" };
180
+
181
+ /** Why `db` cannot be `app`'s database, or null when it can. A name that matches nothing would read as "no references". */
182
+ export async function appDatabaseProblem(app: AppDatabaseKind, name: string, db: Db): Promise<string | null> {
183
+ const found = await db.listCollections({ name: APP_MARKER[app] }, { nameOnly: true }).toArray();
184
+ return found.length
185
+ ? null
186
+ : `'${name}' has no ${APP_MARKER[app]} collection, so it is not a ${APP_LABEL[app]} database (check the name)`;
187
+ }
188
+
189
+ const refPath = (r: Pick<OrgReference, "kind" | "path" | "field">): string =>
190
+ r.kind === "rows" || r.kind === "answers" ? `${r.path}.${String(r.field)}` : r.path;
191
+
192
+ /** The value at a dotted path of a document read from the driver. */
193
+ function getPath(doc: Row, path: string): unknown {
194
+ return path.split(".").reduce<unknown>((v, k) => (v && typeof v === "object" ? (v as Row)[k] : undefined), doc);
195
+ }
196
+
197
+ /**
198
+ * A list of ids with the copy's replaced by the kept organization's (in each
199
+ * value's stored form). A list is a set to every app that reads one: where
200
+ * the kept id is already in it, the copy's id is dropped instead.
201
+ */
202
+ function rewriteIds(driver: MergeDriver, list: readonly unknown[], copy: string, kept: unknown): unknown[] {
203
+ const keptHex = idText(kept).toLowerCase();
204
+ let hasKept = list.some((v) => idOf(driver, v) === keptHex);
205
+ const out: unknown[] = [];
206
+ for (const v of list) {
207
+ if (idOf(driver, v) !== copy) out.push(v);
208
+ else if (!hasKept) {
209
+ out.push(inFormOf(driver, v, kept));
210
+ hasKept = true;
211
+ }
212
+ }
213
+ return out;
214
+ }
215
+
216
+ /** Sub-records with the copy's id in `field` replaced; a sub-record that would then repeat another one exactly is dropped. */
217
+ function rewriteRows(driver: MergeDriver, rows: readonly unknown[], field: string, copy: string, kept: unknown): unknown[] {
218
+ const key = (r: unknown): string =>
219
+ r && typeof r === "object" ? JSON.stringify({ ...(r as Row), [field]: idOf(driver, (r as Row)[field]) }) : JSON.stringify(r);
220
+ const isCopyRow = (r: unknown): boolean => !!r && typeof r === "object" && idOf(driver, (r as Row)[field]) === copy;
221
+ const seen = new Set(rows.filter((r) => !isCopyRow(r)).map(key));
222
+ const out: unknown[] = [];
223
+ for (const r of rows) {
224
+ if (!isCopyRow(r)) {
225
+ out.push(r);
226
+ continue;
227
+ }
228
+ const moved = { ...(r as Row), [field]: inFormOf(driver, (r as Row)[field], kept) };
229
+ if (seen.has(key(moved))) continue;
230
+ seen.add(key(moved));
231
+ out.push(moved);
232
+ }
233
+ return out;
234
+ }
235
+
236
+ /** Form answers with the copy's id replaced inside each answer's list of values. */
237
+ function rewriteAnswers(driver: MergeDriver, answers: readonly unknown[], field: string, copy: string, kept: unknown): unknown[] {
238
+ return answers.map((a) => {
239
+ const vals = a && typeof a === "object" ? (a as Row)[field] : undefined;
240
+ return Array.isArray(vals) && vals.some((v) => idOf(driver, v) === copy)
241
+ ? { ...(a as Row), [field]: rewriteIds(driver, vals, copy, kept) }
242
+ : a;
243
+ });
244
+ }
245
+
246
+ /** Every stored reference to `orgId` in the given databases, as the before-images of a re-point to `keptId`. Reads only. */
247
+ async function findReferences(driver: MergeDriver, dbs: readonly MergeDatabase[], orgId: unknown, keptId: unknown): Promise<MergeRefImage[]> {
248
+ const out: MergeRefImage[] = [];
249
+ const copy = idText(orgId).toLowerCase();
250
+ for (const d of dbs) {
251
+ for (const ref of ORG_REFERENCES.filter((r) => r.app === d.app)) {
252
+ if (ref.kind === "count") continue;
253
+ const base = { db: d.name, collection: ref.collection, kind: ref.kind, path: ref.path, ...(ref.field ? { field: ref.field } : {}) };
254
+ if (ref.kind === "value") {
255
+ for (const from of idForms(driver, orgId)) {
256
+ const docs = await d.db.collection(ref.collection).find({ [ref.path]: from } as Document, { projection: { _id: 1 } }).toArray();
257
+ for (const doc of docs) out.push({ ...base, docId: doc._id, from, to: inFormOf(driver, from, keptId) });
258
+ }
259
+ continue;
260
+ }
261
+ // A list or a list of sub-records is moved whole, one line per document, so a
262
+ // document holding the id in both stored forms is one compare-and-swap. Read
263
+ // without promoting numbers, so an untouched value written back keeps its type.
264
+ const docs = await d.db
265
+ .collection(ref.collection)
266
+ .find({ [refPath(ref)]: { $in: idForms(driver, orgId) } } as Document, { projection: { _id: 1, [ref.path]: 1 }, promoteValues: false })
267
+ .toArray();
268
+ for (const doc of docs) {
269
+ const before = getPath(doc as Row, ref.path);
270
+ if (!Array.isArray(before)) continue;
271
+ const after =
272
+ ref.kind === "list"
273
+ ? rewriteIds(driver, before, copy, keptId)
274
+ : ref.kind === "rows"
275
+ ? rewriteRows(driver, before, String(ref.field), copy, keptId)
276
+ : rewriteAnswers(driver, before, String(ref.field), copy, keptId);
277
+ out.push({ ...base, docId: doc._id, from: copy, to: idText(keptId).toLowerCase(), before, after });
278
+ }
279
+ }
280
+ }
281
+ return out;
282
+ }
283
+
284
+ /** How many documents still name `orgId` in the given databases (an Agency's pointer and the never-moved kinds included). */
285
+ async function countReferences(driver: MergeDriver, dbs: readonly MergeDatabase[], orgId: unknown, only?: "count"): Promise<number> {
286
+ let n = 0;
287
+ for (const d of dbs) {
288
+ for (const ref of ORG_REFERENCES.filter((r) => r.app === d.app && (!only || r.kind === only))) {
289
+ n += await d.db.collection(ref.collection).countDocuments({ [refPath(ref)]: { $in: idForms(driver, orgId) } } as Document);
290
+ }
291
+ if (d.app === "platform" && !only) {
292
+ n += await d.db.collection(AGENCIES_COLLECTION).countDocuments({ organizationId: { $in: idForms(driver, orgId) } } as Document);
293
+ }
294
+ }
295
+ return n;
296
+ }
297
+
298
+ /** Move one reference forward (`back` false) or back, only where it still holds what was there. True when it moved. */
299
+ async function repoint(db: Db, ref: MergeRefImage, back: boolean): Promise<boolean> {
300
+ const coll = db.collection(ref.collection);
301
+ if (ref.kind === "value") {
302
+ const [from, to] = back ? [ref.to, ref.from] : [ref.from, ref.to];
303
+ return (await coll.updateOne({ _id: ref.docId, [ref.path]: from } as Document, { $set: { [ref.path]: to } })).matchedCount === 1;
304
+ }
305
+ const [from, to] = back ? [ref.after, ref.before] : [ref.before, ref.after];
306
+ return (await coll.updateOne({ _id: ref.docId, [ref.path]: from } as Document, { $set: { [ref.path]: to } })).matchedCount === 1;
307
+ }
308
+
309
+ /** Whether a reference still holds what the merge wrote. */
310
+ async function holdsMerged(db: Db, ref: MergeRefImage): Promise<boolean> {
311
+ const filter = ref.kind === "value" ? { _id: ref.docId, [ref.path]: ref.to } : { _id: ref.docId, [ref.path]: ref.after };
312
+ return (await db.collection(ref.collection).countDocuments(filter as Document)) === 1;
313
+ }
314
+
315
+ // ─── One merge, as a person named it ────────────────────────────────────────
316
+
317
+ /** What a reviewer writes in the merge sheet's `approved` column. */
318
+ export const MERGE = "merge";
319
+
320
+ /** What a reviewer writes in the sheet's `different_name_ok` to merge two rows whose names differ. */
321
+ export const YES = "yes";
322
+
323
+ export interface MergeLine {
324
+ /** Sheet line (header = 1), for messages. */
325
+ line: number;
326
+ duplicateId: string;
327
+ duplicateName: string;
328
+ keptId: string;
329
+ keptName: string;
330
+ /** The line says in so many words that the two names differ and are one organization. */
331
+ differentNameOk: boolean;
332
+ }
333
+
334
+ // ─── Planning ───────────────────────────────────────────────────────────────
335
+
336
+ export interface PlannedMerge {
337
+ line: MergeLine;
338
+ /** `merge` is written; `already` is done (the copy is gone and recorded); `skip` blocks the whole apply. */
339
+ status: "merge" | "already" | "skip";
340
+ detail: string;
341
+ /** Stored names ("" when the row was not found). */
342
+ duplicateName: string;
343
+ keptName: string;
344
+ /** Whose list each row sits in (`agencyScope`), in words. */
345
+ duplicateList: string;
346
+ keptList: string;
347
+ flags: string[];
348
+ /** Present on `merge`: what {@link executeMerges} writes, and its undo. */
349
+ write?: MergeImage;
350
+ }
351
+
352
+ /**
353
+ * Read every approved line and decide. Reads only. `skip` (any one blocks the
354
+ * whole apply): either row is missing; a stored name is not the sheet's; the
355
+ * copy is a canonical singleton, an Agency's own organization (it names an
356
+ * Agency, or an Agency points at it: that is not a copy), or has programs;
357
+ * the kept row is inactive or declined, or is a unit of the copy; the two
358
+ * names differ and the line does not say `different_name_ok` = yes; the kept
359
+ * row could not be seen where the copy is used.
360
+ *
361
+ * Seen, as Thread decides it (`organizationReadableBy`, `resolveUserCommunity`):
362
+ * an Agency sees the organizations in its own list, and an organization of
363
+ * another list only when the Agency's `state` is exactly that organization's
364
+ * `community` (both non-blank; compared as stored, no trimming or case change).
365
+ * So the kept row must be in the copy's list, or the Agency whose list the
366
+ * copy is in must have a `state` equal to the kept row's `community`.
367
+ *
368
+ * @param dbs - the platform database first, then each app database the caller could open.
369
+ * @param driver - the caller's ObjectId class and EJSON (see {@link MergeDriver}).
370
+ */
371
+ export async function planMerges(
372
+ dbs: readonly MergeDatabase[],
373
+ lines: readonly MergeLine[],
374
+ driver: MergeDriver,
375
+ ): Promise<PlannedMerge[]> {
376
+ const platform = dbs[0] as MergeDatabase;
377
+ const orgs = platform.db.collection(ORGANIZATIONS_COLLECTION);
378
+ const agencies = platform.db.collection(AGENCIES_COLLECTION);
379
+ const unchecked = APP_DATABASE_KINDS.filter((k) => !dbs.some((d) => d.app === k));
380
+ const listAgency = async (org: Row): Promise<Row | null> =>
381
+ blank(org.agencyScope)
382
+ ? null
383
+ : ((await agencies.findOne({ _id: { $in: idForms(driver, org.agencyScope) } } as Document, { projection: { name: 1, state: 1 } })) as Row | null);
384
+ const listOf = async (org: Row): Promise<string> => {
385
+ if (blank(org.agencyScope)) return "in no agency's list";
386
+ const a = await listAgency(org);
387
+ return `in the list of ${a ? text(a.name) || idText(org.agencyScope) : `agency ${idText(org.agencyScope)}, which is not in this database`}`;
388
+ };
389
+ /** Whether `copyId` is the kept row's parent, or its parent's parent, and so on (a cycle or a deep chain stops the walk). */
390
+ const isUnitOf = async (kept: Row, copyId: string): Promise<boolean> => {
391
+ const seen = new Set<string>();
392
+ let parent = kept.parentOrgId;
393
+ for (let depth = 0; depth < 25 && !blank(parent); depth += 1) {
394
+ const id = idOf(driver, parent);
395
+ if (id === null || seen.has(id)) return false;
396
+ if (id === copyId) return true;
397
+ seen.add(id);
398
+ const next = (await orgs.findOne({ _id: { $in: idForms(driver, parent) } } as Document, { projection: { parentOrgId: 1 } })) as Row | null;
399
+ parent = next?.parentOrgId;
400
+ }
401
+ return false;
402
+ };
403
+ const out: PlannedMerge[] = [];
404
+ for (const line of lines) {
405
+ const one = async (id: string): Promise<Row | null> => {
406
+ const found = await orgs.find({ _id: { $in: idForms(driver, id) } } as Document).limit(2).toArray();
407
+ return found.length === 1 ? (found[0] as Row) : null;
408
+ };
409
+ const dup = await one(line.duplicateId);
410
+ const kept = await one(line.keptId);
411
+ const base = {
412
+ line,
413
+ duplicateName: dup ? text(dup.name) : "",
414
+ keptName: kept ? text(kept.name) : "",
415
+ duplicateList: dup ? await listOf(dup) : "",
416
+ keptList: kept ? await listOf(kept) : "",
417
+ };
418
+ const flags: string[] = [];
419
+ const skip = (detail: string): void => {
420
+ out.push({ ...base, status: "skip", detail, flags });
421
+ };
422
+ // The sheet reader refuses this too. It is refused here as well because the
423
+ // plan is a public call (0.69.0): a copy merged into itself would have its
424
+ // references "moved" to itself and then be deleted.
425
+ if (line.duplicateId.trim().toLowerCase() === line.keptId.trim().toLowerCase()) {
426
+ skip("the copy and the kept organization are the same row");
427
+ continue;
428
+ }
429
+ const mergedFrom = (kept?.legacy_ids as { merged_from?: unknown } | undefined)?.merged_from;
430
+ const listed = Array.isArray(mergedFrom) && mergedFrom.includes(line.duplicateId);
431
+ if (!dup && kept && listed) {
432
+ out.push({ ...base, status: "already", detail: "already merged: the copy is gone and the kept organization records its id", flags });
433
+ continue;
434
+ }
435
+ if (!dup || !kept) {
436
+ skip(`no organization has the id ${!dup ? line.duplicateId : line.keptId}`);
437
+ continue;
438
+ }
439
+ const misnamed = (
440
+ [
441
+ ["copy", line.duplicateName, base.duplicateName],
442
+ ["kept organization", line.keptName, base.keptName],
443
+ ] as const
444
+ ).find(([, onSheet, stored]) => onSheet.trim() !== stored && onSheet.trim() !== sheetText(stored).trim());
445
+ if (misnamed) {
446
+ skip(`the sheet names the ${misnamed[0]} ${JSON.stringify(misnamed[1].trim())}, the database names it ${JSON.stringify(misnamed[2])}`);
447
+ continue;
448
+ }
449
+ if (!blank(dup.canonicalKey)) {
450
+ skip("the copy is a canonical singleton (Unknown / Anonymous); never merged");
451
+ continue;
452
+ }
453
+ const pointing = await agencies.countDocuments({ organizationId: { $in: idForms(driver, dup._id) } } as Document);
454
+ if (!blank(dup.agencyId) || pointing) {
455
+ skip("the copy is an Agency's own organization (it names an Agency, or an Agency points at it): that is not a copy");
456
+ continue;
457
+ }
458
+ if (Array.isArray(dup.programs) && dup.programs.length) {
459
+ skip("the copy has programs; merging programs is not supported");
460
+ continue;
461
+ }
462
+ if (!isListedOrganization(kept as { status?: number; reviewStatus?: string })) {
463
+ skip("the kept organization is inactive or declined: nothing is merged into a row that is not offered");
464
+ continue;
465
+ }
466
+ if (await isUnitOf(kept, idText(dup._id).toLowerCase())) {
467
+ skip("the kept organization is a unit of the copy (the copy is on its chain of parent organizations)");
468
+ continue;
469
+ }
470
+ if (comparableName(dup.name) !== comparableName(kept.name)) {
471
+ if (!line.differentNameOk) {
472
+ skip(`the two names differ: write ${YES} in different_name_ok on this line if they are one organization`);
473
+ continue;
474
+ }
475
+ flags.push("the names differ; the sheet says they are one organization");
476
+ }
477
+ const sameList = !blank(kept.agencyScope) && idText(kept.agencyScope) === idText(dup.agencyScope);
478
+ const viewer = await listAgency(dup);
479
+ const state = typeof viewer?.state === "string" ? viewer.state : "";
480
+ const community = typeof kept.community === "string" ? kept.community : "";
481
+ if (!sameList && !(state !== "" && state === community)) {
482
+ skip(
483
+ `the kept organization could not be seen by the agency whose list the copy is in: the copy is ${base.duplicateList} ` +
484
+ `(that agency's state ${JSON.stringify(state)}), the kept row is ${base.keptList} (community ${JSON.stringify(community)}). ` +
485
+ "An agency sees another list's organization only when its state is exactly that organization's community. " +
486
+ "The kept row's list or community is corrected first, by a deliberate edit",
487
+ );
488
+ continue;
489
+ }
490
+ const keyed = !blank(dup.key);
491
+ if (keyed) {
492
+ flags.push(
493
+ `the copy carries the identifier ${String(dup.key)}: identifiers never move` +
494
+ `${blank(kept.key) ? " (the kept organization has none; the key sheet gives it one)" : ""}, so the copy is kept as inactive`,
495
+ );
496
+ }
497
+ const refs = await findReferences(driver, dbs, dup._id, kept._id);
498
+ const grants = await countReferences(driver, dbs, dup._id, "count");
499
+ const outcome = keyed || grants || unchecked.length ? "retire" : "delete";
500
+ const moves = new Map<string, number>();
501
+ for (const r of refs) {
502
+ const k = `${r.db} ${r.collection}.${refPath(r)}`;
503
+ moves.set(k, (moves.get(k) ?? 0) + 1);
504
+ }
505
+ const why = [
506
+ ...(unchecked.length ? [`references in ${unchecked.map((k) => `${APP_LABEL[k]}'s database`).join(" and ")} could not be checked`] : []),
507
+ ...(grants ? [`${grants} sharing grant(s) name the copy, and sharing rules are never moved`] : []),
508
+ ];
509
+ const then =
510
+ outcome === "delete"
511
+ ? "then the copy is deleted"
512
+ : `then the copy is kept as inactive${why.length ? `: ${why.join("; ")}` : ""}`;
513
+ out.push({
514
+ ...base,
515
+ status: "merge",
516
+ detail: `${moves.size ? `moves ${[...moves].map(([k, n]) => `${n} in ${k}`).join(", ")}` : "nothing points at the copy"}; ${then}`,
517
+ flags,
518
+ write: {
519
+ duplicateId: dup._id,
520
+ duplicateName: base.duplicateName,
521
+ keptId: kept._id,
522
+ keptName: base.keptName,
523
+ duplicate: dup as Document,
524
+ refs,
525
+ outcome,
526
+ addsLegacyEntry: !listed,
527
+ },
528
+ });
529
+ }
530
+ return out;
531
+ }
532
+
533
+ /** One planned line as printed: both rows by stored name and list, what moves, what happens to the copy, any flag. */
534
+ export function formatPlannedMerge(p: PlannedMerge): string {
535
+ return (
536
+ ` ${p.status.padEnd(6)} ${p.line.duplicateId} ${p.duplicateName || "(no organization)"}${p.duplicateList ? ` (${p.duplicateList})` : ""}` +
537
+ ` -> ${p.line.keptId} ${p.keptName || "(no organization)"}${p.keptList ? ` (${p.keptList})` : ""}\n` +
538
+ ` ${p.detail}${p.flags.map((f) => ` [${f}]`).join("")}`
539
+ );
540
+ }
541
+
542
+ // ─── Writing ────────────────────────────────────────────────────────────────
543
+
544
+ export interface ExecutedMerge {
545
+ merge: MergeImage;
546
+ /** `deleted` / `retired`: the line is done. `changed`: a row moved since the plan. `failed`: the database refused. */
547
+ status: "deleted" | "retired" | "changed" | "failed";
548
+ moved: number;
549
+ detail?: string;
550
+ }
551
+
552
+ /**
553
+ * Carry out each merge, one at a time: record the copy's id on the kept row,
554
+ * move each reference (only where it still holds what the plan read), then
555
+ * count what still names the copy. Nothing left and every app database
556
+ * checked: the copy is deleted. Otherwise it is marked inactive. Either
557
+ * happens only while the copy is still exactly as planned. The kept row gets
558
+ * `legacy_ids.merged_from` and nothing else: not even a new `updatedTime`.
559
+ */
560
+ export async function executeMerges(
561
+ dbs: readonly MergeDatabase[],
562
+ merges: readonly MergeImage[],
563
+ now: Date,
564
+ driver: MergeDriver,
565
+ ): Promise<ExecutedMerge[]> {
566
+ const orgs = (dbs[0] as MergeDatabase).db.collection(ORGANIZATIONS_COLLECTION);
567
+ const dbNamed = new Map(dbs.map((d) => [d.name, d.db]));
568
+ const out: ExecutedMerge[] = [];
569
+ for (const merge of merges) {
570
+ let moved = 0;
571
+ try {
572
+ const kept = await orgs.updateOne(
573
+ { _id: merge.keptId, status: { $in: [null, ORGANIZATION_STATUS.ACTIVE] }, reviewStatus: { $ne: "rejected" } } as Document,
574
+ { $addToSet: { "legacy_ids.merged_from": idText(merge.duplicateId) } },
575
+ );
576
+ if (kept.matchedCount !== 1) {
577
+ out.push({ merge, status: "changed", moved, detail: "the kept organization is gone or no longer offered since the plan; nothing was written" });
578
+ continue;
579
+ }
580
+ let stale = 0;
581
+ for (const ref of merge.refs) {
582
+ if (await repoint(dbNamed.get(ref.db) as Db, ref, false)) moved += 1;
583
+ else stale += 1;
584
+ }
585
+ const left = await countReferences(driver, dbs, merge.duplicateId);
586
+ const asPlanned = { _id: merge.duplicateId, updatedTime: merge.duplicate.updatedTime ?? null, status: merge.duplicate.status ?? null } as Document;
587
+ if (merge.outcome === "delete" && left === 0) {
588
+ const res = await orgs.deleteOne(asPlanned);
589
+ out.push(
590
+ res.deletedCount === 1
591
+ ? { merge, status: "deleted", moved }
592
+ : { merge, status: "changed", moved, detail: "the copy changed since the plan and was left as it is; its references were moved" },
593
+ );
594
+ continue;
595
+ }
596
+ const res = await orgs.updateOne(asPlanned, { $set: { status: ORGANIZATION_STATUS.INACTIVE, updatedTime: now } });
597
+ const why =
598
+ merge.outcome === "delete"
599
+ ? `${left} reference(s) still point at the copy${stale ? ` (${stale} changed since the plan)` : ""}, so it was not deleted`
600
+ : left
601
+ ? `${left} reference(s) still point at the copy`
602
+ : undefined;
603
+ out.push(
604
+ res.matchedCount === 1
605
+ ? { merge, status: "retired", moved, ...(why ? { detail: why } : {}) }
606
+ : { merge, status: "changed", moved, detail: "the copy changed since the plan and was left as it is; its references were moved" },
607
+ );
608
+ } catch (err) {
609
+ out.push({ merge, status: "failed", moved, detail: message(err) });
610
+ }
611
+ }
612
+ return out;
613
+ }
614
+
615
+ // ─── Undo ───────────────────────────────────────────────────────────────────
616
+
617
+ export interface MergeRollbackRow {
618
+ image: MergeImage;
619
+ /** `restore`: everything can be put back. `partial`: some of it. `skip`: nothing to do, or nothing safe to do. */
620
+ status: "restore" | "partial" | "skip";
621
+ detail: string;
622
+ }
623
+
624
+ /** A document compared whole, whatever order its top-level keys come back in. */
625
+ function sameDocument(driver: MergeDriver, x: Document, y: Document): boolean {
626
+ const sorted = (d: Document): Document => Object.fromEntries(Object.keys(d).sort().map((k) => [k, d[k] as unknown]));
627
+ const strict = (d: Document): string => driver.EJSON.stringify({ v: d }, { relaxed: false });
628
+ return strict(sorted(x)) === strict(sorted(y));
629
+ }
630
+
631
+ /**
632
+ * Undo each merge of a before-images file, newest first; with `dryRun`, only
633
+ * say what would happen. The copy comes back first (re-inserted exactly from
634
+ * its before-image when it was deleted; its `status` and `updatedTime`
635
+ * restored when it was marked inactive), then each reference that still holds
636
+ * what the merge wrote goes back (a list or a list of sub-records is put back
637
+ * whole, so a copy's id the merge dropped returns too), then the copy's id is
638
+ * taken off the kept row's `legacy_ids`, only when this run put it there. A
639
+ * reference somebody has changed since is left alone and counted.
640
+ *
641
+ * @param dbFor - a handle on a database of the same server, by name.
642
+ */
643
+ export async function rollbackMerges(
644
+ dbFor: (name: string) => Db,
645
+ images: MergeBeforeImages,
646
+ opts: { dryRun: boolean },
647
+ driver: MergeDriver,
648
+ ): Promise<MergeRollbackRow[]> {
649
+ const orgs = dbFor(images.db).collection(ORGANIZATIONS_COLLECTION);
650
+ const out: MergeRollbackRow[] = [];
651
+ for (const image of [...(images.merges ?? [])].reverse()) {
652
+ const said: string[] = [];
653
+ let partial = false;
654
+ const before = image.duplicate;
655
+ const now = (await orgs.findOne({ _id: image.duplicateId } as Document)) as Document | null;
656
+ const retiredHere =
657
+ !!now &&
658
+ sameDocument(driver, now, { ...before, status: ORGANIZATION_STATUS.INACTIVE, updatedTime: images.appliedTime });
659
+ if (!now) {
660
+ said.push("put the deleted copy back exactly as it was");
661
+ if (!opts.dryRun) await orgs.insertOne(before);
662
+ } else if (retiredHere) {
663
+ said.push(before.status === ORGANIZATION_STATUS.INACTIVE ? "put the copy back as it was before this run" : "make the copy active again, as it was");
664
+ if (!opts.dryRun) await orgs.replaceOne({ _id: image.duplicateId, updatedTime: images.appliedTime } as Document, before);
665
+ } else if (sameDocument(driver, now, before)) {
666
+ said.push("the copy is as it was");
667
+ } else {
668
+ partial = true;
669
+ said.push("the copy has changed since the merge: left as it is");
670
+ }
671
+ let back = 0;
672
+ let moved = 0;
673
+ for (const ref of image.refs) {
674
+ const db = dbFor(ref.db);
675
+ if (!(await holdsMerged(db, ref))) moved += 1;
676
+ else if (opts.dryRun || (await repoint(db, ref, true))) back += 1;
677
+ else moved += 1;
678
+ }
679
+ if (image.refs.length) {
680
+ said.push(`${back} of ${image.refs.length} reference(s) back to the copy${moved ? ` (${moved} changed since the merge: left alone)` : ""}`);
681
+ }
682
+ if (moved) partial = true;
683
+ const entry = idText(image.duplicateId);
684
+ const listed = image.addsLegacyEntry
685
+ ? await orgs.countDocuments({ _id: image.keptId, "legacy_ids.merged_from": entry } as Document)
686
+ : 0;
687
+ if (listed) {
688
+ said.push("take the copy's id off the kept organization's legacy_ids");
689
+ if (!opts.dryRun) {
690
+ await orgs.updateOne({ _id: image.keptId } as Document, { $pull: { "legacy_ids.merged_from": entry } } as Document);
691
+ // Leave no empty shell behind: the row had no such field before its first merge.
692
+ await orgs.updateOne({ _id: image.keptId, "legacy_ids.merged_from": { $size: 0 } } as Document, { $unset: { "legacy_ids.merged_from": "" } });
693
+ await orgs.updateOne({ _id: image.keptId, legacy_ids: {} } as Document, { $unset: { legacy_ids: "" } });
694
+ }
695
+ } else if (!image.addsLegacyEntry) {
696
+ said.push("the copy's id stays on the kept organization's legacy_ids (an earlier run put it there)");
697
+ }
698
+ const anything = !now || retiredHere || back > 0 || listed > 0;
699
+ out.push({
700
+ image,
701
+ status: !anything ? "skip" : partial ? "partial" : "restore",
702
+ detail: anything ? said.join("; ") : `nothing left to undo (${said.join("; ")})`,
703
+ });
704
+ }
705
+ return out;
706
+ }