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