fix(metadata-protocol)!: the exact read no longer serves an undeclared App-pair row the registry binds to no package; it adopts SchemaRegistry#overlayRowBinding over the served holders (ADR-0150 D4)

.changeset/32561-exact-read-adopts-pair-row-binding.md

@@ -0,0 +1,22 @@
+---
+'@objectstack/metadata-protocol': minor
+'@objectstack/objectql': minor
+---
+
+fix(metadata-protocol)!: the exact read (`?package=X`) no longer serves an undeclared App-pair row the registry binds to no package (ADR-0150 D4, red line 2)
+
+Clause-②: yes (narrowing) — two exact reads that served a row of an App's customization pair now answer the address's own shipped item: `?package=X` for an undeclared pair row of the very bundle member a bundle addition of another package of the App ships, and a package's address for an undeclared pair row while another App's shared pair stores an undeclared row of the name. In both the registry binds the row to no package. First-party packages in either position: 0. The widening is one public method: `SchemaRegistry#overlayRowBinding(type, name, item)`, the registry's binding of a stored row, read-only, which the exact read asks.
+Metadata-protocol: narrowed
+
+<!-- adr-0087: registered pair-row-exact-read-no-owner -->
+
+**BREAKING** for two exact reads, both of an undeclared row of an App's customization pair (`<app>.custom`, a row with no `overrides.package`). An undeclared row that could customize either of two packages' members is not attributed to one of them (red line 2). To keep such a row on the package whose locale it customizes, save it with `overrides.package` naming that package, the package of the App that ships the locale: the save door accepts it (it already prescribes it, refusing `403 NOT_OVERRIDABLE` a new undeclared row of a locale an installed package ships), and `?package=<that package>` then serves the row. A row of a locale no package ships stays readable at `?package=<app>.custom`.
+
+The exact read's owner check (`pairRowOnAddress`) counted the holders after the registry had bound the row, so a bundle addition was no holder there, and it never read another App's pair. The registry (`SchemaRegistry#pairRowBinding`, since #32408) counts an addition that ships the row's member as a second owner, and binds a row whose count would read another shared pair's undeclared row to no package. The exact read now adopts that binding: `SchemaRegistry#overlayRowBinding(type, name, item)`, a new read-only method, answers it over the holders the exact read serves (a disabled package holds no name, ADR-0150 D3), and `pairRowOnAddress` treats an undeclared pair row as no member of an address whose one owner it does not bind the row to. It adds no count of its own.
+
+What moves (each line FROM → TO), with App A, X a package of A holding an email template's name, Z a package of A depending on X that ships only `fr-FR` of it (a bundle addition), and `A.custom` storing an undeclared `fr-FR` row:
+
+- `?package=X&member=fr-FR`: FROM the row TO X's own `fr-FR` (none, `404`). X's list and execution list: FROM carrying the row TO leaving it out. Either order: Z installed before the row (reached by a hydrated row; the save door refuses that write `403 NOT_OVERRIDABLE`, prescribing the declaration) or after it (the row saved and published while X alone held the name, then Z installed). `?package=Z` keeps Z's own `fr-FR`; `?package=A.custom` keeps the row.
+- `?package=Y` / `?package=P` when App A's pair and App B's pair each store an undeclared row of the name (the registry binds neither): FROM the pair's row TO the package's own item of that member (none). Each pair's own address keeps its row.
+
+Unchanged: a row declaring its base (`overrides.package`) binds and serves as declared; the App's own address keeps an undeclared row of its own pair (#28390 ruling A); two holders that could own a row still refuse `409` naming both; a row whose one owner the registry binds it to is served there as before; a registry without `overlayRowBinding` keeps the exact read's own count. With one of two holders of the name disabled, the enabled holder's address, list and execution list keep an undeclared row of the pair (#32183, epic ruling R4-A): the adoption counts the served holders, as the exact read does, while the registry's own readers keep counting every holder, so a disable never moves their binding.

.changeset/32561-pair-row-exact-read-semantic-entry.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the protocol upgrade guide names the two exact reads #32561 narrows: an undeclared row of an App's customization pair is no member of a package's address when the registry binds it to no package, because another package of the App ships its locale as a bundle addition or another App's shared pair stores an undeclared row of the name
+
+Clause-②: no
+Metadata-protocol: none
+
+The semantic entry `pair-row-exact-read-no-owner` (`packages/spec/src/migrations/entries/semantic/18.pair-row-exact-read-no-owner.ts`) registers the narrowing `.changeset/32561-exact-read-adopts-pair-row-binding.md` declares (ADR-0087, `adr-0087: registered`). There is no automatic rewrite, because which package's locale a pair row customizes is a judgement about that row. The remedy it names is the one the save door accepts: declare the package that ships the locale (`overrides.package`). It adds no key and no export.

packages/metadata-protocol/src/protocol-exact-qualifier.ts

@@ -85,6 +85,16 @@ interface ExactQualifierRegistry {
     getEnvironmentScopedItem(type: string, name: string, member?: string): unknown;
     getPackageScopedItem(type: string, name: string, packageId: string, member?: string): unknown;
     getPackage?(id: string): unknown;
+    /**
+     * [#32561] The package the registry binds a stored row of `(type, name)`
+     * to (objectql's `overlayRowBinding`, the one owner rule every registry
+     * reader asks, counted over the served holders as this read counts them):
+     * a package id, `null` for the environment's own item, or `undefined` for
+     * no package. The exact read adopts it for an undeclared pair row
+     * ({@link pairRowOnAddress}); a registry without it keeps the exact read's
+     * own count.
+     */
+    overlayRowBinding?(type: string, name: string, item: unknown): string | null | undefined;
 }
 
 /**
@@ -422,7 +432,8 @@ export function exactQualifierItem(
     const bases = [address.packageId, ...address.registryHolders];
     if (bases.some((base) => isPairOf(served, base, installed))) {
         const verdict = pairRowOnAddress(served, item, address.packageId, bases,
-            registry.packageScopedHoldersOf(request.type, request.name) ?? [], installed);
+            registry.packageScopedHoldersOf(request.type, request.name) ?? [], installed,
+            registryRowBinding(registry, request.type, request.name, item));
         if (verdict === 'serve') return item;
         if (verdict !== 'not-member') {
             throw refusal(request.type, request.name, address.packageId, 'ambiguous-in-closure',
@@ -716,7 +727,22 @@ export function pairMemberWithheldAt(
     const registry = exactQualifierRegistry(host);
     if (!registry || (registry as { readsByPackage?(type: string): boolean }).readsByPackage?.(type) !== true) return false;
     return pairRowOnAddress(pairId, item, base, [base], registry.packageScopedHoldersOf(type, name) ?? [],
-        installedManifestsOfEngine(host.engine)) !== 'serve';
+        installedManifestsOfEngine(host.engine), registryRowBinding(registry, type, name, item)) !== 'serve';
+}
+
+/**
+ * [#32561] The registry's binding of the stored row `item`, read lazily
+ * ({@link ExactQualifierRegistry.overlayRowBinding}), or `undefined` when the
+ * registry does not answer it (the exact read then keeps its own count).
+ */
+function registryRowBinding(
+    registry: ExactQualifierRegistry,
+    type: string,
+    name: string,
+    item: unknown,
+): (() => string | null | undefined) | undefined {
+    const read = registry.overlayRowBinding;
+    return typeof read === 'function' ? () => read.call(registry, type, name, item) : undefined;
 }
 
 /**
@@ -735,6 +761,16 @@ export function pairMemberWithheldAt(
  * - Else two or more holders could own it: refuse, naming every one (F2).
  * - Else a sole owner that is not one of the address's bases owns it: not
  *   this address's member (S2).
+ * - [#32561] Else a sole owner the registry does not bind the row to
+ *   (`registryBinding`, the registry's one owner rule: `pairRowBinding`
+ *   counts a bundle addition that ships the row's member as an owner, and
+ *   binds a row whose count would read another shared pair's undeclared row
+ *   to no package) is no owner of it: not this address's member, so the
+ *   address answers its own shipped item (epic ruling, red line 2). The
+ *   exact read adopts the registry's count rather than counting again. Both
+ *   count the served holders (a disabled package holds no name, ADR-0150
+ *   D3): with one of two holders disabled, the row stays the enabled one's
+ *   member (#32183, epic ruling R4-A).
  * - Else (the sole owner is a base, or no holder pairs it) it is served.
  */
 export function pairRowOnAddress(
@@ -744,13 +780,15 @@ export function pairRowOnAddress(
     bases: readonly string[],
     holders: readonly string[],
     installed: InstalledManifestLookup,
+    registryBinding?: () => string | null | undefined,
 ): 'serve' | 'not-member' | { refuse: string[] } {
     const declared = declaredOverrideBase(item);
     if (declared !== undefined) return bases.includes(declared) ? 'serve' : 'not-member';
     if (isAppPairOf(pairId, addressPackageId, installed)) return 'serve';
     const owners = pairMemberOwners(pairId, holders, installed, item);
     if (owners.length > 1) return { refuse: owners };
     if (owners.length === 1 && !bases.includes(owners[0]!)) return 'not-member';
+    if (owners.length === 1 && registryBinding !== undefined && registryBinding() !== owners[0]) return 'not-member';
     return 'serve';
 }