@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.
- package/README.md +59 -0
- package/dist/org-merge/index.cjs +947 -0
- package/dist/org-merge/index.cjs.map +1 -0
- package/dist/org-merge/index.d.cts +282 -0
- package/dist/org-merge/index.d.ts +282 -0
- package/dist/org-merge/index.js +908 -0
- package/dist/org-merge/index.js.map +1 -0
- package/package.json +6 -1
- package/src/orgMerge/__tests__/orgMergeSubpath.test.ts +56 -0
- package/src/orgMerge/index.ts +12 -0
- package/src/orgMerge/orgMerge.ts +706 -0
- package/src/orgMerge/support.ts +22 -0
- package/src/orgMerge/types.ts +93 -0
|
@@ -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 };
|