@htilabs/platform-common-models 0.67.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,282 @@
1
+ /**
2
+ * What a merge saves before it writes: everything its undo needs.
3
+ */
4
+ /** A stored document, as the driver hands it back. */
5
+ type MergeDocument = Record<string, any>;
6
+ /**
7
+ * The caller's BSON: the ObjectId class its driver stores and reads, and its
8
+ * EJSON. Passed in so this package imports neither mongoose nor the driver
9
+ * (with `mongodb`: `{ ObjectId, EJSON: BSON.EJSON }`; with mongoose:
10
+ * `mongoose.mongo.ObjectId` and `mongoose.mongo.BSON.EJSON`). An id built with another copy of the class would not match
11
+ * `instanceof` on the values the caller's driver returns.
12
+ */
13
+ interface MergeDriver {
14
+ ObjectId: {
15
+ new (hex: string): {
16
+ toHexString(): string;
17
+ };
18
+ };
19
+ EJSON: {
20
+ stringify(value: any, options?: {
21
+ relaxed?: boolean;
22
+ }): string;
23
+ };
24
+ }
25
+ interface MergeCursorLike {
26
+ limit(n: number): MergeCursorLike;
27
+ sort(spec: any): MergeCursorLike;
28
+ toArray(): Promise<any[]>;
29
+ }
30
+ /** The slice of a driver `Collection` a merge uses. */
31
+ interface MergeCollectionLike {
32
+ find(filter: any, options?: any): MergeCursorLike;
33
+ findOne(filter: any, options?: any): Promise<any>;
34
+ countDocuments(filter?: any): Promise<number>;
35
+ updateOne(filter: any, update: any): Promise<{
36
+ matchedCount: number;
37
+ }>;
38
+ replaceOne(filter: any, replacement: any): Promise<unknown>;
39
+ deleteOne(filter: any): Promise<{
40
+ deletedCount: number;
41
+ }>;
42
+ insertOne(doc: any): Promise<unknown>;
43
+ }
44
+ /** The slice of a driver `Db` a merge uses: a `mongodb` `Db` or a mongoose connection's `.db` fits. */
45
+ interface MergeDbLike {
46
+ collection(name: string): MergeCollectionLike;
47
+ listCollections(filter?: any, options?: any): {
48
+ toArray(): Promise<any[]>;
49
+ };
50
+ }
51
+ type Document = MergeDocument;
52
+ /** One stored reference a merge moves from the copy to the kept Org (`orgMerge.ts`). */
53
+ interface MergeRefImage {
54
+ /** The database the document is in (the platform database, or an app's own on the same server). */
55
+ db: string;
56
+ collection: string;
57
+ /**
58
+ * `value`: `path` holds the id. `list`: `path` is a list of ids. `rows`: `path` is a list of sub-records, `field`
59
+ * holds the id. `answers`: `path` is a list of form answers, `field` in each is a list of values.
60
+ */
61
+ kind: "value" | "list" | "rows" | "answers";
62
+ path: string;
63
+ field?: string;
64
+ docId: unknown;
65
+ /** On `value`: the copy's id exactly as stored, and the kept Org's id in the same stored form. Otherwise the two ids as text. */
66
+ from: unknown;
67
+ to: unknown;
68
+ /** On every other kind: the whole list at `path` before the merge, and as the merge leaves it. */
69
+ before?: unknown[];
70
+ after?: unknown[];
71
+ }
72
+ /** One copy folded into the Org that is kept: everything the undo needs. Written before the merge is. */
73
+ interface MergeImage {
74
+ duplicateId: unknown;
75
+ duplicateName: string;
76
+ keptId: unknown;
77
+ keptName: string;
78
+ /** The copy's row exactly as stored before the merge. The undo re-inserts it. */
79
+ duplicate: Document;
80
+ refs: MergeRefImage[];
81
+ /** What was planned for the copy once its references had moved. */
82
+ outcome: "delete" | "retire";
83
+ /** 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. */
84
+ addsLegacyEntry: boolean;
85
+ }
86
+ /**
87
+ * The saved record of a run of merges, as the undo reads it. The registry
88
+ * fill's before-images file is one (`FillBeforeImages`); the Platform's Admin
89
+ * Hub stores one per merge.
90
+ */
91
+ interface MergeBeforeImages {
92
+ /** The platform database the merges ran in. */
93
+ db: string;
94
+ /** The `updatedTime` the run stamped on every row it wrote. */
95
+ appliedTime: Date;
96
+ merges?: MergeImage[];
97
+ }
98
+
99
+ /** A name reduced for comparison: case, punctuation and a leading "the" dropped. */
100
+ declare function comparableName(value: unknown): string;
101
+ /** A spreadsheet must not evaluate an org name as a formula. */
102
+ declare const sheetText: (v: unknown) => string;
103
+
104
+ /**
105
+ * @htilabs/platform-common-models — folding a copy into the real organization
106
+ *
107
+ * The logic behind `fill-org-registry --apply-merges`. Runbook:
108
+ * `scripts/FILL_ORG_REGISTRY_RUNBOOK.md`, "Folding a copy into the real
109
+ * organization".
110
+ *
111
+ * ## Why
112
+ *
113
+ * One record per real-world organization (UDD Org Data Object, 2026-10-02).
114
+ * Where the same organization was typed in twice, the steward (HTI Labs)
115
+ * reconciles the two by hand: a person names the copy and the row that is
116
+ * kept. Nothing here works out which rows are copies.
117
+ *
118
+ * ## What a merge is (ruled 2026-10-20, the prototype's ORG-MERGE)
119
+ *
120
+ * Pure re-pointing. Every stored reference to the copy's `_id` is changed to
121
+ * the kept organization's `_id`. Nothing on the kept row is combined or
122
+ * rewritten: not its name, type, VSP answer, list or programs, and no
123
+ * Account's sharing rule. The copy is then deleted, and its id is recorded on
124
+ * the kept row as `legacy_ids.merged_from`, so an old reference found later
125
+ * can be traced.
126
+ *
127
+ * ## Where references live
128
+ *
129
+ * {@link ORG_REFERENCES} is the list, read from the models of this package,
130
+ * Thread, PAVE 2.0, the Platform app and auth (2026-11-10). Thread and PAVE
131
+ * keep their case records in databases of their own. The copy is deleted only
132
+ * when nothing in the platform database points at it AND every Thread and
133
+ * PAVE database was named on the command line and nothing there points at it
134
+ * either. Otherwise the copy stays, marked inactive (`status` 2, which every
135
+ * app already reads as "not offered", `isListedOrganization`), and the line
136
+ * says why.
137
+ *
138
+ * ## What it never does
139
+ *
140
+ * It never writes a fact of the kept row, never moves an identifier (`key`:
141
+ * identifiers never change), never moves a sharing grant, never merges an
142
+ * Agency's own organization (that is not a copy) or a copy that has programs,
143
+ * and never re-points a copy of an id kept inside a sent share, a session
144
+ * draft or a sealed field (see the runbook).
145
+ */
146
+
147
+ type Db = MergeDbLike;
148
+ /**
149
+ * Thread's development sample rows (`apps/api/src/seed/index.ts`: the
150
+ * "Thread Prototype Agency" and its organizations, ids `64e4ff1c2a7dcd9cb5f4a0xx`
151
+ * and `…a1xx`). Some reached production. They are never a kept row or a copy.
152
+ */
153
+ declare const THREAD_SAMPLE_ID_PREFIX = "64e4ff1c2a7dcd9cb5f4a";
154
+ /** Which database a reference lives in: the platform database, or an app's own. */
155
+ type ReferenceApp = "platform" | "thread" | "pave";
156
+ declare const APP_LABEL: Record<ReferenceApp, string>;
157
+ interface OrgReference {
158
+ app: ReferenceApp;
159
+ collection: string;
160
+ /**
161
+ * `value`: `path` holds the id. `list`: `path` is a list of ids. `rows`:
162
+ * `path` is a list of sub-records and `field` in each holds the id.
163
+ * `answers`: `path` is a list of form answers and `field` in each is a list
164
+ * of values, any of which may be the id. `count`: counted, never moved: a
165
+ * copy it names is kept, not deleted.
166
+ */
167
+ kind: MergeRefImage["kind"] | "count";
168
+ path: string;
169
+ field?: string;
170
+ /** Who writes it, for the runbook's table. */
171
+ writtenBy: string;
172
+ }
173
+ /**
174
+ * Every place an organization's `_id` is stored, from the code (2026-11-10).
175
+ * `agencies.organizationId` is not here: an organization an Agency points at
176
+ * is that Agency's own and is never merged. A reference by an Org's `key`
177
+ * (the Platform app's sharing-rule attachments) is not here either: a merge
178
+ * moves ids, and identifiers never move. Program ids (`programs[].programId`)
179
+ * are not here: a copy with programs is refused.
180
+ */
181
+ declare const ORG_REFERENCES: readonly OrgReference[];
182
+ /** The apps that keep references in a database of their own. A copy is deleted only when each was checked. */
183
+ declare const APP_DATABASE_KINDS: readonly ["thread", "pave"];
184
+ type AppDatabaseKind = (typeof APP_DATABASE_KINDS)[number];
185
+ /** One database a merge reads and re-points in. */
186
+ interface MergeDatabase {
187
+ app: ReferenceApp;
188
+ name: string;
189
+ db: Db;
190
+ }
191
+ /** Why `db` cannot be `app`'s database, or null when it can. A name that matches nothing would read as "no references". */
192
+ declare function appDatabaseProblem(app: AppDatabaseKind, name: string, db: Db): Promise<string | null>;
193
+ /** What a reviewer writes in the merge sheet's `approved` column. */
194
+ declare const MERGE = "merge";
195
+ /** What a reviewer writes in the sheet's `different_name_ok` to merge two rows whose names differ. */
196
+ declare const YES = "yes";
197
+ interface MergeLine {
198
+ /** Sheet line (header = 1), for messages. */
199
+ line: number;
200
+ duplicateId: string;
201
+ duplicateName: string;
202
+ keptId: string;
203
+ keptName: string;
204
+ /** The line says in so many words that the two names differ and are one organization. */
205
+ differentNameOk: boolean;
206
+ }
207
+ interface PlannedMerge {
208
+ line: MergeLine;
209
+ /** `merge` is written; `already` is done (the copy is gone and recorded); `skip` blocks the whole apply. */
210
+ status: "merge" | "already" | "skip";
211
+ detail: string;
212
+ /** Stored names ("" when the row was not found). */
213
+ duplicateName: string;
214
+ keptName: string;
215
+ /** Whose list each row sits in (`agencyScope`), in words. */
216
+ duplicateList: string;
217
+ keptList: string;
218
+ flags: string[];
219
+ /** Present on `merge`: what {@link executeMerges} writes, and its undo. */
220
+ write?: MergeImage;
221
+ }
222
+ /**
223
+ * Read every approved line and decide. Reads only. `skip` (any one blocks the
224
+ * whole apply): either row is missing; a stored name is not the sheet's; the
225
+ * copy is a canonical singleton, an Agency's own organization (it names an
226
+ * Agency, or an Agency points at it: that is not a copy), or has programs;
227
+ * the kept row is inactive or declined, or is a unit of the copy; the two
228
+ * names differ and the line does not say `different_name_ok` = yes; the kept
229
+ * row could not be seen where the copy is used.
230
+ *
231
+ * Seen, as Thread decides it (`organizationReadableBy`, `resolveUserCommunity`):
232
+ * an Agency sees the organizations in its own list, and an organization of
233
+ * another list only when the Agency's `state` is exactly that organization's
234
+ * `community` (both non-blank; compared as stored, no trimming or case change).
235
+ * So the kept row must be in the copy's list, or the Agency whose list the
236
+ * copy is in must have a `state` equal to the kept row's `community`.
237
+ *
238
+ * @param dbs - the platform database first, then each app database the caller could open.
239
+ * @param driver - the caller's ObjectId class and EJSON (see {@link MergeDriver}).
240
+ */
241
+ declare function planMerges(dbs: readonly MergeDatabase[], lines: readonly MergeLine[], driver: MergeDriver): Promise<PlannedMerge[]>;
242
+ /** One planned line as printed: both rows by stored name and list, what moves, what happens to the copy, any flag. */
243
+ declare function formatPlannedMerge(p: PlannedMerge): string;
244
+ interface ExecutedMerge {
245
+ merge: MergeImage;
246
+ /** `deleted` / `retired`: the line is done. `changed`: a row moved since the plan. `failed`: the database refused. */
247
+ status: "deleted" | "retired" | "changed" | "failed";
248
+ moved: number;
249
+ detail?: string;
250
+ }
251
+ /**
252
+ * Carry out each merge, one at a time: record the copy's id on the kept row,
253
+ * move each reference (only where it still holds what the plan read), then
254
+ * count what still names the copy. Nothing left and every app database
255
+ * checked: the copy is deleted. Otherwise it is marked inactive. Either
256
+ * happens only while the copy is still exactly as planned. The kept row gets
257
+ * `legacy_ids.merged_from` and nothing else: not even a new `updatedTime`.
258
+ */
259
+ declare function executeMerges(dbs: readonly MergeDatabase[], merges: readonly MergeImage[], now: Date, driver: MergeDriver): Promise<ExecutedMerge[]>;
260
+ interface MergeRollbackRow {
261
+ image: MergeImage;
262
+ /** `restore`: everything can be put back. `partial`: some of it. `skip`: nothing to do, or nothing safe to do. */
263
+ status: "restore" | "partial" | "skip";
264
+ detail: string;
265
+ }
266
+ /**
267
+ * Undo each merge of a before-images file, newest first; with `dryRun`, only
268
+ * say what would happen. The copy comes back first (re-inserted exactly from
269
+ * its before-image when it was deleted; its `status` and `updatedTime`
270
+ * restored when it was marked inactive), then each reference that still holds
271
+ * what the merge wrote goes back (a list or a list of sub-records is put back
272
+ * whole, so a copy's id the merge dropped returns too), then the copy's id is
273
+ * taken off the kept row's `legacy_ids`, only when this run put it there. A
274
+ * reference somebody has changed since is left alone and counted.
275
+ *
276
+ * @param dbFor - a handle on a database of the same server, by name.
277
+ */
278
+ declare function rollbackMerges(dbFor: (name: string) => Db, images: MergeBeforeImages, opts: {
279
+ dryRun: boolean;
280
+ }, driver: MergeDriver): Promise<MergeRollbackRow[]>;
281
+
282
+ export { APP_DATABASE_KINDS, APP_LABEL, type AppDatabaseKind, type ExecutedMerge, MERGE, type MergeBeforeImages, type MergeCollectionLike, type MergeCursorLike, type MergeDatabase, type MergeDbLike, type MergeDocument, type MergeDriver, type MergeImage, type MergeLine, type MergeRefImage, type MergeRollbackRow, ORG_REFERENCES, type OrgReference, type PlannedMerge, type ReferenceApp, THREAD_SAMPLE_ID_PREFIX, YES, appDatabaseProblem, comparableName, executeMerges, formatPlannedMerge, planMerges, rollbackMerges, sheetText };
@@ -0,0 +1,282 @@
1
+ /**
2
+ * What a merge saves before it writes: everything its undo needs.
3
+ */
4
+ /** A stored document, as the driver hands it back. */
5
+ type MergeDocument = Record<string, any>;
6
+ /**
7
+ * The caller's BSON: the ObjectId class its driver stores and reads, and its
8
+ * EJSON. Passed in so this package imports neither mongoose nor the driver
9
+ * (with `mongodb`: `{ ObjectId, EJSON: BSON.EJSON }`; with mongoose:
10
+ * `mongoose.mongo.ObjectId` and `mongoose.mongo.BSON.EJSON`). An id built with another copy of the class would not match
11
+ * `instanceof` on the values the caller's driver returns.
12
+ */
13
+ interface MergeDriver {
14
+ ObjectId: {
15
+ new (hex: string): {
16
+ toHexString(): string;
17
+ };
18
+ };
19
+ EJSON: {
20
+ stringify(value: any, options?: {
21
+ relaxed?: boolean;
22
+ }): string;
23
+ };
24
+ }
25
+ interface MergeCursorLike {
26
+ limit(n: number): MergeCursorLike;
27
+ sort(spec: any): MergeCursorLike;
28
+ toArray(): Promise<any[]>;
29
+ }
30
+ /** The slice of a driver `Collection` a merge uses. */
31
+ interface MergeCollectionLike {
32
+ find(filter: any, options?: any): MergeCursorLike;
33
+ findOne(filter: any, options?: any): Promise<any>;
34
+ countDocuments(filter?: any): Promise<number>;
35
+ updateOne(filter: any, update: any): Promise<{
36
+ matchedCount: number;
37
+ }>;
38
+ replaceOne(filter: any, replacement: any): Promise<unknown>;
39
+ deleteOne(filter: any): Promise<{
40
+ deletedCount: number;
41
+ }>;
42
+ insertOne(doc: any): Promise<unknown>;
43
+ }
44
+ /** The slice of a driver `Db` a merge uses: a `mongodb` `Db` or a mongoose connection's `.db` fits. */
45
+ interface MergeDbLike {
46
+ collection(name: string): MergeCollectionLike;
47
+ listCollections(filter?: any, options?: any): {
48
+ toArray(): Promise<any[]>;
49
+ };
50
+ }
51
+ type Document = MergeDocument;
52
+ /** One stored reference a merge moves from the copy to the kept Org (`orgMerge.ts`). */
53
+ interface MergeRefImage {
54
+ /** The database the document is in (the platform database, or an app's own on the same server). */
55
+ db: string;
56
+ collection: string;
57
+ /**
58
+ * `value`: `path` holds the id. `list`: `path` is a list of ids. `rows`: `path` is a list of sub-records, `field`
59
+ * holds the id. `answers`: `path` is a list of form answers, `field` in each is a list of values.
60
+ */
61
+ kind: "value" | "list" | "rows" | "answers";
62
+ path: string;
63
+ field?: string;
64
+ docId: unknown;
65
+ /** On `value`: the copy's id exactly as stored, and the kept Org's id in the same stored form. Otherwise the two ids as text. */
66
+ from: unknown;
67
+ to: unknown;
68
+ /** On every other kind: the whole list at `path` before the merge, and as the merge leaves it. */
69
+ before?: unknown[];
70
+ after?: unknown[];
71
+ }
72
+ /** One copy folded into the Org that is kept: everything the undo needs. Written before the merge is. */
73
+ interface MergeImage {
74
+ duplicateId: unknown;
75
+ duplicateName: string;
76
+ keptId: unknown;
77
+ keptName: string;
78
+ /** The copy's row exactly as stored before the merge. The undo re-inserts it. */
79
+ duplicate: Document;
80
+ refs: MergeRefImage[];
81
+ /** What was planned for the copy once its references had moved. */
82
+ outcome: "delete" | "retire";
83
+ /** 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. */
84
+ addsLegacyEntry: boolean;
85
+ }
86
+ /**
87
+ * The saved record of a run of merges, as the undo reads it. The registry
88
+ * fill's before-images file is one (`FillBeforeImages`); the Platform's Admin
89
+ * Hub stores one per merge.
90
+ */
91
+ interface MergeBeforeImages {
92
+ /** The platform database the merges ran in. */
93
+ db: string;
94
+ /** The `updatedTime` the run stamped on every row it wrote. */
95
+ appliedTime: Date;
96
+ merges?: MergeImage[];
97
+ }
98
+
99
+ /** A name reduced for comparison: case, punctuation and a leading "the" dropped. */
100
+ declare function comparableName(value: unknown): string;
101
+ /** A spreadsheet must not evaluate an org name as a formula. */
102
+ declare const sheetText: (v: unknown) => string;
103
+
104
+ /**
105
+ * @htilabs/platform-common-models — folding a copy into the real organization
106
+ *
107
+ * The logic behind `fill-org-registry --apply-merges`. Runbook:
108
+ * `scripts/FILL_ORG_REGISTRY_RUNBOOK.md`, "Folding a copy into the real
109
+ * organization".
110
+ *
111
+ * ## Why
112
+ *
113
+ * One record per real-world organization (UDD Org Data Object, 2026-10-02).
114
+ * Where the same organization was typed in twice, the steward (HTI Labs)
115
+ * reconciles the two by hand: a person names the copy and the row that is
116
+ * kept. Nothing here works out which rows are copies.
117
+ *
118
+ * ## What a merge is (ruled 2026-10-20, the prototype's ORG-MERGE)
119
+ *
120
+ * Pure re-pointing. Every stored reference to the copy's `_id` is changed to
121
+ * the kept organization's `_id`. Nothing on the kept row is combined or
122
+ * rewritten: not its name, type, VSP answer, list or programs, and no
123
+ * Account's sharing rule. The copy is then deleted, and its id is recorded on
124
+ * the kept row as `legacy_ids.merged_from`, so an old reference found later
125
+ * can be traced.
126
+ *
127
+ * ## Where references live
128
+ *
129
+ * {@link ORG_REFERENCES} is the list, read from the models of this package,
130
+ * Thread, PAVE 2.0, the Platform app and auth (2026-11-10). Thread and PAVE
131
+ * keep their case records in databases of their own. The copy is deleted only
132
+ * when nothing in the platform database points at it AND every Thread and
133
+ * PAVE database was named on the command line and nothing there points at it
134
+ * either. Otherwise the copy stays, marked inactive (`status` 2, which every
135
+ * app already reads as "not offered", `isListedOrganization`), and the line
136
+ * says why.
137
+ *
138
+ * ## What it never does
139
+ *
140
+ * It never writes a fact of the kept row, never moves an identifier (`key`:
141
+ * identifiers never change), never moves a sharing grant, never merges an
142
+ * Agency's own organization (that is not a copy) or a copy that has programs,
143
+ * and never re-points a copy of an id kept inside a sent share, a session
144
+ * draft or a sealed field (see the runbook).
145
+ */
146
+
147
+ type Db = MergeDbLike;
148
+ /**
149
+ * Thread's development sample rows (`apps/api/src/seed/index.ts`: the
150
+ * "Thread Prototype Agency" and its organizations, ids `64e4ff1c2a7dcd9cb5f4a0xx`
151
+ * and `…a1xx`). Some reached production. They are never a kept row or a copy.
152
+ */
153
+ declare const THREAD_SAMPLE_ID_PREFIX = "64e4ff1c2a7dcd9cb5f4a";
154
+ /** Which database a reference lives in: the platform database, or an app's own. */
155
+ type ReferenceApp = "platform" | "thread" | "pave";
156
+ declare const APP_LABEL: Record<ReferenceApp, string>;
157
+ interface OrgReference {
158
+ app: ReferenceApp;
159
+ collection: string;
160
+ /**
161
+ * `value`: `path` holds the id. `list`: `path` is a list of ids. `rows`:
162
+ * `path` is a list of sub-records and `field` in each holds the id.
163
+ * `answers`: `path` is a list of form answers and `field` in each is a list
164
+ * of values, any of which may be the id. `count`: counted, never moved: a
165
+ * copy it names is kept, not deleted.
166
+ */
167
+ kind: MergeRefImage["kind"] | "count";
168
+ path: string;
169
+ field?: string;
170
+ /** Who writes it, for the runbook's table. */
171
+ writtenBy: string;
172
+ }
173
+ /**
174
+ * Every place an organization's `_id` is stored, from the code (2026-11-10).
175
+ * `agencies.organizationId` is not here: an organization an Agency points at
176
+ * is that Agency's own and is never merged. A reference by an Org's `key`
177
+ * (the Platform app's sharing-rule attachments) is not here either: a merge
178
+ * moves ids, and identifiers never move. Program ids (`programs[].programId`)
179
+ * are not here: a copy with programs is refused.
180
+ */
181
+ declare const ORG_REFERENCES: readonly OrgReference[];
182
+ /** The apps that keep references in a database of their own. A copy is deleted only when each was checked. */
183
+ declare const APP_DATABASE_KINDS: readonly ["thread", "pave"];
184
+ type AppDatabaseKind = (typeof APP_DATABASE_KINDS)[number];
185
+ /** One database a merge reads and re-points in. */
186
+ interface MergeDatabase {
187
+ app: ReferenceApp;
188
+ name: string;
189
+ db: Db;
190
+ }
191
+ /** Why `db` cannot be `app`'s database, or null when it can. A name that matches nothing would read as "no references". */
192
+ declare function appDatabaseProblem(app: AppDatabaseKind, name: string, db: Db): Promise<string | null>;
193
+ /** What a reviewer writes in the merge sheet's `approved` column. */
194
+ declare const MERGE = "merge";
195
+ /** What a reviewer writes in the sheet's `different_name_ok` to merge two rows whose names differ. */
196
+ declare const YES = "yes";
197
+ interface MergeLine {
198
+ /** Sheet line (header = 1), for messages. */
199
+ line: number;
200
+ duplicateId: string;
201
+ duplicateName: string;
202
+ keptId: string;
203
+ keptName: string;
204
+ /** The line says in so many words that the two names differ and are one organization. */
205
+ differentNameOk: boolean;
206
+ }
207
+ interface PlannedMerge {
208
+ line: MergeLine;
209
+ /** `merge` is written; `already` is done (the copy is gone and recorded); `skip` blocks the whole apply. */
210
+ status: "merge" | "already" | "skip";
211
+ detail: string;
212
+ /** Stored names ("" when the row was not found). */
213
+ duplicateName: string;
214
+ keptName: string;
215
+ /** Whose list each row sits in (`agencyScope`), in words. */
216
+ duplicateList: string;
217
+ keptList: string;
218
+ flags: string[];
219
+ /** Present on `merge`: what {@link executeMerges} writes, and its undo. */
220
+ write?: MergeImage;
221
+ }
222
+ /**
223
+ * Read every approved line and decide. Reads only. `skip` (any one blocks the
224
+ * whole apply): either row is missing; a stored name is not the sheet's; the
225
+ * copy is a canonical singleton, an Agency's own organization (it names an
226
+ * Agency, or an Agency points at it: that is not a copy), or has programs;
227
+ * the kept row is inactive or declined, or is a unit of the copy; the two
228
+ * names differ and the line does not say `different_name_ok` = yes; the kept
229
+ * row could not be seen where the copy is used.
230
+ *
231
+ * Seen, as Thread decides it (`organizationReadableBy`, `resolveUserCommunity`):
232
+ * an Agency sees the organizations in its own list, and an organization of
233
+ * another list only when the Agency's `state` is exactly that organization's
234
+ * `community` (both non-blank; compared as stored, no trimming or case change).
235
+ * So the kept row must be in the copy's list, or the Agency whose list the
236
+ * copy is in must have a `state` equal to the kept row's `community`.
237
+ *
238
+ * @param dbs - the platform database first, then each app database the caller could open.
239
+ * @param driver - the caller's ObjectId class and EJSON (see {@link MergeDriver}).
240
+ */
241
+ declare function planMerges(dbs: readonly MergeDatabase[], lines: readonly MergeLine[], driver: MergeDriver): Promise<PlannedMerge[]>;
242
+ /** One planned line as printed: both rows by stored name and list, what moves, what happens to the copy, any flag. */
243
+ declare function formatPlannedMerge(p: PlannedMerge): string;
244
+ interface ExecutedMerge {
245
+ merge: MergeImage;
246
+ /** `deleted` / `retired`: the line is done. `changed`: a row moved since the plan. `failed`: the database refused. */
247
+ status: "deleted" | "retired" | "changed" | "failed";
248
+ moved: number;
249
+ detail?: string;
250
+ }
251
+ /**
252
+ * Carry out each merge, one at a time: record the copy's id on the kept row,
253
+ * move each reference (only where it still holds what the plan read), then
254
+ * count what still names the copy. Nothing left and every app database
255
+ * checked: the copy is deleted. Otherwise it is marked inactive. Either
256
+ * happens only while the copy is still exactly as planned. The kept row gets
257
+ * `legacy_ids.merged_from` and nothing else: not even a new `updatedTime`.
258
+ */
259
+ declare function executeMerges(dbs: readonly MergeDatabase[], merges: readonly MergeImage[], now: Date, driver: MergeDriver): Promise<ExecutedMerge[]>;
260
+ interface MergeRollbackRow {
261
+ image: MergeImage;
262
+ /** `restore`: everything can be put back. `partial`: some of it. `skip`: nothing to do, or nothing safe to do. */
263
+ status: "restore" | "partial" | "skip";
264
+ detail: string;
265
+ }
266
+ /**
267
+ * Undo each merge of a before-images file, newest first; with `dryRun`, only
268
+ * say what would happen. The copy comes back first (re-inserted exactly from
269
+ * its before-image when it was deleted; its `status` and `updatedTime`
270
+ * restored when it was marked inactive), then each reference that still holds
271
+ * what the merge wrote goes back (a list or a list of sub-records is put back
272
+ * whole, so a copy's id the merge dropped returns too), then the copy's id is
273
+ * taken off the kept row's `legacy_ids`, only when this run put it there. A
274
+ * reference somebody has changed since is left alone and counted.
275
+ *
276
+ * @param dbFor - a handle on a database of the same server, by name.
277
+ */
278
+ declare function rollbackMerges(dbFor: (name: string) => Db, images: MergeBeforeImages, opts: {
279
+ dryRun: boolean;
280
+ }, driver: MergeDriver): Promise<MergeRollbackRow[]>;
281
+
282
+ export { APP_DATABASE_KINDS, APP_LABEL, type AppDatabaseKind, type ExecutedMerge, MERGE, type MergeBeforeImages, type MergeCollectionLike, type MergeCursorLike, type MergeDatabase, type MergeDbLike, type MergeDocument, type MergeDriver, type MergeImage, type MergeLine, type MergeRefImage, type MergeRollbackRow, ORG_REFERENCES, type OrgReference, type PlannedMerge, type ReferenceApp, THREAD_SAMPLE_ID_PREFIX, YES, appDatabaseProblem, comparableName, executeMerges, formatPlannedMerge, planMerges, rollbackMerges, sheetText };