@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.
@@ -82,6 +82,23 @@ interface MergeImage {
82
82
  outcome: "delete" | "retire";
83
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
84
  addsLegacyEntry: boolean;
85
+ /**
86
+ * Present when the copy's programs move to the kept Org (a steward's merge, 0.84.0): the kept Org's
87
+ * `programs` exactly as stored before the merge and the copy's rows exactly as stored, in order. The merge adds
88
+ * the copy's rows to the end of the kept Org's list, ids unchanged.
89
+ */
90
+ programs?: MergeProgramsImage;
91
+ }
92
+ /**
93
+ * The copy's `programs[]` rows moved to the kept Org, and what the kept Org's
94
+ * list was. Both are read without promoting numbers, so a value written back
95
+ * keeps its stored type.
96
+ */
97
+ interface MergeProgramsImage {
98
+ /** False when the kept Org stored no list (the field absent, or not a list): the merge creates it, the undo removes it. */
99
+ keptHad: boolean;
100
+ keptBefore: unknown[];
101
+ moved: unknown[];
85
102
  }
86
103
  /**
87
104
  * The saved record of a run of merges, as the undo reads it. The registry
@@ -98,6 +115,12 @@ interface MergeBeforeImages {
98
115
 
99
116
  /** A name reduced for comparison: case, punctuation and a leading "the" dropped. */
100
117
  declare function comparableName(value: unknown): string;
118
+ /**
119
+ * An organization id as text, comparable: a 24-hex database id in lower case
120
+ * (the form an ObjectId prints as), any other text id exactly as stored. A
121
+ * text id is never case-folded: "Org-A" and "org-a" are two rows.
122
+ */
123
+ declare function comparableId(value: string): string;
101
124
  /** A spreadsheet must not evaluate an org name as a formula. */
102
125
  declare const sheetText: (v: unknown) => string;
103
126
 
@@ -135,13 +158,56 @@ declare const sheetText: (v: unknown) => string;
135
158
  * app already reads as "not offered", `isListedOrganization`), and the line
136
159
  * says why.
137
160
  *
161
+ * ## Programs (0.84.0)
162
+ *
163
+ * A Program belongs to the Organization, and is stored on its row
164
+ * (`organizations.programs[]`). "Make the other objects really move in a
165
+ * merge" (Crysta, 2026-11-11): when a steward merges, the copy's program rows
166
+ * move to the kept organization, exactly as stored and with their ids
167
+ * unchanged. A program id is minted, never derived from a name, so it names
168
+ * one program wherever its row sits; everything that points at a program
169
+ * (`servicelistings.program_id`, a case's program in Thread or PAVE) names it
170
+ * beside the organization, and that reference is re-pointed above. So nothing
171
+ * that points at a program is touched, and nothing is left pointing at a
172
+ * program that is gone. The rows are appended to the kept organization's
173
+ * list in the same write that records the copy's id there. Two live programs
174
+ * that end up with the same name are both kept, as two programs (a name is
175
+ * not an identity; the plan says so in a flag). Where the agency whose list
176
+ * the copy is in cannot yet read the kept row in Thread and PAVE (see "Who is
177
+ * merging"), the flag also says it may not be able to pick the programs that
178
+ * moved; nothing is refused for it. A copy that is then kept as
179
+ * inactive keeps no programs: they are the kept organization's now. A merge
180
+ * inside one agency's own list (`agency`) still refuses a copy with programs,
181
+ * as before.
182
+ *
138
183
  * ## What it never does
139
184
  *
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).
185
+ * It never writes a fact of the kept row (its programs are added to, never
186
+ * rewritten), never moves an identifier (`key`: identifiers never change),
187
+ * never moves a sharing grant, never merges an Agency's own organization
188
+ * (that is not a copy), and never re-points a copy of an id kept inside a
189
+ * sent share, a session draft or a sealed field (see the runbook).
190
+ *
191
+ * ## Who is merging (0.84.0)
192
+ *
193
+ * The caller says who merges ({@link MergeActor}); nothing here works it out.
194
+ *
195
+ * - `steward`: HTI Labs reconciling the registry (the Admin Hub's "Merge into
196
+ * another organization", the registry tool). The registry is ONE
197
+ * platform-wide list: "Organizations should never sit inside one agency's
198
+ * own list" (Crysta, 2026-11-11), and an agency's list never blocks a
199
+ * registry action. So the pair is judged against the registry alone: both
200
+ * rows exist, the kept one is offered (active, not declined). Whose list a
201
+ * row was typed into (`agencyScope`) and its `community` refuse nothing.
202
+ * Where Thread's and PAVE's as-built per-agency read would hide the kept
203
+ * row from the agency whose list the copy is in, the plan carries a flag
204
+ * saying so, in words a steward can read; it goes when both apps read the
205
+ * one list (Thread #1228 and PAVE's twin).
206
+ * - `agency`: a merge made inside one agency's own list. The kept row must be
207
+ * readable where the copy is used, by Thread's as-built rule. This is the
208
+ * rule every caller had before 0.84.0, unchanged. No app calls it today.
209
+ *
210
+ * Every other refusal is about the data, not about lists, and holds for both.
145
211
  */
146
212
 
147
213
  type Db = MergeDbLike;
@@ -204,6 +270,17 @@ interface MergeLine {
204
270
  /** The line says in so many words that the two names differ and are one organization. */
205
271
  differentNameOk: boolean;
206
272
  }
273
+ /**
274
+ * Who is merging. `steward`: HTI Labs, acting on the one platform-wide
275
+ * registry; no agency's list refuses the pair. `agency`: a merge inside one
276
+ * agency's own list; the kept row must be readable where the copy is used
277
+ * (the only rule before 0.84.0). See "Who is merging" at the top of this file.
278
+ */
279
+ type MergeActor = "steward" | "agency";
280
+ /** What the caller states about a plan. Required: the rules never guess who is merging. */
281
+ interface MergePlanOptions {
282
+ mergedBy: MergeActor;
283
+ }
207
284
  interface PlannedMerge {
208
285
  line: MergeLine;
209
286
  /** `merge` is written; `already` is done (the copy is gone and recorded); `skip` blocks the whole apply. */
@@ -225,8 +302,10 @@ interface PlannedMerge {
225
302
  * copy is a canonical singleton, an Agency's own organization (it names an
226
303
  * Agency, or an Agency points at it: that is not a copy), or has programs;
227
304
  * 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.
305
+ * names differ and the line does not say `different_name_ok` = yes; and, only
306
+ * when an `agency` merges ({@link MergeActor}), the kept row could not be seen
307
+ * where the copy is used. A `steward`'s merge is never refused for that: the
308
+ * registry is one platform-wide list, and the plan carries a flag instead.
230
309
  *
231
310
  * Seen, as Thread decides it (`organizationReadableBy`, `resolveUserCommunity`):
232
311
  * an Agency sees the organizations in its own list, and an organization of
@@ -237,8 +316,9 @@ interface PlannedMerge {
237
316
  *
238
317
  * @param dbs - the platform database first, then each app database the caller could open.
239
318
  * @param driver - the caller's ObjectId class and EJSON (see {@link MergeDriver}).
319
+ * @param opts - who is merging ({@link MergePlanOptions}); stated by the caller, never inferred.
240
320
  */
241
- declare function planMerges(dbs: readonly MergeDatabase[], lines: readonly MergeLine[], driver: MergeDriver): Promise<PlannedMerge[]>;
321
+ declare function planMerges(dbs: readonly MergeDatabase[], lines: readonly MergeLine[], driver: MergeDriver, opts: MergePlanOptions): Promise<PlannedMerge[]>;
242
322
  /** One planned line as printed: both rows by stored name and list, what moves, what happens to the copy, any flag. */
243
323
  declare function formatPlannedMerge(p: PlannedMerge): string;
244
324
  interface ExecutedMerge {
@@ -254,7 +334,9 @@ interface ExecutedMerge {
254
334
  * count what still names the copy. Nothing left and every app database
255
335
  * checked: the copy is deleted. Otherwise it is marked inactive. Either
256
336
  * 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`.
337
+ * `legacy_ids.merged_from` and, when the copy has programs, those rows added
338
+ * to the end of its own (in the one write, and only while its programs are
339
+ * still as planned): nothing else, not even a new `updatedTime`.
258
340
  */
259
341
  declare function executeMerges(dbs: readonly MergeDatabase[], merges: readonly MergeImage[], now: Date, driver: MergeDriver): Promise<ExecutedMerge[]>;
260
342
  interface MergeRollbackRow {
@@ -279,4 +361,4 @@ declare function rollbackMerges(dbFor: (name: string) => Db, images: MergeBefore
279
361
  dryRun: boolean;
280
362
  }, driver: MergeDriver): Promise<MergeRollbackRow[]>;
281
363
 
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 };
364
+ export { APP_DATABASE_KINDS, APP_LABEL, type AppDatabaseKind, type ExecutedMerge, MERGE, type MergeActor, type MergeBeforeImages, type MergeCollectionLike, type MergeCursorLike, type MergeDatabase, type MergeDbLike, type MergeDocument, type MergeDriver, type MergeImage, type MergeLine, type MergePlanOptions, type MergeProgramsImage, type MergeRefImage, type MergeRollbackRow, ORG_REFERENCES, type OrgReference, type PlannedMerge, type ReferenceApp, THREAD_SAMPLE_ID_PREFIX, YES, appDatabaseProblem, comparableId, comparableName, executeMerges, formatPlannedMerge, planMerges, rollbackMerges, sheetText };
@@ -82,6 +82,23 @@ interface MergeImage {
82
82
  outcome: "delete" | "retire";
83
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
84
  addsLegacyEntry: boolean;
85
+ /**
86
+ * Present when the copy's programs move to the kept Org (a steward's merge, 0.84.0): the kept Org's
87
+ * `programs` exactly as stored before the merge and the copy's rows exactly as stored, in order. The merge adds
88
+ * the copy's rows to the end of the kept Org's list, ids unchanged.
89
+ */
90
+ programs?: MergeProgramsImage;
91
+ }
92
+ /**
93
+ * The copy's `programs[]` rows moved to the kept Org, and what the kept Org's
94
+ * list was. Both are read without promoting numbers, so a value written back
95
+ * keeps its stored type.
96
+ */
97
+ interface MergeProgramsImage {
98
+ /** False when the kept Org stored no list (the field absent, or not a list): the merge creates it, the undo removes it. */
99
+ keptHad: boolean;
100
+ keptBefore: unknown[];
101
+ moved: unknown[];
85
102
  }
86
103
  /**
87
104
  * The saved record of a run of merges, as the undo reads it. The registry
@@ -98,6 +115,12 @@ interface MergeBeforeImages {
98
115
 
99
116
  /** A name reduced for comparison: case, punctuation and a leading "the" dropped. */
100
117
  declare function comparableName(value: unknown): string;
118
+ /**
119
+ * An organization id as text, comparable: a 24-hex database id in lower case
120
+ * (the form an ObjectId prints as), any other text id exactly as stored. A
121
+ * text id is never case-folded: "Org-A" and "org-a" are two rows.
122
+ */
123
+ declare function comparableId(value: string): string;
101
124
  /** A spreadsheet must not evaluate an org name as a formula. */
102
125
  declare const sheetText: (v: unknown) => string;
103
126
 
@@ -135,13 +158,56 @@ declare const sheetText: (v: unknown) => string;
135
158
  * app already reads as "not offered", `isListedOrganization`), and the line
136
159
  * says why.
137
160
  *
161
+ * ## Programs (0.84.0)
162
+ *
163
+ * A Program belongs to the Organization, and is stored on its row
164
+ * (`organizations.programs[]`). "Make the other objects really move in a
165
+ * merge" (Crysta, 2026-11-11): when a steward merges, the copy's program rows
166
+ * move to the kept organization, exactly as stored and with their ids
167
+ * unchanged. A program id is minted, never derived from a name, so it names
168
+ * one program wherever its row sits; everything that points at a program
169
+ * (`servicelistings.program_id`, a case's program in Thread or PAVE) names it
170
+ * beside the organization, and that reference is re-pointed above. So nothing
171
+ * that points at a program is touched, and nothing is left pointing at a
172
+ * program that is gone. The rows are appended to the kept organization's
173
+ * list in the same write that records the copy's id there. Two live programs
174
+ * that end up with the same name are both kept, as two programs (a name is
175
+ * not an identity; the plan says so in a flag). Where the agency whose list
176
+ * the copy is in cannot yet read the kept row in Thread and PAVE (see "Who is
177
+ * merging"), the flag also says it may not be able to pick the programs that
178
+ * moved; nothing is refused for it. A copy that is then kept as
179
+ * inactive keeps no programs: they are the kept organization's now. A merge
180
+ * inside one agency's own list (`agency`) still refuses a copy with programs,
181
+ * as before.
182
+ *
138
183
  * ## What it never does
139
184
  *
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).
185
+ * It never writes a fact of the kept row (its programs are added to, never
186
+ * rewritten), never moves an identifier (`key`: identifiers never change),
187
+ * never moves a sharing grant, never merges an Agency's own organization
188
+ * (that is not a copy), and never re-points a copy of an id kept inside a
189
+ * sent share, a session draft or a sealed field (see the runbook).
190
+ *
191
+ * ## Who is merging (0.84.0)
192
+ *
193
+ * The caller says who merges ({@link MergeActor}); nothing here works it out.
194
+ *
195
+ * - `steward`: HTI Labs reconciling the registry (the Admin Hub's "Merge into
196
+ * another organization", the registry tool). The registry is ONE
197
+ * platform-wide list: "Organizations should never sit inside one agency's
198
+ * own list" (Crysta, 2026-11-11), and an agency's list never blocks a
199
+ * registry action. So the pair is judged against the registry alone: both
200
+ * rows exist, the kept one is offered (active, not declined). Whose list a
201
+ * row was typed into (`agencyScope`) and its `community` refuse nothing.
202
+ * Where Thread's and PAVE's as-built per-agency read would hide the kept
203
+ * row from the agency whose list the copy is in, the plan carries a flag
204
+ * saying so, in words a steward can read; it goes when both apps read the
205
+ * one list (Thread #1228 and PAVE's twin).
206
+ * - `agency`: a merge made inside one agency's own list. The kept row must be
207
+ * readable where the copy is used, by Thread's as-built rule. This is the
208
+ * rule every caller had before 0.84.0, unchanged. No app calls it today.
209
+ *
210
+ * Every other refusal is about the data, not about lists, and holds for both.
145
211
  */
146
212
 
147
213
  type Db = MergeDbLike;
@@ -204,6 +270,17 @@ interface MergeLine {
204
270
  /** The line says in so many words that the two names differ and are one organization. */
205
271
  differentNameOk: boolean;
206
272
  }
273
+ /**
274
+ * Who is merging. `steward`: HTI Labs, acting on the one platform-wide
275
+ * registry; no agency's list refuses the pair. `agency`: a merge inside one
276
+ * agency's own list; the kept row must be readable where the copy is used
277
+ * (the only rule before 0.84.0). See "Who is merging" at the top of this file.
278
+ */
279
+ type MergeActor = "steward" | "agency";
280
+ /** What the caller states about a plan. Required: the rules never guess who is merging. */
281
+ interface MergePlanOptions {
282
+ mergedBy: MergeActor;
283
+ }
207
284
  interface PlannedMerge {
208
285
  line: MergeLine;
209
286
  /** `merge` is written; `already` is done (the copy is gone and recorded); `skip` blocks the whole apply. */
@@ -225,8 +302,10 @@ interface PlannedMerge {
225
302
  * copy is a canonical singleton, an Agency's own organization (it names an
226
303
  * Agency, or an Agency points at it: that is not a copy), or has programs;
227
304
  * 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.
305
+ * names differ and the line does not say `different_name_ok` = yes; and, only
306
+ * when an `agency` merges ({@link MergeActor}), the kept row could not be seen
307
+ * where the copy is used. A `steward`'s merge is never refused for that: the
308
+ * registry is one platform-wide list, and the plan carries a flag instead.
230
309
  *
231
310
  * Seen, as Thread decides it (`organizationReadableBy`, `resolveUserCommunity`):
232
311
  * an Agency sees the organizations in its own list, and an organization of
@@ -237,8 +316,9 @@ interface PlannedMerge {
237
316
  *
238
317
  * @param dbs - the platform database first, then each app database the caller could open.
239
318
  * @param driver - the caller's ObjectId class and EJSON (see {@link MergeDriver}).
319
+ * @param opts - who is merging ({@link MergePlanOptions}); stated by the caller, never inferred.
240
320
  */
241
- declare function planMerges(dbs: readonly MergeDatabase[], lines: readonly MergeLine[], driver: MergeDriver): Promise<PlannedMerge[]>;
321
+ declare function planMerges(dbs: readonly MergeDatabase[], lines: readonly MergeLine[], driver: MergeDriver, opts: MergePlanOptions): Promise<PlannedMerge[]>;
242
322
  /** One planned line as printed: both rows by stored name and list, what moves, what happens to the copy, any flag. */
243
323
  declare function formatPlannedMerge(p: PlannedMerge): string;
244
324
  interface ExecutedMerge {
@@ -254,7 +334,9 @@ interface ExecutedMerge {
254
334
  * count what still names the copy. Nothing left and every app database
255
335
  * checked: the copy is deleted. Otherwise it is marked inactive. Either
256
336
  * 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`.
337
+ * `legacy_ids.merged_from` and, when the copy has programs, those rows added
338
+ * to the end of its own (in the one write, and only while its programs are
339
+ * still as planned): nothing else, not even a new `updatedTime`.
258
340
  */
259
341
  declare function executeMerges(dbs: readonly MergeDatabase[], merges: readonly MergeImage[], now: Date, driver: MergeDriver): Promise<ExecutedMerge[]>;
260
342
  interface MergeRollbackRow {
@@ -279,4 +361,4 @@ declare function rollbackMerges(dbFor: (name: string) => Db, images: MergeBefore
279
361
  dryRun: boolean;
280
362
  }, driver: MergeDriver): Promise<MergeRollbackRow[]>;
281
363
 
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 };
364
+ export { APP_DATABASE_KINDS, APP_LABEL, type AppDatabaseKind, type ExecutedMerge, MERGE, type MergeActor, type MergeBeforeImages, type MergeCollectionLike, type MergeCursorLike, type MergeDatabase, type MergeDbLike, type MergeDocument, type MergeDriver, type MergeImage, type MergeLine, type MergePlanOptions, type MergeProgramsImage, type MergeRefImage, type MergeRollbackRow, ORG_REFERENCES, type OrgReference, type PlannedMerge, type ReferenceApp, THREAD_SAMPLE_ID_PREFIX, YES, appDatabaseProblem, comparableId, comparableName, executeMerges, formatPlannedMerge, planMerges, rollbackMerges, sheetText };