Skip to content

Commit d74ab15

Browse files
committed
wip(metadata-protocol): the packageless-overlays census reaches rows bound to a read-only base
Claude-Session: https://claude.ai/code/session_01ADHkmQZSg4zWtKMdRnKmKS Co-authored-by: Claude <noreply@anthropic.com>
1 parent 7f277a8 commit d74ab15

3 files changed

Lines changed: 222 additions & 18 deletions

File tree

‎packages/cli/src/commands/migrate/packageless-overlays.ts‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,11 @@ function reasonOf(row: CensusRow): string {
6565
return `'${row.base}' has no paired .custom package id, so there is nowhere to move it. Left as it is.`;
6666
case 'foreign_declaration':
6767
return `its body already carries an \`overrides\` key that does not name '${row.base}'. Left as it is: `
68-
+ 'remove the key with a save naming no package, then re-run: the move declares the right override.';
68+
+ (row.boundToBase
69+
// [#29392] A save naming the base is closed, so the key cannot be removed in place.
70+
? `delete it with a delete naming '${row.base}', then save its body into '${row.pair}' declaring `
71+
+ `overrides: { package: '${row.base}', basedOn }.`
72+
: 'remove the key with a save naming no package, then re-run: the move declares the right override.');
6973
case 'shadowed':
7074
return (row.shadowDeclares
7175
? `'${row.pair}' already overrides this item (a customization made in Studio), and that row is the one `
@@ -94,6 +98,7 @@ function jsonRow(row: CensusRow, outcome?: Outcome): Record<string, unknown> {
9498
...(row.pair !== undefined ? { pair: row.pair } : {}),
9599
...(row.shadowDeclares !== undefined ? { shadowDeclares: row.shadowDeclares } : {}),
96100
...(row.addedMember !== undefined ? { addedMember: row.addedMember } : {}),
101+
...(row.boundToBase ? { boundToBase: true } : {}),
97102
outcome: outcome?.outcome ?? (row.disposition === 'movable' ? 'listed' : 'left'),
98103
...(outcome && outcome.outcome !== 'failed'
99104
? { packageId: outcome.packageId, ...(outcome.basedOn !== undefined ? { basedOn: outcome.basedOn } : {}) }
@@ -106,7 +111,9 @@ function jsonRow(row: CensusRow, outcome?: Outcome): Record<string, unknown> {
106111
* `os migrate packageless-overlays` — list, and with `--apply` move, every
107112
* package-less overlay row of a name exactly one installed code package ships
108113
* into that package's paired `<base>.custom`, as a declared override
109-
* (ADR-0146 D11, the migration half of N-16).
114+
* (ADR-0146 D11, the migration half of N-16) — and every overlay row bound to
115+
* a read-only code package that ships its name, which a save naming that
116+
* package stored before such a save was closed (listed `boundToBase`).
110117
*
111118
* ## Why a ceremony
112119
*
@@ -125,7 +132,7 @@ function jsonRow(row: CensusRow, outcome?: Outcome): Record<string, unknown> {
125132
* header holds the rules): the pair is ensured through its one creation door,
126133
* each body is saved into the pair through the save door with the declaration
127134
* (`basedOn` = the installed base's version now), read back as the served
128-
* override, and only then is the package-less row deleted. A name no package
135+
* override, and only then is the moved row deleted. A name no package
129136
* ships is environment metadata and is not touched; a name several packages
130137
* ship, and a row the pair already overrides (a Studio customization made
131138
* first), are listed and left alone. A pair row declaring an override with no
@@ -158,8 +165,8 @@ function jsonRow(row: CensusRow, outcome?: Outcome): Record<string, unknown> {
158165
export default class MigratePackagelessOverlays extends Command {
159166
static override description =
160167
'List, and with --apply move, the package-less view, dashboard, report, translation and email-template rows '
161-
+ 'over a name one installed package ships into that package\'s paired .custom package, as declared overrides '
162-
+ '(ADR-0146 D11). Run once after upgrading.';
168+
+ 'over a name one installed package ships, and those bound to a read-only package that ships the name, into '
169+
+ 'that package\'s paired .custom package, as declared overrides (ADR-0146 D11). Run once after upgrading.';
163170

164171
static override examples = [
165172
'$ os migrate packageless-overlays',
@@ -242,7 +249,7 @@ export default class MigratePackagelessOverlays extends Command {
242249
}
243250
printWarning(
244251
'Apply mode moves the listed sys_metadata rows into each base\'s paired .custom package (created when '
245-
+ 'absent) and deletes the package-less rows. Re-run with --yes to confirm, or run without --apply to preview.',
252+
+ 'absent) and deletes the rows moved. Re-run with --yes to confirm, or run without --apply to preview.',
246253
);
247254
this.exit(1);
248255
return;
@@ -381,7 +388,8 @@ export default class MigratePackagelessOverlays extends Command {
381388
console.log(chalk.bold(`${movable.length} row(s) to move:`));
382389
for (const row of movable) {
383390
// [#28904] A member the base does not ship moves in as the pair's own, declaring nothing.
384-
console.log(` • ${itemOf(row)} → ${row.pair} ${row.addedMember !== undefined
391+
// [#29392] A row bound to the base (a save naming it, before that write was closed) moves the same way.
392+
console.log(` • ${itemOf(row)}${row.boundToBase ? ` bound to ${row.base}` : ''} → ${row.pair} ${row.addedMember !== undefined
385393
? `(its own member; ${row.base} ships none at ${row.addedMember})`
386394
: `(overrides ${row.base})`}`);
387395
}
@@ -413,7 +421,7 @@ export default class MigratePackagelessOverlays extends Command {
413421
+ `${line.declarationsCompleted} basedOn recorded, ${line.shadowed} shadowed, ${line.failed} failed`);
414422
}
415423
if (failed > 0) {
416-
printError(`${failed} row(s) could not be moved; each package-less row that failed is kept as it was.`);
424+
printError(`${failed} row(s) could not be moved; each row that failed is kept as it was.`);
417425
} else {
418426
printSuccess(`Done ${chalk.dim(`(${timer.display()})`)}. Restart the server so it serves the moved rows.`);
419427
}

‎packages/metadata-protocol/src/protocol-packageless-overlay-migration.ts‎

Lines changed: 68 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,32 @@
4646
* are never in the population (ADR-0146 D6; their own ceremony is
4747
* `os migrate security-catalog-overlays`).
4848
*
49+
* ## …and the rows bound to a read-only base (#29392)
50+
*
51+
* Before #28905 closed it, a save naming the read-only code package itself
52+
* (`?package=<base>`) stored the customization as a row bound to the base,
53+
* declaring nothing, served at the base's address in place of its document.
54+
* Such a row is in the population too: a row of one of the five overlay types
55+
* whose `package_id` is a READ-ONLY code package that ships the name — the
56+
* reading the #28905 close names "packaged" (`readOnlyShippingPackages` over
57+
* `shippedArtifactsOf`, its `overlayBaseShippers`), the one this census reads
58+
* for a package-less row too. The binding names the base, so a name several
59+
* packages ship is never `multi_shipped` here: the row is classified by the
60+
* same {@link classifyPackagelessRow} with its binding as the one shipper,
61+
* and carries `boundToBase`. It moves as a package-less row does, with the
62+
* same outcomes (`moved`, or `moved` + `addedMember`), the delete of step 4
63+
* addressing it by its own binding. A row bound to a writable package (the
64+
* pair included) is that package's own item, edited in place (ADR-0070), and
65+
* a row bound to a read-only package that does not ship the name is not a
66+
* customization of it: neither is listed.
67+
*
68+
* Two rows of one item from different bindings — a package-less one and one
69+
* bound to the base — would both land on the pair's one row. The move takes
70+
* the package-less rows first; a row of an item this run has already moved a
71+
* row of another binding into the pair is kept, its outcome `failed`, and the
72+
* next run lists it `shadowed` (the pair holds the item now), with that
73+
* disposition's two ways out. Nothing is overwritten.
74+
*
4975
* ## The move, one row at a time
5076
*
5177
* 1. The pair is ensured through the ensure door,
@@ -162,6 +188,13 @@ export interface PackagelessOverlayRow {
162188
* override (module header, "a bundle member the base does not ship").
163189
*/
164190
readonly addedMember?: string;
191+
/**
192+
* [#29392] The row is bound to `base`, a read-only code package that ships
193+
* the name — stored by a save naming the base before the #28905 close —
194+
* rather than to no package (module header, "the rows bound to a read-only
195+
* base"). Absent for a package-less row.
196+
*/
197+
readonly boundToBase?: true;
165198
}
166199

167200
/** One pair row whose declaration lacks `basedOn` (module header, last section). */
@@ -371,7 +404,6 @@ export async function listPackagelessOverlays(
371404
const listed: PackagelessOverlayRow[] = [];
372405
let environmentRows = 0;
373406
for (const row of rows) {
374-
if (!isUnbound(row)) continue;
375407
const type = PLURAL_TO_SINGULAR[row.type] ?? row.type;
376408
const name = String(row.name);
377409
const state = stateOf(row)!;
@@ -380,6 +412,10 @@ export async function listPackagelessOverlays(
380412
// item is edited in place (ADR-0070) and has no pair (ADR-0146 D3), and
381413
// the pair itself is writable — the write gate's own narrowing.
382414
const shippers = readOnlyShippingPackages(this.shippedArtifactsOf(type, name), (id) => this.isWritablePackage(id));
415+
// [#29392] A bound row is in the population only when its binding is
416+
// one of those read-only shippers: a row bound to the base itself.
417+
const binding = isUnbound(row) ? undefined : String(row.package_id);
418+
if (binding !== undefined && !shippers.includes(binding)) continue;
383419
if (shippers.length === 0) {
384420
environmentRows += 1;
385421
continue;
@@ -394,11 +430,18 @@ export async function listPackagelessOverlays(
394430
shippers,
395431
};
396432
const body = bodyOf(row);
397-
const classified = classifyPackagelessRow(shippers, body, (pair) => shadowOf(pair, type, name, member, state));
433+
// A row bound to the base names its base: the binding is its one shipper.
434+
const classified = classifyPackagelessRow(binding !== undefined ? [binding] : shippers, body,
435+
(pair) => shadowOf(pair, type, name, member, state));
398436
const addedMember = classified.disposition === 'movable' && classified.base !== undefined
399437
? addedMemberOf(this, type, name, classified.base, body)
400438
: undefined;
401-
listed.push({ ...common, ...classified, ...(addedMember !== undefined ? { addedMember } : {}) });
439+
listed.push({
440+
...common,
441+
...classified,
442+
...(addedMember !== undefined ? { addedMember } : {}),
443+
...(binding !== undefined ? { boundToBase: true as const } : {}),
444+
});
402445
}
403446

404447
// Every type a declaration applies to, not only the five the move acts on.
@@ -500,13 +543,25 @@ export async function migratePackagelessOverlays(
500543
for (const row of await environmentRowsOfTypes.call(this, OVERRIDABLE_TYPE_SPELLINGS)) rowsById.set(String(row.id), row);
501544
}
502545

503-
for (const row of census.rows) {
504-
if (row.disposition !== 'movable' || row.base === undefined || row.pair === undefined) continue;
546+
// [#29392] The package-less rows first, then the rows bound to a base; an
547+
// item this run moved a row of one binding into keeps a row of the other
548+
// (module header, "the rows bound to a read-only base").
549+
const movedFrom = new Map<string, boolean>();
550+
const toMove = census.rows.filter((row) => row.disposition === 'movable' && row.base !== undefined && row.pair !== undefined);
551+
for (const row of [...toMove.filter((r) => !r.boundToBase), ...toMove.filter((r) => r.boundToBase)]) {
552+
if (row.base === undefined || row.pair === undefined) continue;
505553
const line = lineOf(row.base, row.pair);
506554
const fail = (error: string) => {
507555
line.failed += 1;
508556
outcomes.push({ id: row.id, outcome: 'failed', error });
509557
};
558+
const itemKey = `${row.pair}\u0000${row.type}\u0000${row.name}\u0000${row.member ?? ''}`;
559+
const bound = row.boundToBase === true;
560+
if (movedFrom.has(itemKey) && movedFrom.get(itemKey) !== bound) {
561+
fail(`'${row.pair}' now holds this item: this run moved its ${bound ? 'package-less row' : `row bound to '${row.base}'`} `
562+
+ 'there, and the row is kept beside it, never merged. Re-run the preview for the ways out.');
563+
continue;
564+
}
510565
const ensuredPair = await ensure(row.base, row.pair);
511566
if (!ensuredPair.ok) { fail(ensuredPair.error); continue; }
512567
// [#28904] A member the base does not ship is the pair's own: no
@@ -533,12 +588,14 @@ export async function migratePackagelessOverlays(
533588
// or, for an added member, that member's own row declaring nothing.
534589
const written = await storedPairRow(this, row, row.pair);
535590
if (addedMember === undefined ? !isServedOverrideRowOf(written, row.base) : !isOwnMemberRow(written)) {
591+
const kept = bound ? `the row bound to '${row.base}' is kept` : 'the unbound row is kept';
536592
fail(addedMember === undefined
537-
? `The row saved into '${row.pair}' does not read back as the declared override of '${row.base}'; the unbound row is kept.`
538-
: `The row saved into '${row.pair}' does not read back as its own member '${addedMember}', declaring no override; the unbound row is kept.`);
593+
? `The row saved into '${row.pair}' does not read back as the declared override of '${row.base}'; ${kept}.`
594+
: `The row saved into '${row.pair}' does not read back as its own member '${addedMember}', declaring no override; ${kept}.`);
539595
continue;
540596
}
541-
// Step 4: only now, the unbound row, by its own address.
597+
// Step 4: only now, the unbound row (or the row bound to the
598+
// base), by its own address.
542599
await repository.delete(
543600
{ type: row.storedType, name: row.name, org: 'env' } as never,
544601
{
@@ -550,10 +607,12 @@ export async function migratePackagelessOverlays(
550607
: `Moved into '${row.pair}' as its own member '${addedMember}', which '${row.base}' does not ship (ADR-0146 D2, D11)`,
551608
intent: 'override-artifact',
552609
state: row.state,
553-
packageId: null,
610+
// [#29392] A row bound to the base is deleted by that binding.
611+
packageId: bound ? row.base : null,
554612
...(row.member !== undefined ? { member: row.member } : {}),
555613
} as never,
556614
);
615+
movedFrom.set(itemKey, bound);
557616
line.moved += 1;
558617
outcomes.push(addedMember === undefined
559618
? { id: row.id, outcome: 'moved', packageId: row.pair, basedOn: basedOn! }

0 commit comments

Comments
 (0)