@@ -0,0 +1,15 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(metadata-protocol): a tenant's edit follows its item across the packages of one App
+
+Clause-②: no — no accept set changes; the lookup scope widens only within one suite (triage 6724363147)
+Metadata-protocol: none
+
+When a later version of an App moves an item from one of its packages to another (an ADR-0130 D4 suite split such as a flat App becoming an App plus modules, or the rollback of one), the item's reads no longer drop the tenant's edit of it. Before, the edit was still stored and every read served the vendor's item: the reads looked for the edit under the package that ships the item now, and the edit names the package that shipped it at the time of the edit.
+
+- **What follows.** The App pair's (`<app>.custom`) declared override whose `overrides.package` names a former owner of the item, and a row bound to the former owner itself (a Regime O save stored before ADR-0146 D11 closed saves naming the read-only base). Each is served at the package that ships the item now, by name (with and without `?package=`), in the list and as the layered read's `effective`.
+- **Same App, read from the install record.** Two installed packages are of one App when `appOf` answers the same App for both over the registry's installed manifests. When the former owner is no longer installed (a rollback), the record is the row's binding to the App's pair, which the save door admits only for a package of that App. Never an id or name prefix.
+- **What never follows.** A row bound to, or declaring, a package of another App; a row of another App's pair; a row whose former owner still ships the item (it stays that package's edit); an `object` (it takes no tenant overlay, `ITEM_LOCKED`); and, between two former owners' rows, neither.
+- **Nothing is written.** The row keeps its binding and body, so a rollback needs no reverse step; the next save of the item writes the current owner's address, as every save does.
@@ -50,7 +50,7 @@ import type { StoredOverlayRow } from './item-lock.js';
 import { overlayMemberWhere } from './migrations/overlay-index.js';
 import type { ObjectStackProtocolImplementation } from './protocol.js';
 import { rowMatchesOverlayWhere, servedOverlayRowCandidates } from './protocol.js';
-import { isServedOverrideRowOf } from './served-override.js';
+import { holdsServedOverlayCandidate } from './protocol-overlay-merge.js';
 import { installedManifestsOfEngine } from './installed-manifests.js';
 
 /**
@@ -64,6 +64,7 @@ export interface EnvironmentRowsHost {
     readonly engine: ObjectStackProtocolImplementation['engine'];
     readonly findEnvironmentRow: ObjectStackProtocolImplementation['findEnvironmentRow'];
     readonly findEnvironmentRows: ObjectStackProtocolImplementation['findEnvironmentRows'];
+    readonly shippedArtifactsOf: ObjectStackProtocolImplementation['shippedArtifactsOf'];
     readonly legacyOrganizationRowsOf: ObjectStackProtocolImplementation['legacyOrganizationRowsOf'];
     readonly rethrowUnlessMetadataStoreUnprovisioned: ObjectStackProtocolImplementation['rethrowUnlessMetadataStoreUnprovisioned'];
     readonly withoutLegacyOrganizationRows: ObjectStackProtocolImplementation['withoutLegacyOrganizationRows'];
@@ -97,7 +98,7 @@ export async function findEnvironmentRow(this: Pick<EnvironmentRowsHost, 'engine
 
 /** The body of `ObjectStackProtocolImplementation#findServedOverlayRow`; the method's docblock there is its contract. */
 export async function findServedOverlayRow(
-    this: Pick<EnvironmentRowsHost, 'engine' | 'findEnvironmentRow'>,
+    this: Pick<EnvironmentRowsHost, 'engine' | 'findEnvironmentRow' | 'findEnvironmentRows' | 'shippedArtifactsOf'>,
     args: {
     type: string;
     name: string;
@@ -119,7 +120,14 @@ export async function findServedOverlayRow(
     // read); with no package context (legacy/runtime reader), any row.
     const other = PLURAL_TO_SINGULAR[args.type] ?? SINGULAR_TO_PLURAL[args.type];
     const installed = installedManifestsOfEngine(this.engine);
-    for (const candidate of servedOverlayRowCandidates({ packageId: args.packageId, servedOverride: args.servedOverride, installed })) {
+    // [#31593] The code packages that ship the item, read once, when a
+    // moved edit of it can be a candidate (`suite-moved-overlay.ts`).
+    let shippers: ReadonlySet<string> | undefined;
+    const ships = (packageId: string): boolean => {
+        shippers ??= shippingPackageIds(this.shippedArtifactsOf(args.type, args.name, undefined, args.member));
+        return shippers.has(packageId);
+    };
+    for (const candidate of servedOverlayRowCandidates({ packageId: args.packageId, servedOverride: args.servedOverride, installed, ships })) {
         const type = candidate.spelling === 'canonical' ? args.type : other;
         if (type === undefined) continue;
         const where: Record<string, unknown> = {
@@ -130,6 +138,17 @@ export async function findServedOverlayRow(
             ...overlayMemberWhere(type, args.member),
         };
         if (candidate.packageId !== undefined) where.package_id = candidate.packageId;
+        if (candidate.moved === 'base') {
+            // [#31593] A row bound to a former owner of the item, at any
+            // binding: every row of the item is read and the predicate
+            // picks; two former owners' rows are never guessed between.
+            const rows = activeRows !== undefined && args.state === 'active'
+                ? activeRows.filter((stored) => rowMatchesOverlayWhere(stored, where))
+                : await this.findEnvironmentRows('sys_metadata', { where, context: { isSystem: true } });
+            const moved = (rows ?? []).filter((row) => holdsServedOverlayCandidate(candidate, row, installed, ships));
+            if (moved.length === 1) return { row: moved[0], overrideOf: candidate.overrideOf };
+            continue;
+        }
         // [#21911, ADR-0096] The explicit system opt-in: a platform store
         // read, which no caller's grants scope — the door that asked
         // already authorized the caller, and the protocol scopes the row
@@ -143,8 +162,10 @@ export async function findServedOverlayRow(
         // candidate only when it declares the override of the address's
         // package ({@link isServedOverrideRowOf}, on the row's own binding and
         // body): an undeclared row of the pair is the pair's own item.
+        // [#31593] …and the moved-override candidate only when its body
+        // declares a former owner of the item ({@link isMovedOverrideRowOf}).
         if (candidate.overrideOf !== undefined) {
-            if (isServedOverrideRowOf(row, candidate.overrideOf, installed)) return { row, overrideOf: candidate.overrideOf };
+            if (holdsServedOverlayCandidate(candidate, row, installed, ships)) return { row, overrideOf: candidate.overrideOf };
             continue;
         }
         return { row };
 
@@ -12,7 +12,8 @@ import {
     type InstalledManifestLookup,
 } from '@objectstack/metadata-core';
 import { canonicalMetaUrlType } from '@objectstack/spec/shared';
-import { isServedOverrideRowOf } from './served-override.js';
+import { isServedOverrideRowOf, type ServedOverrideRow } from './served-override.js';
+import { isMovedBaseRowOf, isMovedOverrideRowOf, type ShipsName } from './suite-moved-overlay.js';
 import {
     listSlotNameOf,
 } from './protocol-object-extension-item.js';
@@ -39,6 +40,40 @@ interface ServedOverlayRowCandidate {
      * package's own item, never the base's.
      */
     readonly overrideOf?: string;
+    /**
+     * [#31593] Set on the two candidates that hold a tenant's edit of the
+     * item from before it moved to `overrideOf` from another package of the
+     * same App (`suite-moved-overlay.ts`): `'override'`, a declared override
+     * in the App's pair that names the former owner
+     * ({@link isMovedOverrideRowOf}), at `packageId` the pair; `'base'`, a row
+     * bound to the former owner itself ({@link isMovedBaseRowOf}), at any
+     * package (`packageId` undefined). A row holds such a candidate only when
+     * its predicate admits it, and it is then served as `overrideOf`'s item.
+     */
+    readonly moved?: 'override' | 'base';
+}
+
+/**
+ * [#31593] Whether `row` holds `candidate`'s place beyond the `where` it
+ * matched: the declared override when the candidate is one
+ * ({@link isServedOverrideRowOf}), the moved edit when the candidate is one
+ * ({@link isMovedOverrideRowOf}, {@link isMovedBaseRowOf}), and any row
+ * otherwise. The one reading both readers of the candidates take
+ * ({@link findServedOverlayRow}, {@link mergePackageAwareOverlay}).
+ */
+export function holdsServedOverlayCandidate(
+    candidate: ServedOverlayRowCandidate,
+    row: ServedOverrideRow,
+    installed: InstalledManifestLookup | undefined,
+    ships: ShipsName | undefined,
+): boolean {
+    if (candidate.overrideOf === undefined) return true;
+    if (installed === undefined) return false;
+    if (candidate.moved === undefined) return isServedOverrideRowOf(row, candidate.overrideOf, installed);
+    if (ships === undefined) return false;
+    return candidate.moved === 'override'
+        ? isMovedOverrideRowOf(row, candidate.overrideOf, installed, ships)
+        : isMovedBaseRowOf(row, candidate.overrideOf, installed, ships);
 }
 
 /**
@@ -112,6 +147,14 @@ export function withoutServedRowName(item: unknown): Record<string, unknown> | u
  *    the save never wrote (#23165's shape). A package-unbound row still wins
  *    over the code package and over another package's row (ADR-0146 D8
  *    item 1) until the migration moves it into the pair (D11).
+ *  - [#31593] …and, when the read also names which packages ship the name
+ *    (`ships`), a tenant's edit of the item from before it moved to the
+ *    package from another package of the same App (`suite-moved-overlay.ts`):
+ *    the App's pair's override that declares the former owner, right after
+ *    the package's own declared override; and a row bound to the former owner
+ *    itself, LAST, after the package-less row, which wins over another
+ *    package's row (D8 item 1). A read that names no `ships` (every write
+ *    address) is unchanged.
  *
  * Both readers of stored content take this order, so they cannot pick
  * differently: {@link ObjectStackProtocolImplementation.findServedOverlayRow}
@@ -133,13 +176,18 @@ export function servedOverlayRowCandidates(address: ServedOverlayAddress): Serve
     const pairs = address.servedOverride === true && typeof base === 'string' && base !== ''
         ? pairsOf(base, address.installed)
         : [];
-    const places: ReadonlyArray<Pick<ServedOverlayRowCandidate, 'packageId' | 'overrideOf'>> = base === null
+    // [#31593] The moved edits are candidates only when the read names the
+    // packages that ship the name (`ships`): the predicates need it.
+    const moved = typeof base === 'string' && base !== '' && address.servedOverride === true && address.ships !== undefined;
+    const places: ReadonlyArray<Pick<ServedOverlayRowCandidate, 'packageId' | 'overrideOf' | 'moved'>> = base === null
         ? [{ packageId: null }]
         : base
             ? [
                 ...pairs.map((pair) => ({ packageId: pair, overrideOf: base })),
+                ...(moved ? pairs.map((pair) => ({ packageId: pair, overrideOf: base, moved: 'override' as const })) : []),
                 { packageId: base },
                 { packageId: null },
+                ...(moved ? [{ packageId: undefined, overrideOf: base, moved: 'base' as const }] : []),
             ]
             : [{ packageId: undefined }];
     return (['canonical', 'other'] as const).flatMap((spelling) =>
@@ -177,6 +225,12 @@ export type ServedOverlayAddress =
         readonly servedOverride: boolean | undefined;
         /** The installed manifests of the registry the read serves, read for the address's pair. */
         readonly installed: InstalledManifestLookup;
+        /**
+         * [#31593] Which code packages ship the item the read serves, in the
+         * registry it serves. Named, the moved edits of the item are
+         * candidates too (`suite-moved-overlay.ts`); omitted, they are not.
+         */
+        readonly ships?: ShipsName;
     };
 
 /**
@@ -359,20 +413,28 @@ export function mergePackageAwareOverlay(
         list: readonly Contribution[],
         real: string | undefined,
     ): { item: any; overrideOf?: string } | undefined => {
+        // [#31593] The code packages that ship the slot's item: its
+        // lower-layer contributions, each under its own package.
+        const shippers = new Set(list
+            .filter((c) => c.stored === undefined && !c.standIn && c.pkg !== undefined)
+            .map((c) => c.pkg as string));
+        const ships = (packageId: string): boolean => shippers.has(packageId);
         for (const candidate of servedOverlayRowCandidates(options.installed !== undefined
-            ? { packageId: real, servedOverride: options.servedOverride, installed: options.installed }
+            ? { packageId: real, servedOverride: options.servedOverride, installed: options.installed, ships }
             : { packageId: real })) {
-            const hit = list.find((c) => c.stored !== undefined
+            const hits = list.filter((c) => c.stored !== undefined
                 && (c.stored.type === type ? 'canonical' : 'other') === candidate.spelling
                 && (candidate.packageId === undefined || (c.pkg ?? null) === candidate.packageId)
                 // [#28409] The pair's row holds the override candidate only
                 // when it declares the override: judged on the row's own
                 // binding (the contribution's `pkg`, the row's `package_id`)
                 // and its body, never on a stamp the body carries.
-                && (candidate.overrideOf === undefined || isServedOverrideRowOf(
-                    { type: c.stored.type, package_id: c.pkg, metadata: c.item }, candidate.overrideOf,
-                    options.installed!,
-                )));
+                // [#31593] …and a moved candidate, when its predicate admits it.
+                && holdsServedOverlayCandidate(candidate,
+                    { type: c.stored.type, package_id: c.pkg, metadata: c.item }, options.installed, ships));
+            // [#31593] Two former owners' rows could follow the item: neither
+            // is guessed (`suite-moved-overlay.ts`).
+            const hit = candidate.moved === 'base' ? (hits.length === 1 ? hits[0] : undefined) : hits[0];
             if (hit) return candidate.overrideOf === undefined ? { item: hit.item } : { item: hit.item, overrideOf: candidate.overrideOf };
         }
         return undefined;
 
@@ -3814,6 +3814,8 @@ export class ObjectStackProtocolImplementation implements
         const host: ThisParameterType<typeof findServedOverlayRow> = {
             get engine() { return readEngine(); },
             findEnvironmentRow: (...a) => this.findEnvironmentRow(...a),
+            findEnvironmentRows: (...a) => this.findEnvironmentRows(...a),
+            shippedArtifactsOf: (...a) => this.shippedArtifactsOf(...a),
         };
         return findServedOverlayRow.call(host, args, activeRows);
     }
Original file line number	Diff line number	Diff line change
`@@ -3814,6 +3814,8 @@ export class ObjectStackProtocolImplementation implements`
`3814`	`3814`	`const host: ThisParameterType<typeof findServedOverlayRow> = {`
`3815`	`3815`	`get engine() { return readEngine(); },`
`3816`	`3816`	`findEnvironmentRow: (...a) => this.findEnvironmentRow(...a),`
	`3817`	`+ findEnvironmentRows: (...a) => this.findEnvironmentRows(...a),`
	`3818`	`+ shippedArtifactsOf: (...a) => this.shippedArtifactsOf(...a),`
`3817`	`3819`	`};`
`3818`	`3820`	`return findServedOverlayRow.call(host, args, activeRows);`
`3819`	`3821`	`}`