diff --git a/‎.changeset/21761-lock-address-selection.md‎
Lines changed: 22 additions & 0 deletions b/‎.changeset/21761-lock-address-selection.md‎
Lines changed: 22 additions & 0 deletions
diff --git a/‎packages/metadata-protocol/src/get-meta-item-cached-etag-scope.test.ts‎
Lines changed: 33 additions & 23 deletions b/‎packages/metadata-protocol/src/get-meta-item-cached-etag-scope.test.ts‎
Lines changed: 33 additions & 23 deletions
diff --git a/‎packages/metadata-protocol/src/item-lock.ts‎
Lines changed: 212 additions & 7 deletions b/‎packages/metadata-protocol/src/item-lock.ts‎
Lines changed: 212 additions & 7 deletions
@@ -0,0 +1,22 @@
+---
+"@objectstack/metadata-protocol": minor
+---
+
+fix(metadata-protocol)!: an item's lock is the strictest lock among the stored rows in scope for its address, at the write doors and on both reads (#21761)
+
+Clause-②: no (narrowing)
+
+ADR-0048 lets one item (type, name, organization scope) hold several stored `sys_metadata` rows: one per package (`?package=` saves) and a package-less one. The ADR-0010 `_lock` gate asked for the item with no package and bound whichever row the store returned first, while `getMetaItem` and `getMetaItemLayered` naming a package reported that package's row. So a read and the door could state two different locks for one item, and the door's answer depended on row order.
+
+Now every caller selects the lock from the item's address through one function: the strictest lock among the item's stored rows in scope. The scope is ADR-0005's (the organization's rows when it holds any row of the item, else the env-wide rows), and within it every row of the item counts, whichever package it is bound to. The strictest lock refuses a write when any of those rows refuses it, and a delete likewise; two rows that refuse different verbs (`no-overlay` and `no-delete`) give `full`. Both reads report that lock in `lock`, `editable` and `deletable`, the served body carries its `_lock` family, and the list item and the `getMetaDiagnostics` locked count follow it. Content stays prefer-local: a read naming a package is still served that package's own row.
+
+**What moves for consumers.** The door now refuses where it used to depend on which row the store returned first:
+
+- a package-less row declaring no lock and a package's row declaring `full`: a save or delete, with or without `?package=`, is refused `403 ITEM_LOCKED` in every row order, where it was admitted when the package-less row came back first;
+- a package's row declaring `none` and a package-less row declaring `full`: refused in every row order, where it was admitted when the package's row came back first. A package row's explicit `none` is not a grant over another row's lock;
+- two rows refusing different verbs (`no-overlay`, `no-delete`): both a save and a delete are refused, where each was admitted under the row order that bound the other row;
+- another package's row of the same name declaring a lock binds a save naming this package too, as it did under the row order that returned it first.
+
+No write the door refused before is admitted now. Both reads become stricter in exactly those arrangements: a read naming a package whose own row declares `none` now reports `editable: false` when another row in scope declares `full`. No key, export, status or error code changes.
+
+<!-- adr-0087: not-required (no-migration-prescription) the write doors refuse, by the strictest lock among the stored rows in scope, writes they used to admit when the store returned a looser row first. No authorable key, spelling, export or stored shape moves: every stored row keeps parsing, nothing is read or rewritten at rest, and which row an administrator meant to lock is not something a ledger entry can rewrite. The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id covers the lock gate (not already-registered); and the change is a door verdict, not a declaration (not runtime-interface-only or type-surface-only). -->
@@ -65,7 +65,7 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import { organizationIdForMetaRead } from '@objectstack/metadata-core';
+import { assertEngineFindOnePredicate, organizationIdForMetaRead } from '@objectstack/metadata-core';
 import { DEFAULT_METADATA_TYPE_REGISTRY } from '@objectstack/spec/kernel';
 import { ObjectStackProtocolImplementation } from './protocol.js';
 
@@ -108,34 +108,44 @@ const storedRow = (
 });
 
 /**
- * The engine double: `findOne` over a row table, plus the registry surface the
- * single-item read path touches on its way past the overlay.
+ * The engine double: `findOne` and `find` over a row table, plus the registry
+ * surface the single-item read path touches on its way past the overlay.
  *
- * ⛔ No `find` / `insert` / `update` / `delete`, deliberately — the read path
- * under test issues exactly one verb, and a double declaring verbs no case
- * exercises would owe `check:engine-double-contract` a dispatch contract that
- * protects nothing. Same shape the sibling org-read-gate pin drives.
+ * ⛔ No `insert` / `update` / `delete`, deliberately — the read path under test
+ * issues two read verbs (`findOne` for the served row, and since #21761 `find`
+ * for the rows its lock is selected from), and a double declaring verbs no
+ * case exercises would owe `check:engine-double-contract` a dispatch contract
+ * that protects nothing. Same shape the sibling org-read-gate pin drives.
  */
 function makeHarness(rows: StoredRow[]) {
+    const matching = (table: string, opts?: { where?: Record<string, unknown> }): StoredRow[] => {
+        if (table !== 'sys_metadata') return [];
+        const where = opts?.where ?? {};
+        // `check:where-matcher` — a hand-written matcher with no combinator
+        // branch reads `$and` as a field name and answers the wrong
+        // question rather than failing. Refuse the shape this double does
+        // not implement, matching the sibling doubles' convention.
+        for (const k of Object.keys(where)) {
+            if (k.startsWith('$')) {
+                throw new Error(`[test double] unsupported WHERE combinator '${k}'`);
+            }
+        }
+        return rows.filter((r) =>
+            Object.entries(where).every(([k, v]) => {
+                if (v === undefined) return true;
+                return (r as unknown as Record<string, unknown>)[k] === v;
+            }),
+        );
+    };
     const engine: any = {
         async findOne(table: string, opts?: { where?: Record<string, unknown> }) {
+            // `check:engine-double-contract` — refuses what the real engine refuses.
+            assertEngineFindOnePredicate(table, opts);
             if (table !== 'sys_metadata') return undefined;
-            const where = opts?.where ?? {};
-            // `check:where-matcher` — a hand-written matcher with no combinator
-            // branch reads `$and` as a field name and answers the wrong
-            // question rather than failing. Refuse the shape this double does
-            // not implement, matching the sibling doubles' convention.
-            for (const k of Object.keys(where)) {
-                if (k.startsWith('$')) {
-                    throw new Error(`[test double] unsupported WHERE combinator '${k}'`);
-                }
-            }
-            return rows.find((r) =>
-                Object.entries(where).every(([k, v]) => {
-                    if (v === undefined) return true;
-                    return (r as unknown as Record<string, unknown>)[k] === v;
-                }),
-            );
+            return matching(table, opts)[0];
+        },
+        async find(table: string, opts?: { where?: Record<string, unknown> }) {
+            return matching(table, opts);
         },
         registry: {
             registerItem: () => undefined,
 
@@ -45,20 +45,56 @@
  * from it. A layer added here without an axis there turns that pin's
  * completeness check red, naming the layer.
  *
- * ⛔ Not a policy of its own. Each caller decides which document it hands each
- * layer: the door hands the canonical-spelling, package-agnostic row; the reads
- * hand the row they serve (see `findServedOverlayRow` for the one declared
- * difference between the two).
+ * ## [#21761] The overlay layer is selected from the item's ADDRESS
+ *
+ * The `overlay` layer is not a row a caller picks. Every caller hands
+ * {@link resolveOverlayLockLayer} the item's address ({@link ItemAddress}) and
+ * a reader of stored rows, and that one function selects the rows in scope
+ * and contributes their strictest lock. So the reads and the doors cannot
+ * select differently: before it, each caller pre-selected the row it handed
+ * this module, and on the package axis (ADR-0048) a read naming a package
+ * reported that package's row while the `_lock` gate bound whichever row
+ * `findOne` returned first.
+ *
+ *  - **The rows in scope.** ADR-0005 precedence, as the reads resolve it: the
+ *    organization's rows when it holds any row of the item, else the env-wide
+ *    rows. Within that scope every row of the item, whichever package it is
+ *    bound to: the address's own package row, the package-less row, and any
+ *    other package's row. Those are every row the doors could bind before this
+ *    rule (they asked with no package, so `findOne` could return any of them).
+ *    A row stored under the type's other spelling is in scope only for a
+ *    caller that passes `otherSpelling` (the reads), and only when no row
+ *    under the canonical spelling is in that scope (the one declared
+ *    difference, #4432).
+ *  - **The lock is the strictest among them.** A write is refused when any
+ *    row in scope refuses it, and a delete likewise. So the lock is never
+ *    more permissive than any row a door could bind before, and it does not
+ *    depend on the order the store returns rows in. For two rows that refuse
+ *    different verbs (`'no-overlay'` and `'no-delete'`) that is `'full'`, the
+ *    state that refuses both.
+ *  - **Content stays prefer-local** (ADR-0048). Only the lock is resolved
+ *    across the rows in scope. The served document is still the row the
+ *    address prefers, and its lock family is the binding layer's.
+ *
+ * ⛔ Not a policy of its own. Which artifact a caller hands the `artifact`
+ * layer is still the caller's lookup.
  */
-import { extractProtection, type MetadataLock, type MetadataLockSource } from '@objectstack/spec/kernel';
+import {
+    MetadataLockSchema,
+    evaluateLockForDelete,
+    evaluateLockForWrite,
+    extractProtection,
+    type MetadataLock,
+    type MetadataLockSource,
+} from '@objectstack/spec/kernel';
 
 /**
  * The layers an item's lock can come from, in precedence order:
  *
  *  - `artifact`: the item a code package's loader registered (ADR-0010 §3.3,
  *    "an overlay cannot loosen a packaged lock");
- *  - `overlay`: the stored `sys_metadata` row (ADR-0005), as the caller
- *    resolved it.
+ *  - `overlay`: the stored `sys_metadata` rows in the item's scope (ADR-0005),
+ *    as {@link resolveOverlayLockLayer} selects them from the item's address.
  */
 export const ITEM_LOCK_LAYERS = Object.freeze(['artifact', 'overlay'] as const);
 
@@ -131,3 +167,172 @@ export async function resolveItemLockLazily(read: {
     }
     return UNLOCKED;
 }
+
+// ── [#21761] The overlay layer, selected from the item's address ─────────────
+
+/**
+ * The fields of an item's address, by name: what a read or a write door names
+ * when it asks about one item. {@link ItemAddress} is derived from it, and the
+ * acceptance pin (`protocol.lock-one-resolution.test.ts`) gives each field an
+ * axis, so a field added here without one turns that pin's completeness check
+ * red, naming the field.
+ */
+export const ITEM_ADDRESS_FIELDS = Object.freeze(['type', 'name', 'organizationId', 'packageId'] as const);
+
+/** One of {@link ITEM_ADDRESS_FIELDS}. */
+export type ItemAddressField = (typeof ITEM_ADDRESS_FIELDS)[number];
+
+/**
+ * An item's address:
+ *
+ *  - `type`: the canonical metadata type (#4432);
+ *  - `name`: the item's name;
+ *  - `organizationId`: the organization the request is scoped to, already
+ *    gated by `organizationIdForMetaRead` (ADR-0005), or `undefined` for the
+ *    env-wide scope alone;
+ *  - `packageId`: the package the request names (ADR-0048 `?package=`), or
+ *    `undefined`. It decides which row's prose the lock carries when several
+ *    rows in scope declare the strictest lock, never which rows are in scope.
+ */
+export type ItemAddress = {
+    readonly type: string;
+    readonly name: string;
+    readonly organizationId: string | undefined;
+    readonly packageId: string | undefined;
+} & { readonly [F in ItemAddressField]: unknown };
+
+/** A stored `sys_metadata` row, as far as the overlay layer reads it. */
+export interface StoredOverlayRow {
+    readonly id?: unknown;
+    readonly package_id?: string | null;
+    readonly metadata?: unknown;
+}
+
+/**
+ * The stored rows of the addressed item in one scope (`organizationId`, or
+ * `null` for env-wide) under one spelling of its type: `'canonical'`, or
+ * `'other'` (the type's singular/plural twin, pre-#4432 residue). Every row of
+ * the item there, whichever package it is bound to. A failed read throws: each
+ * caller owns its #5532 / #5706 discrimination.
+ */
+export type StoredOverlayRowReader = (
+    organizationId: string | null,
+    spelling: 'canonical' | 'other',
+) => readonly StoredOverlayRow[] | Promise<readonly StoredOverlayRow[]>;
+
+/**
+ * The body a stored `sys_metadata` row holds, as written: the document a row
+ * contributes, parsed the one way the `_lock` gate and both reads parse it. No
+ * conversion is replayed: none touches the `_lock` family.
+ */
+export function storedRowDocument(row: { metadata?: unknown }): unknown {
+    return typeof row.metadata === 'string' ? JSON.parse(row.metadata) : row.metadata;
+}
+
+/**
+ * The strictest of `locks`: the state that refuses a write when any of them
+ * does, and a delete when any of them does. Read off the lock algebra itself
+ * (`evaluateLockForWrite` / `evaluateLockForDelete`), so `'no-overlay'` with
+ * `'no-delete'` is `'full'`, and no lock is `'none'`.
+ */
+export function strictestLock(locks: readonly MetadataLock[]): MetadataLock {
+    const refusesWrite = locks.some((lock) => evaluateLockForWrite(lock) !== null);
+    const refusesDelete = locks.some((lock) => evaluateLockForDelete(lock) !== null);
+    const strictest = MetadataLockSchema.options.find((state) =>
+        (evaluateLockForWrite(state) !== null) === refusesWrite
+        && (evaluateLockForDelete(state) !== null) === refusesDelete);
+    if (strictest === undefined) {
+        // Unreachable while the lock algebra covers all four verdict pairs; a
+        // state added without a write/delete answer must fail here, loudly.
+        throw new Error(`No ADR-0010 lock state refuses write=${refusesWrite}, delete=${refusesDelete}.`);
+    }
+    return strictest;
+}
+
+/** The ADR-0010 lock family a stored body carries, and nothing else. */
+const LOCK_FAMILY_KEYS = Object.freeze(['_lock', '_lockReason', '_lockDocsUrl', '_lockSource'] as const);
+
+/**
+ * [#21761] THE overlay layer's selection. The document the `overlay` layer of
+ * {@link resolveItemLock} gets for `address`: the strictest lock among the
+ * stored rows in the address's scope, read through `rowsIn`. See this module's
+ * header for the rule. `undefined` when no row is in scope or none of them
+ * declares a lock.
+ *
+ * The document is the lock family alone. It is the family of the row that
+ * declares the strictest lock, preferring the address's own package row, then
+ * the package-less row, then the other packages' rows by package id, so its
+ * prose (`_lockReason`, `_lockDocsUrl`, `_lockSource`) is the same whatever
+ * order the store returned the rows in. When no single row declares it (one
+ * row refuses writes and another deletes), the document is that lock with no
+ * prose.
+ *
+ * Every caller that enforces or reports an item's lock passes its address
+ * here: the `_lock` gate (`otherSpelling: false`, #4432), both item reads and
+ * the list (`otherSpelling: true`). Rows are read scope by scope and stop at
+ * the first scope that holds one, so the gate reads no more than it did when
+ * it read one row.
+ */
+export async function resolveOverlayLockLayer(
+    address: ItemAddress,
+    rowsIn: StoredOverlayRowReader,
+    options: { readonly otherSpelling: boolean },
+): Promise<unknown> {
+    const scopes: Array<string | null> = address.organizationId ? [address.organizationId, null] : [null];
+    for (const scope of scopes) {
+        let rows = await rowsIn(scope, 'canonical');
+        if (rows.length === 0 && options.otherSpelling) rows = await rowsIn(scope, 'other');
+        if (rows.length > 0) return strictestRowLockDocument(rows, address.packageId);
+    }
+    return undefined;
+}
+
+function strictestRowLockDocument(rows: readonly StoredOverlayRow[], packageId: string | undefined): unknown {
+    const declared = rows.map((row) => {
+        const document = storedRowDocument(row);
+        return { row, document, lock: extractProtection(document).lock };
+    });
+    const lock = strictestLock(declared.map((d) => d.lock));
+    if (lock === 'none') return undefined;
+    const rank = (row: StoredOverlayRow): number => {
+        const own = row.package_id ?? null;
+        if (packageId !== undefined && own === packageId) return 0;
+        return own === null ? 1 : 2;
+    };
+    const ordered = [...declared].sort((a, b) =>
+        rank(a.row) - rank(b.row)
+        || String(a.row.package_id ?? '').localeCompare(String(b.row.package_id ?? ''))
+        || String(a.row.id ?? '').localeCompare(String(b.row.id ?? '')));
+    const binding = ordered.find((d) => d.lock === lock);
+    if (binding === undefined) return { _lock: lock };
+    const source = binding.document as Record<string, unknown>;
+    const family: Record<string, unknown> = {};
+    for (const key of LOCK_FAMILY_KEYS) {
+        if (source[key] !== undefined) family[key] = source[key];
+    }
+    return family;
+}
+
+/**
+ * [#21761] `document` with the lock family of the `overlay` layer
+ * ({@link resolveOverlayLockLayer}) when that layer binds, so a served body
+ * states the lock the envelope reports even when the rows in scope that bind
+ * are not the row the body was served from. A key that layer's document does
+ * not declare is removed. Returns `document` itself when the overlay layer does
+ * not bind or nothing changes (the binding row is the served row), and a copy
+ * otherwise. The `artifact` layer's family is `mergeArtifactProtection`'s to
+ * put, as before.
+ */
+export function withOverlayLockFamily(document: unknown, layers: ItemLockLayers): unknown {
+    if (!document || typeof document !== 'object' || Array.isArray(document)) return document;
+    if (resolveItemLock(layers).layer !== 'overlay') return document;
+    const family = layers.overlay as Record<string, unknown>;
+    const current = document as Record<string, unknown>;
+    if (LOCK_FAMILY_KEYS.every((key) => current[key] === family[key])) return document;
+    const out: Record<string, unknown> = { ...current };
+    for (const key of LOCK_FAMILY_KEYS) {
+        if (family[key] === undefined) delete out[key];
+        else out[key] = family[key];
+    }
+    return out;
+}