@htilabs/platform-common-models 0.83.0 → 0.84.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.
@@ -32,13 +32,56 @@
32
32
  * app already reads as "not offered", `isListedOrganization`), and the line
33
33
  * says why.
34
34
  *
35
+ * ## Programs (0.84.0)
36
+ *
37
+ * A Program belongs to the Organization, and is stored on its row
38
+ * (`organizations.programs[]`). "Make the other objects really move in a
39
+ * merge" (Crysta, 2026-11-11): when a steward merges, the copy's program rows
40
+ * move to the kept organization, exactly as stored and with their ids
41
+ * unchanged. A program id is minted, never derived from a name, so it names
42
+ * one program wherever its row sits; everything that points at a program
43
+ * (`servicelistings.program_id`, a case's program in Thread or PAVE) names it
44
+ * beside the organization, and that reference is re-pointed above. So nothing
45
+ * that points at a program is touched, and nothing is left pointing at a
46
+ * program that is gone. The rows are appended to the kept organization's
47
+ * list in the same write that records the copy's id there. Two live programs
48
+ * that end up with the same name are both kept, as two programs (a name is
49
+ * not an identity; the plan says so in a flag). Where the agency whose list
50
+ * the copy is in cannot yet read the kept row in Thread and PAVE (see "Who is
51
+ * merging"), the flag also says it may not be able to pick the programs that
52
+ * moved; nothing is refused for it. A copy that is then kept as
53
+ * inactive keeps no programs: they are the kept organization's now. A merge
54
+ * inside one agency's own list (`agency`) still refuses a copy with programs,
55
+ * as before.
56
+ *
35
57
  * ## What it never does
36
58
  *
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).
59
+ * It never writes a fact of the kept row (its programs are added to, never
60
+ * rewritten), never moves an identifier (`key`: identifiers never change),
61
+ * never moves a sharing grant, never merges an Agency's own organization
62
+ * (that is not a copy), and never re-points a copy of an id kept inside a
63
+ * sent share, a session draft or a sealed field (see the runbook).
64
+ *
65
+ * ## Who is merging (0.84.0)
66
+ *
67
+ * The caller says who merges ({@link MergeActor}); nothing here works it out.
68
+ *
69
+ * - `steward`: HTI Labs reconciling the registry (the Admin Hub's "Merge into
70
+ * another organization", the registry tool). The registry is ONE
71
+ * platform-wide list: "Organizations should never sit inside one agency's
72
+ * own list" (Crysta, 2026-11-11), and an agency's list never blocks a
73
+ * registry action. So the pair is judged against the registry alone: both
74
+ * rows exist, the kept one is offered (active, not declined). Whose list a
75
+ * row was typed into (`agencyScope`) and its `community` refuse nothing.
76
+ * Where Thread's and PAVE's as-built per-agency read would hide the kept
77
+ * row from the agency whose list the copy is in, the plan carries a flag
78
+ * saying so, in words a steward can read; it goes when both apps read the
79
+ * one list (Thread #1228 and PAVE's twin).
80
+ * - `agency`: a merge made inside one agency's own list. The kept row must be
81
+ * readable where the copy is used, by Thread's as-built rule. This is the
82
+ * rule every caller had before 0.84.0, unchanged. No app calls it today.
83
+ *
84
+ * Every other refusal is about the data, not about lists, and holds for both.
42
85
  */
43
86
 
44
87
  /*
@@ -53,17 +96,19 @@
53
96
 
54
97
 
55
98
  import { ORGANIZATION_STATUS, isListedOrganization } from "../orgDirectory/orgRecord.js";
99
+ import { isLiveOrganizationProgram, programNameKey } from "../orgDirectory/vocabulary.js";
56
100
  import { AGENCIES_COLLECTION, ORGANIZATIONS_COLLECTION } from "../orgDirectory/read.js";
57
101
  import { directoryIdString } from "../orgDirectory/rules.js";
58
102
  import { POINTS_OF_CONTACT_COLLECTION } from "../pointsOfContact/schemas.js";
59
103
  import { SERVICE_LISTINGS_COLLECTION } from "../serviceListings/read.js";
60
- import { comparableName, sheetText } from "./support.js";
104
+ import { comparableId, comparableName, sheetText } from "./support.js";
61
105
  import type {
62
106
  MergeBeforeImages,
63
107
  MergeDbLike,
64
108
  MergeDocument,
65
109
  MergeDriver,
66
110
  MergeImage,
111
+ MergeProgramsImage,
67
112
  MergeRefImage,
68
113
  } from "./types.js";
69
114
 
@@ -77,19 +122,27 @@ const idText = (v: unknown): string => directoryIdString(v) ?? String(v);
77
122
  const HEX_24 = /^[0-9a-fA-F]{24}$/;
78
123
  const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
79
124
 
80
- /** An id's lower-case text when the value is an id (a string or an ObjectId), else null. Never a sub-record. */
125
+ /**
126
+ * An id's comparable text when the value is an id (a string or an ObjectId), else null. Never a sub-record.
127
+ * A 24-hex id is lower-cased (the form an ObjectId prints as); a text id is compared exactly as stored.
128
+ */
81
129
  const idOf = (driver: MergeDriver, v: unknown): string | null =>
82
- typeof v === "string" ? v.trim().toLowerCase() : v instanceof driver.ObjectId ? v.toHexString() : null;
130
+ typeof v === "string" ? comparableId(v) : v instanceof driver.ObjectId ? v.toHexString() : null;
83
131
 
84
132
  /** Every stored form of an id: the ObjectId and the lower-case text when it is 24-hex, else the text. */
85
133
  function idForms(driver: MergeDriver, id: unknown): unknown[] {
86
134
  const s = idText(id);
87
135
  return HEX_24.test(s) ? [new driver.ObjectId(s.toLowerCase()), s.toLowerCase()] : [s];
88
136
  }
89
- /** The kept id in the same stored form as the value it replaces. */
137
+ /**
138
+ * The kept id in the same stored form as the value it replaces. A text id is
139
+ * written exactly as the kept row stores it: before 0.84.0 it was lower-cased,
140
+ * so a reference moved to a row stored under "Org-A" named "org-a", which is
141
+ * no row.
142
+ */
90
143
  function inFormOf(driver: MergeDriver, from: unknown, keptId: unknown): unknown {
91
144
  const s = idText(keptId);
92
- return from instanceof driver.ObjectId && HEX_24.test(s) ? new driver.ObjectId(s.toLowerCase()) : s.toLowerCase();
145
+ return from instanceof driver.ObjectId && HEX_24.test(s) ? new driver.ObjectId(s.toLowerCase()) : comparableId(s);
93
146
  }
94
147
 
95
148
  /**
@@ -175,15 +228,50 @@ export interface MergeDatabase {
175
228
  db: Db;
176
229
  }
177
230
 
178
- /** A collection only that app's database has: how a mistyped database name is caught. */
231
+ /** A collection every database of that app has: how a mistyped database name is caught. */
179
232
  const APP_MARKER: Record<AppDatabaseKind, string> = { thread: "caserecords", pave: "protectedpeople" };
180
233
 
234
+ /**
235
+ * Collections ONLY PAVE's database has. Thread's database and PAVE's both
236
+ * hold `caserecords` and `protectedpeople` (each app has both models), so the
237
+ * two markers above cannot tell one from the other: before 0.84.0 PAVE's
238
+ * database named as Thread's (or the two names swapped) was accepted, each
239
+ * was searched with the other app's field names, found nothing, and a copy
240
+ * its case records still named could be deleted.
241
+ *
242
+ * A database is PAVE's when it has ANY of these, and Thread's only when it
243
+ * has NONE. Any, not one in particular: PAVE has built every model's
244
+ * collection at each start only since its index sweep (pave-2.0
245
+ * `declaredIndexSweep`, 2026-11-09); on an older build a collection exists
246
+ * only once something was saved in it. Thread names none of the three (its
247
+ * disclosure model's collection is `disclosurerecords`, no underscore).
248
+ */
249
+ const PAVE_ONLY_COLLECTIONS = ["programhousingenrollments", "disclosure_records", "reportingdestinationconfigs"] as const;
250
+
181
251
  /** Why `db` cannot be `app`'s database, or null when it can. A name that matches nothing would read as "no references". */
182
252
  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)`;
253
+ const has = async (collection: string): Promise<boolean> =>
254
+ (await db.listCollections({ name: collection }, { nameOnly: true }).toArray()).length > 0;
255
+ if (!(await has(APP_MARKER[app]))) {
256
+ return `'${name}' has no ${APP_MARKER[app]} collection, so it is not a ${APP_LABEL[app]} database (check the name)`;
257
+ }
258
+ let paves: string | null = null;
259
+ for (const c of PAVE_ONLY_COLLECTIONS) {
260
+ if (await has(c)) {
261
+ paves = c;
262
+ break;
263
+ }
264
+ }
265
+ if (app === "thread" && paves) {
266
+ return `'${name}' has a ${paves} collection, which only PAVE's database has, so it is not a Thread database (check the name)`;
267
+ }
268
+ if (app === "pave" && !paves) {
269
+ return (
270
+ `'${name}' has none of the collections only PAVE's database has (${PAVE_ONLY_COLLECTIONS.join(", ")}), ` +
271
+ "so it is not a PAVE database (check the name)"
272
+ );
273
+ }
274
+ return null;
187
275
  }
188
276
 
189
277
  const refPath = (r: Pick<OrgReference, "kind" | "path" | "field">): string =>
@@ -200,7 +288,7 @@ function getPath(doc: Row, path: string): unknown {
200
288
  * the kept id is already in it, the copy's id is dropped instead.
201
289
  */
202
290
  function rewriteIds(driver: MergeDriver, list: readonly unknown[], copy: string, kept: unknown): unknown[] {
203
- const keptHex = idText(kept).toLowerCase();
291
+ const keptHex = comparableId(idText(kept));
204
292
  let hasKept = list.some((v) => idOf(driver, v) === keptHex);
205
293
  const out: unknown[] = [];
206
294
  for (const v of list) {
@@ -246,7 +334,7 @@ function rewriteAnswers(driver: MergeDriver, answers: readonly unknown[], field:
246
334
  /** Every stored reference to `orgId` in the given databases, as the before-images of a re-point to `keptId`. Reads only. */
247
335
  async function findReferences(driver: MergeDriver, dbs: readonly MergeDatabase[], orgId: unknown, keptId: unknown): Promise<MergeRefImage[]> {
248
336
  const out: MergeRefImage[] = [];
249
- const copy = idText(orgId).toLowerCase();
337
+ const copy = comparableId(idText(orgId));
250
338
  for (const d of dbs) {
251
339
  for (const ref of ORG_REFERENCES.filter((r) => r.app === d.app)) {
252
340
  if (ref.kind === "count") continue;
@@ -274,7 +362,7 @@ async function findReferences(driver: MergeDriver, dbs: readonly MergeDatabase[]
274
362
  : ref.kind === "rows"
275
363
  ? rewriteRows(driver, before, String(ref.field), copy, keptId)
276
364
  : rewriteAnswers(driver, before, String(ref.field), copy, keptId);
277
- out.push({ ...base, docId: doc._id, from: copy, to: idText(keptId).toLowerCase(), before, after });
365
+ out.push({ ...base, docId: doc._id, from: copy, to: comparableId(idText(keptId)), before, after });
278
366
  }
279
367
  }
280
368
  }
@@ -333,6 +421,19 @@ export interface MergeLine {
333
421
 
334
422
  // ─── Planning ───────────────────────────────────────────────────────────────
335
423
 
424
+ /**
425
+ * Who is merging. `steward`: HTI Labs, acting on the one platform-wide
426
+ * registry; no agency's list refuses the pair. `agency`: a merge inside one
427
+ * agency's own list; the kept row must be readable where the copy is used
428
+ * (the only rule before 0.84.0). See "Who is merging" at the top of this file.
429
+ */
430
+ export type MergeActor = "steward" | "agency";
431
+
432
+ /** What the caller states about a plan. Required: the rules never guess who is merging. */
433
+ export interface MergePlanOptions {
434
+ mergedBy: MergeActor;
435
+ }
436
+
336
437
  export interface PlannedMerge {
337
438
  line: MergeLine;
338
439
  /** `merge` is written; `already` is done (the copy is gone and recorded); `skip` blocks the whole apply. */
@@ -355,8 +456,10 @@ export interface PlannedMerge {
355
456
  * copy is a canonical singleton, an Agency's own organization (it names an
356
457
  * Agency, or an Agency points at it: that is not a copy), or has programs;
357
458
  * 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.
459
+ * names differ and the line does not say `different_name_ok` = yes; and, only
460
+ * when an `agency` merges ({@link MergeActor}), the kept row could not be seen
461
+ * where the copy is used. A `steward`'s merge is never refused for that: the
462
+ * registry is one platform-wide list, and the plan carries a flag instead.
360
463
  *
361
464
  * Seen, as Thread decides it (`organizationReadableBy`, `resolveUserCommunity`):
362
465
  * an Agency sees the organizations in its own list, and an organization of
@@ -367,12 +470,18 @@ export interface PlannedMerge {
367
470
  *
368
471
  * @param dbs - the platform database first, then each app database the caller could open.
369
472
  * @param driver - the caller's ObjectId class and EJSON (see {@link MergeDriver}).
473
+ * @param opts - who is merging ({@link MergePlanOptions}); stated by the caller, never inferred.
370
474
  */
371
475
  export async function planMerges(
372
476
  dbs: readonly MergeDatabase[],
373
477
  lines: readonly MergeLine[],
374
478
  driver: MergeDriver,
479
+ opts: MergePlanOptions,
375
480
  ): Promise<PlannedMerge[]> {
481
+ if (opts?.mergedBy !== "steward" && opts?.mergedBy !== "agency") {
482
+ throw new Error("planMerges: say who is merging (mergedBy: 'steward' or 'agency')");
483
+ }
484
+ const byAgency = opts.mergedBy === "agency";
376
485
  const platform = dbs[0] as MergeDatabase;
377
486
  const orgs = platform.db.collection(ORGANIZATIONS_COLLECTION);
378
487
  const agencies = platform.db.collection(AGENCIES_COLLECTION);
@@ -422,7 +531,7 @@ export async function planMerges(
422
531
  // The sheet reader refuses this too. It is refused here as well because the
423
532
  // plan is a public call (0.69.0): a copy merged into itself would have its
424
533
  // references "moved" to itself and then be deleted.
425
- if (line.duplicateId.trim().toLowerCase() === line.keptId.trim().toLowerCase()) {
534
+ if (comparableId(line.duplicateId) === comparableId(line.keptId)) {
426
535
  skip("the copy and the kept organization are the same row");
427
536
  continue;
428
537
  }
@@ -455,15 +564,49 @@ export async function planMerges(
455
564
  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
565
  continue;
457
566
  }
567
+ // A copy's programs move with it when a steward merges (see "Programs" at the top of this file).
568
+ let programs: MergeProgramsImage | undefined;
458
569
  if (Array.isArray(dup.programs) && dup.programs.length) {
459
- skip("the copy has programs; merging programs is not supported");
460
- continue;
570
+ if (byAgency) {
571
+ skip("the copy has programs; merging programs is not supported");
572
+ continue;
573
+ }
574
+ // Read without promoting numbers, so a row written back (the undo) or compared keeps each value's stored type.
575
+ const stored = async (id: unknown): Promise<unknown> =>
576
+ ((await orgs.findOne({ _id: id } as Document, { projection: { programs: 1 }, promoteValues: false })) as Row | null)?.programs;
577
+ const [keptRows, dupRows] = [await stored(kept._id), await stored(dup._id)];
578
+ if (!Array.isArray(dupRows) || dupRows.length !== dup.programs.length) {
579
+ skip("the copy's programs changed while the plan was read; plan again");
580
+ continue;
581
+ }
582
+ const keptHad = Array.isArray(keptRows);
583
+ const keptBefore = keptHad ? (keptRows as unknown[]) : [];
584
+ const idOfProgram = (r: unknown): string => (r && typeof r === "object" ? text((r as Row).programId) : "");
585
+ const keptIds = new Set(keptBefore.map(idOfProgram).filter(Boolean));
586
+ const twin = dupRows.map(idOfProgram).find((id) => id && keptIds.has(id));
587
+ if (twin) {
588
+ skip(`a program of the copy has the same id as a program of the kept organization (${twin}); two programs cannot share an id`);
589
+ continue;
590
+ }
591
+ programs = { keptHad, keptBefore, moved: dupRows as unknown[] };
592
+ const liveName = (r: unknown): string => {
593
+ const row = r && typeof r === "object" ? (r as Row) : {};
594
+ return typeof row.name === "string" && isLiveOrganizationProgram(row as { status?: string; reviewStatus?: string }) ? programNameKey(row.name) : "";
595
+ };
596
+ const keptNames = new Set(keptBefore.map(liveName).filter(Boolean));
597
+ const same = programs.moved.filter((r) => liveName(r) && keptNames.has(liveName(r))).map((r) => text((r as Row).name));
598
+ if (same.length) {
599
+ flags.push(
600
+ `${same.length} program(s) of the copy have the name of a live program of the kept organization (${same.join(", ")}); ` +
601
+ "both are kept, as two programs",
602
+ );
603
+ }
461
604
  }
462
605
  if (!isListedOrganization(kept as { status?: number; reviewStatus?: string })) {
463
606
  skip("the kept organization is inactive or declined: nothing is merged into a row that is not offered");
464
607
  continue;
465
608
  }
466
- if (await isUnitOf(kept, idText(dup._id).toLowerCase())) {
609
+ if (await isUnitOf(kept, comparableId(idText(dup._id)))) {
467
610
  skip("the kept organization is a unit of the copy (the copy is on its chain of parent organizations)");
468
611
  continue;
469
612
  }
@@ -479,13 +622,26 @@ export async function planMerges(
479
622
  const state = typeof viewer?.state === "string" ? viewer.state : "";
480
623
  const community = typeof kept.community === "string" ? kept.community : "";
481
624
  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;
625
+ if (byAgency) {
626
+ skip(
627
+ `the kept organization could not be seen by the agency whose list the copy is in: the copy is ${base.duplicateList} ` +
628
+ `(that agency's state ${JSON.stringify(state)}), the kept row is ${base.keptList} (community ${JSON.stringify(community)}). ` +
629
+ "An agency sees another list's organization only when its state is exactly that organization's community. " +
630
+ "The kept row's list or community is corrected first, by a deliberate edit",
631
+ );
632
+ continue;
633
+ }
634
+ // A steward's merge is judged against the one registry, so this refuses nothing. Where the copy sits in an
635
+ // agency's list, that agency's users read the kept row through Thread's and PAVE's as-built per-agency
636
+ // rule until both apps read the one list: said, so the steward knows what they will see meanwhile.
637
+ if (viewer) {
638
+ // With programs it is more than a name: that agency's program pickers read the kept row the same way.
639
+ flags.push(
640
+ `until Thread and PAVE show every agency the one organization list, ${text(viewer.name) || "the agency that added the copy"} ` +
641
+ "may not see the kept organization's name on its records that move" +
642
+ (programs ? `, or pick the ${programs.moved.length} program(s) that move to it` : ""),
643
+ );
644
+ }
489
645
  }
490
646
  const keyed = !blank(dup.key);
491
647
  if (keyed) {
@@ -502,6 +658,16 @@ export async function planMerges(
502
658
  const k = `${r.db} ${r.collection}.${refPath(r)}`;
503
659
  moves.set(k, (moves.get(k) ?? 0) + 1);
504
660
  }
661
+ // The copy's programs move even when an app's database could not be checked, and the copy then stays (inactive)
662
+ // for that database's sake. A record there that names the copy with one of its programs keeps naming the copy:
663
+ // said, with the remedy, so nobody takes the merge for finished.
664
+ if (programs && unchecked.length) {
665
+ const where = unchecked.map((k) => `${APP_LABEL[k]}'s database`).join(" and ");
666
+ flags.push(
667
+ `${where} could not be checked: a record there that names the copy with one of its programs still names the copy, ` +
668
+ "while the programs are the kept organization's now; run the merge again with every database to move those records",
669
+ );
670
+ }
505
671
  const why = [
506
672
  ...(unchecked.length ? [`references in ${unchecked.map((k) => `${APP_LABEL[k]}'s database`).join(" and ")} could not be checked`] : []),
507
673
  ...(grants ? [`${grants} sharing grant(s) name the copy, and sharing rules are never moved`] : []),
@@ -513,7 +679,9 @@ export async function planMerges(
513
679
  out.push({
514
680
  ...base,
515
681
  status: "merge",
516
- detail: `${moves.size ? `moves ${[...moves].map(([k, n]) => `${n} in ${k}`).join(", ")}` : "nothing points at the copy"}; ${then}`,
682
+ detail:
683
+ `${moves.size ? `moves ${[...moves].map(([k, n]) => `${n} in ${k}`).join(", ")}` : "nothing points at the copy"}; ` +
684
+ `${programs ? `its ${programs.moved.length} program(s) move to the kept organization; ` : ""}${then}`,
517
685
  flags,
518
686
  write: {
519
687
  duplicateId: dup._id,
@@ -524,6 +692,7 @@ export async function planMerges(
524
692
  refs,
525
693
  outcome,
526
694
  addsLegacyEntry: !listed,
695
+ ...(programs ? { programs } : {}),
527
696
  },
528
697
  });
529
698
  }
@@ -541,6 +710,9 @@ export function formatPlannedMerge(p: PlannedMerge): string {
541
710
 
542
711
  // ─── Writing ────────────────────────────────────────────────────────────────
543
712
 
713
+ /** Said when a copy that changed under the merge could not be deleted or retired after its programs were added to the kept row. */
714
+ const COPY_KEEPS_PROGRAMS = ", and its programs were added to the kept organization while the copy still lists them: undo this merge and run it again";
715
+
544
716
  export interface ExecutedMerge {
545
717
  merge: MergeImage;
546
718
  /** `deleted` / `retired`: the line is done. `changed`: a row moved since the plan. `failed`: the database refused. */
@@ -555,7 +727,9 @@ export interface ExecutedMerge {
555
727
  * count what still names the copy. Nothing left and every app database
556
728
  * checked: the copy is deleted. Otherwise it is marked inactive. Either
557
729
  * 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`.
730
+ * `legacy_ids.merged_from` and, when the copy has programs, those rows added
731
+ * to the end of its own (in the one write, and only while its programs are
732
+ * still as planned): nothing else, not even a new `updatedTime`.
559
733
  */
560
734
  export async function executeMerges(
561
735
  dbs: readonly MergeDatabase[],
@@ -569,12 +743,29 @@ export async function executeMerges(
569
743
  for (const merge of merges) {
570
744
  let moved = 0;
571
745
  try {
746
+ const programs = merge.programs;
572
747
  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) } },
748
+ {
749
+ _id: merge.keptId,
750
+ status: { $in: [null, ORGANIZATION_STATUS.ACTIVE] },
751
+ reviewStatus: { $ne: "rejected" },
752
+ // The copy's programs join the kept row's only while that list is still exactly as the plan read it
753
+ // (`null` matches a row that stores no list).
754
+ ...(programs ? { programs: programs.keptHad ? programs.keptBefore : null } : {}),
755
+ } as Document,
756
+ {
757
+ $addToSet: { "legacy_ids.merged_from": idText(merge.duplicateId) },
758
+ // Added to the end: the kept row's own program rows are not rewritten, not even re-typed.
759
+ ...(programs ? (programs.keptHad ? { $push: { programs: { $each: programs.moved } } } : { $set: { programs: programs.moved } }) : {}),
760
+ },
575
761
  );
576
762
  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" });
763
+ out.push({
764
+ merge,
765
+ status: "changed",
766
+ moved,
767
+ detail: `the kept organization is gone or no longer offered${programs ? ", or its programs changed," : ""} since the plan; nothing was written`,
768
+ });
578
769
  continue;
579
770
  }
580
771
  let stale = 0;
@@ -589,11 +780,12 @@ export async function executeMerges(
589
780
  out.push(
590
781
  res.deletedCount === 1
591
782
  ? { 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" },
783
+ : { merge, status: "changed", moved, detail: `the copy changed since the plan and was left as it is; its references were moved${programs ? COPY_KEEPS_PROGRAMS : ""}` },
593
784
  );
594
785
  continue;
595
786
  }
596
- const res = await orgs.updateOne(asPlanned, { $set: { status: ORGANIZATION_STATUS.INACTIVE, updatedTime: now } });
787
+ // A copy kept as inactive keeps no programs: they are the kept organization's now, under the same ids.
788
+ const res = await orgs.updateOne(asPlanned, { $set: { status: ORGANIZATION_STATUS.INACTIVE, updatedTime: now, ...(programs ? { programs: [] } : {}) } });
597
789
  const why =
598
790
  merge.outcome === "delete"
599
791
  ? `${left} reference(s) still point at the copy${stale ? ` (${stale} changed since the plan)` : ""}, so it was not deleted`
@@ -603,7 +795,7 @@ export async function executeMerges(
603
795
  out.push(
604
796
  res.matchedCount === 1
605
797
  ? { 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" },
798
+ : { merge, status: "changed", moved, detail: `the copy changed since the plan and was left as it is; its references were moved${programs ? COPY_KEEPS_PROGRAMS : ""}` },
607
799
  );
608
800
  } catch (err) {
609
801
  out.push({ merge, status: "failed", moved, detail: message(err) });
@@ -653,9 +845,18 @@ export async function rollbackMerges(
653
845
  let partial = false;
654
846
  const before = image.duplicate;
655
847
  const now = (await orgs.findOne({ _id: image.duplicateId } as Document)) as Document | null;
848
+ const programs = image.programs;
656
849
  const retiredHere =
657
850
  !!now &&
658
- sameDocument(driver, now, { ...before, status: ORGANIZATION_STATUS.INACTIVE, updatedTime: images.appliedTime });
851
+ sameDocument(driver, now, {
852
+ ...before,
853
+ status: ORGANIZATION_STATUS.INACTIVE,
854
+ updatedTime: images.appliedTime,
855
+ // A copy the merge kept as inactive was left with no programs (they moved).
856
+ ...(programs ? { programs: [] } : {}),
857
+ });
858
+ // True once the copy is back as it was before the merge (its programs included).
859
+ let copyBack = true;
659
860
  if (!now) {
660
861
  said.push("put the deleted copy back exactly as it was");
661
862
  if (!opts.dryRun) await orgs.insertOne(before);
@@ -666,6 +867,7 @@ export async function rollbackMerges(
666
867
  said.push("the copy is as it was");
667
868
  } else {
668
869
  partial = true;
870
+ copyBack = false;
669
871
  said.push("the copy has changed since the merge: left as it is");
670
872
  }
671
873
  let back = 0;
@@ -680,6 +882,29 @@ export async function rollbackMerges(
680
882
  said.push(`${back} of ${image.refs.length} reference(s) back to the copy${moved ? ` (${moved} changed since the merge: left alone)` : ""}`);
681
883
  }
682
884
  if (moved) partial = true;
885
+ // The copy's programs come off the kept row, only while its list is still exactly as the merge left it.
886
+ let programsBack = false;
887
+ if (programs) {
888
+ const merged = [...programs.keptBefore, ...programs.moved];
889
+ const holds = (await orgs.countDocuments({ _id: image.keptId, programs: merged } as Document)) === 1;
890
+ const asBefore = (await orgs.countDocuments({ _id: image.keptId, programs: programs.keptHad ? programs.keptBefore : null } as Document)) === 1;
891
+ if (holds) {
892
+ programsBack = true;
893
+ said.push(`take the copy's ${programs.moved.length} program(s) off the kept organization`);
894
+ if (!opts.dryRun) {
895
+ await orgs.updateOne(
896
+ { _id: image.keptId, programs: merged } as Document,
897
+ programs.keptHad ? { $set: { programs: programs.keptBefore } } : { $unset: { programs: "" } },
898
+ );
899
+ }
900
+ } else if (!asBefore) {
901
+ partial = true;
902
+ said.push(
903
+ "the kept organization's programs have changed since the merge: left as they are" +
904
+ (copyBack ? " (the copy has its programs back too, so the same program ids are on both organizations until one list is corrected)" : ""),
905
+ );
906
+ }
907
+ }
683
908
  const entry = idText(image.duplicateId);
684
909
  const listed = image.addsLegacyEntry
685
910
  ? await orgs.countDocuments({ _id: image.keptId, "legacy_ids.merged_from": entry } as Document)
@@ -695,7 +920,7 @@ export async function rollbackMerges(
695
920
  } else if (!image.addsLegacyEntry) {
696
921
  said.push("the copy's id stays on the kept organization's legacy_ids (an earlier run put it there)");
697
922
  }
698
- const anything = !now || retiredHere || back > 0 || listed > 0;
923
+ const anything = !now || retiredHere || back > 0 || listed > 0 || programsBack;
699
924
  out.push({
700
925
  image,
701
926
  status: !anything ? "skip" : partial ? "partial" : "restore",
@@ -15,6 +15,16 @@ export function comparableName(value: unknown): string {
15
15
  .replace(/^the /, "");
16
16
  }
17
17
 
18
+ /**
19
+ * An organization id as text, comparable: a 24-hex database id in lower case
20
+ * (the form an ObjectId prints as), any other text id exactly as stored. A
21
+ * text id is never case-folded: "Org-A" and "org-a" are two rows.
22
+ */
23
+ export function comparableId(value: string): string {
24
+ const s = value.trim();
25
+ return /^[0-9a-fA-F]{24}$/.test(s) ? s.toLowerCase() : s;
26
+ }
27
+
18
28
  /** A spreadsheet must not evaluate an org name as a formula. */
19
29
  export const sheetText = (v: unknown): string => {
20
30
  const s = typeof v === "string" ? v : v == null ? "" : String(v);
@@ -77,6 +77,24 @@ export interface MergeImage {
77
77
  outcome: "delete" | "retire";
78
78
  /** Whether this run adds the copy's id to the kept Org's `legacy_ids.merged_from` (false on a second run). The undo removes it only then. */
79
79
  addsLegacyEntry: boolean;
80
+ /**
81
+ * Present when the copy's programs move to the kept Org (a steward's merge, 0.84.0): the kept Org's
82
+ * `programs` exactly as stored before the merge and the copy's rows exactly as stored, in order. The merge adds
83
+ * the copy's rows to the end of the kept Org's list, ids unchanged.
84
+ */
85
+ programs?: MergeProgramsImage;
86
+ }
87
+
88
+ /**
89
+ * The copy's `programs[]` rows moved to the kept Org, and what the kept Org's
90
+ * list was. Both are read without promoting numbers, so a value written back
91
+ * keeps its stored type.
92
+ */
93
+ export interface MergeProgramsImage {
94
+ /** False when the kept Org stored no list (the field absent, or not a list): the merge creates it, the undo removes it. */
95
+ keptHad: boolean;
96
+ keptBefore: unknown[];
97
+ moved: unknown[];
80
98
  }
81
99
 
82
100
  /**
@@ -233,18 +233,18 @@ type SectionQuestionRef = InferRawDocType<typeof sectionQuestionRefSchema>;
233
233
  declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
234
234
  _id: false;
235
235
  }, {
236
- type: "tip" | "warning" | "prompt";
237
236
  text: string;
238
- }, mongoose.Document<unknown, {}, {
239
237
  type: "tip" | "warning" | "prompt";
238
+ }, mongoose.Document<unknown, {}, {
240
239
  text: string;
240
+ type: "tip" | "warning" | "prompt";
241
241
  }, {
242
242
  id: string;
243
243
  }, mongoose.MergeType<mongoose.DefaultSchemaOptions, {
244
244
  _id: false;
245
245
  }>> & Omit<{
246
- type: "tip" | "warning" | "prompt";
247
246
  text: string;
247
+ type: "tip" | "warning" | "prompt";
248
248
  } & {
249
249
  _id: mongoose.Types.ObjectId;
250
250
  } & {
@@ -252,8 +252,8 @@ declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any
252
252
  }, "id"> & {
253
253
  id: string;
254
254
  }, unknown, {
255
- type: "tip" | "warning" | "prompt";
256
255
  text: string;
256
+ type: "tip" | "warning" | "prompt";
257
257
  } & {
258
258
  _id: mongoose.Types.ObjectId;
259
259
  } & {
@@ -294,18 +294,18 @@ declare const sectionSchemaDefinition: {
294
294
  type: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
295
295
  _id: false;
296
296
  }, {
297
- type: "tip" | "warning" | "prompt";
298
297
  text: string;
299
- }, mongoose.Document<unknown, {}, {
300
298
  type: "tip" | "warning" | "prompt";
299
+ }, mongoose.Document<unknown, {}, {
301
300
  text: string;
301
+ type: "tip" | "warning" | "prompt";
302
302
  }, {
303
303
  id: string;
304
304
  }, mongoose.MergeType<mongoose.DefaultSchemaOptions, {
305
305
  _id: false;
306
306
  }>> & Omit<{
307
- type: "tip" | "warning" | "prompt";
308
307
  text: string;
308
+ type: "tip" | "warning" | "prompt";
309
309
  } & {
310
310
  _id: mongoose.Types.ObjectId;
311
311
  } & {
@@ -313,8 +313,8 @@ declare const sectionSchemaDefinition: {
313
313
  }, "id"> & {
314
314
  id: string;
315
315
  }, unknown, {
316
- type: "tip" | "warning" | "prompt";
317
316
  text: string;
317
+ type: "tip" | "warning" | "prompt";
318
318
  } & {
319
319
  _id: mongoose.Types.ObjectId;
320
320
  } & {