@objectstack/metadata 17.2.0 → 17.4.0

package/dist/node.cjs

@@ -38,9 +38,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/routes/hmr-routes.ts
 var hmr_routes_exports = {};
 __export(hmr_routes_exports, {
+  isDevMetadataEndpointEnabled: () => isDevMetadataEndpointEnabled,
   registerMetadataHmrRoutes: () => registerMetadataHmrRoutes
 });
+function isDevMetadataEndpointEnabled(env = process.env) {
+  return (env.NODE_ENV ?? "").trim().toLowerCase() === "development";
+}
 function registerMetadataHmrRoutes(app, manager, options = {}) {
+  if (!isDevMetadataEndpointEnabled()) return null;
   const routePath = options.path ?? "/api/v1/dev/metadata-events";
   const listeners = /* @__PURE__ */ new Set();
   const broadcast = (evt) => {
@@ -192,6 +197,9 @@ var init_hmr_routes = __esm({
 // src/node.ts
 var node_exports = {};
 __export(node_exports, {
+  AMBIGUOUS_METADATA_STEM_CODE: () => AMBIGUOUS_METADATA_STEM_CODE,
+  AMBIGUOUS_METADATA_STEM_STATUS: () => AMBIGUOUS_METADATA_STEM_STATUS,
+  AmbiguousMetadataStemError: () => AmbiguousMetadataStemError,
   DatabaseLoader: () => DatabaseLoader,
   FilesystemLoader: () => FilesystemLoader,
   HistoryCleanupManager: () => HistoryCleanupManager,
@@ -202,13 +210,15 @@ __export(node_exports, {
   Migration: () => migration_exports,
   NodeMetadataManager: () => NodeMetadataManager,
   RemoteLoader: () => RemoteLoader,
-  SysMetadataHistoryObject: () => import_metadata_core3.SysMetadataHistoryObject,
-  SysMetadataObject: () => import_metadata_core3.SysMetadataObject,
+  SysMetadataHistoryObject: () => import_metadata_core4.SysMetadataHistoryObject,
+  SysMetadataObject: () => import_metadata_core4.SysMetadataObject,
   TypeScriptSerializer: () => TypeScriptSerializer,
   YAMLSerializer: () => YAMLSerializer,
   calculateChecksum: () => calculateChecksum,
+  deriveViewContainerObject: () => deriveViewContainerObject,
   generateDiffSummary: () => generateDiffSummary,
-  generateSimpleDiff: () => generateSimpleDiff
+  generateSimpleDiff: () => generateSimpleDiff,
+  isAmbiguousMetadataStemError: () => isAmbiguousMetadataStemError
 });
 module.exports = __toCommonJS(node_exports);
 
@@ -386,7 +396,7 @@ export default metadata;
 };
 
 // src/loaders/database-loader.ts
-var import_metadata_core = require("@objectstack/metadata-core");
+var import_metadata_core2 = require("@objectstack/metadata-core");
 var import_spec = require("@objectstack/spec");
 var import_shared = require("@objectstack/spec/shared");
 
@@ -554,141 +564,49 @@ var LRUCache = class {
   }
 };
 
-// src/utils/schema-sync-errors.ts
+// src/loaders/database-loader.ts
 var import_types = require("@objectstack/types");
-var ALREADY_EXISTS = {
-  codes: /* @__PURE__ */ new Set([
-    // PostgreSQL SQLSTATE (class 42 — syntax error or access rule violation)
-    "42P07",
-    // duplicate_table
-    "42701",
-    // duplicate_column
-    "42710",
-    // duplicate_object — index / constraint already exists
-    // MySQL / MariaDB (mysql2 puts the symbolic name on `code`)
-    "ER_TABLE_EXISTS_ERROR",
-    // 1050
-    "ER_DUP_FIELDNAME",
-    // 1060
-    "ER_DUP_KEYNAME"
-    // 1061
-  ]),
-  errnos: /* @__PURE__ */ new Set([1050, 1060, 1061]),
-  /**
-   * Message fallback for drivers that carry no machine-readable code —
-   * notably SQLite, whose `code` is the undifferentiated `SQLITE_ERROR` for
-   * every DDL failure, so the message is the only signal available:
-   *   - `table sys_metadata already exists`
-   *   - `duplicate column name: environment_id`
-   *   - `index idx_x already exists`
-   * Postgres phrases its own as `relation "x" already exists` /
-   * `column "x" of relation "y" already exists`, which matches the same test.
-   */
-  message: /already exists|duplicate column name|duplicate key name/i
-};
-var MISSING_TABLE = {
-  codes: /* @__PURE__ */ new Set([
-    "42P01",
-    // PostgreSQL undefined_table
-    "ER_NO_SUCH_TABLE"
-    // MySQL / MariaDB 1146
-  ]),
-  errnos: /* @__PURE__ */ new Set([1146]),
-  /**
-   *   - SQLite / libsql: `no such table: sys_metadata_history`
-   *   - PostgreSQL:      `relation "sys_metadata_history" does not exist`
-   *   - MySQL/MariaDB:   `Table 'app.sys_metadata_history' doesn't exist`
-   */
-  message: /no such table|relation ["'`][^"'`]+["'`] does not exist|table ["'`][^"'`]+["'`] doesn'?t exist|unknown table/i,
-  excludes: {
-    /**
-     * Exactly the three SQLSTATEs the docblock above already names as
-     * must-stay-loud neighbours of `does not exist`. They are listed here
-     * rather than merely trusted to miss the message test, because two of
-     * them (42703 columns, 42704 constraints/triggers) have a phrasing that
-     * *does* hit it, and because a code is a fact where prose is a guess.
-     *
-     * Postgres-shaped on purpose: measured, neither MySQL
-     * (`Unknown column 'label' in 'field list'`) nor SQLite
-     * (`no such column: bogus`, `table t has no column named label`)
-     * phrases a sub-object failure so that a missing-table phrase falls out
-     * of it, so there is nothing there to exclude. Adding their codes would
-     * be surface with no defect behind it.
-     */
-    codes: /* @__PURE__ */ new Set([
-      "42703",
-      // undefined_column
-      "42704",
-      // undefined_object — constraint, trigger, role, type, …
-      "3D000"
-      // invalid_catalog_name — `database "x" does not exist`
-    ]),
-    /**
-     * `«sub-object» "x" of relation "y" …` — Postgres' phrasing for a
-     * failure about something *inside* a relation, which therefore says the
-     * relation itself is present. The two in-repo siblings that carry this
-     * phrase are `mapDataError` (`packages/rest`, #5352) and
-     * `service-analytics`'s missing-column subtraction (#6035/PR #6346).
-     *
-     * [#6615] All three now read one home — `@objectstack/types` — instead
-     * of three hand-kept copies, so the phrase can no longer be taught to
-     * the repo a fourth time or drift in one package only. The **width**
-     * difference that used to justify the copy is preserved and is the
-     * reason the home exports two functions rather than one: those two
-     * *extract* the column name to phrase a better error, so a miss costs a
-     * vaguer message; this one *excludes*, so a miss restores the
-     * corruption. {@link isRelationSubObjectPhrase} is therefore the wider
-     * question — it drops their `column`/`[a-z0-9_]+`/`does not exist`
-     * anchors: any sub-object, any quoted identifier, any verdict.
-     * Over-matching here only ever converts a benign verdict into a loud
-     * one, which is the direction this whole module already errs in.
-     */
-    matchesMessage: import_types.isRelationSubObjectPhrase
+
+// src/migrations/driver-exec.ts
+function resolveDriverExec(driver) {
+  const candidate = driver;
+  if (!candidate) return void 0;
+  if (typeof candidate.execute === "function") {
+    return (sql, bindings) => candidate.execute(sql, bindings ? [...bindings] : []);
   }
-};
-var MAX_CAUSE_DEPTH = 4;
-function matchesDriverError(error, signature, depth) {
-  if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH) return false;
-  if (typeof error === "string") {
-    if (signature.excludes?.matchesMessage(error)) return false;
-    return signature.message.test(error);
-  }
-  if (typeof error !== "object") return false;
-  const err = error;
-  const excludes = signature.excludes;
-  if (excludes) {
-    if (typeof err.code === "string" && excludes.codes.has(err.code)) return false;
-    if (typeof err.message === "string" && excludes.matchesMessage(err.message)) return false;
-  }
-  if (typeof err.code === "string" && signature.codes.has(err.code)) return true;
-  if (typeof err.errno === "number" && signature.errnos.has(err.errno)) return true;
-  if (typeof err.message === "string" && signature.message.test(err.message)) return true;
-  return matchesDriverError(err.cause, signature, depth + 1);
-}
-function isSchemaAlreadyExistsError(error, depth = 0) {
-  return matchesDriverError(error, ALREADY_EXISTS, depth);
+  if (typeof candidate.raw === "function") {
+    return (sql, bindings) => candidate.raw(sql, bindings ? [...bindings] : []);
+  }
+  return void 0;
 }
-function isMissingTableError(error, depth = 0) {
-  return matchesDriverError(error, MISSING_TABLE, depth);
+function driverExecRefusal(helper) {
+  return `${helper}: driver must expose an .execute(sql, bindings?) or .raw(sql, bindings?) method. SqlDriver (better-sqlite3/knex) exposes .execute(), as does its SqliteWasmDriver subclass; cloud-side TursoDriver also conforms.`;
 }
 
 // src/migrations/migrate-project-id-to-environment-id.ts
-var AFFECTED_TABLES = [
-  "sys_metadata",
-  "sys_metadata_history"
-];
+var import_metadata_core = require("@objectstack/metadata-core");
+var SOURCE_COLUMN = "project_id";
+var TARGET_COLUMN = "environment_id";
+var CANDIDATE_OBJECTS = [import_metadata_core.SysMetadataObject, import_metadata_core.SysMetadataHistoryObject];
+function declaresColumn(object, column) {
+  return Object.prototype.hasOwnProperty.call(object.fields ?? {}, column);
+}
+var CANDIDATE_TABLES = CANDIDATE_OBJECTS.map((o) => o.name);
+var AFFECTED_TABLES = CANDIDATE_OBJECTS.filter((o) => declaresColumn(o, TARGET_COLUMN)).map((o) => o.name);
 async function migrateProjectIdToEnvironmentId(driver) {
-  const driverAny = driver;
-  if (typeof driverAny.raw !== "function") {
-    throw new Error(
-      "migrateProjectIdToEnvironmentId: driver must expose a .raw(sql, bindings?) method. migrateProjectIdToEnvironmentId: driver must expose a .raw(sql, bindings?) method. SqlDriver (better-sqlite3/knex) supports this; cloud-side TursoDriver also conforms."
-    );
+  const exec = resolveDriverExec(driver);
+  if (!exec) {
+    throw new Error(driverExecRefusal("migrateProjectIdToEnvironmentId"));
   }
   const results = [];
-  for (const table of AFFECTED_TABLES) {
+  for (const table of CANDIDATE_TABLES) {
+    if (!AFFECTED_TABLES.includes(table)) {
+      results.push({ table, status: "skipped_not_declared" });
+      continue;
+    }
     try {
-      const hasColumn = await _columnExists(driverAny, table, "project_id");
-      const alreadyMigrated = await _columnExists(driverAny, table, "environment_id");
+      const hasColumn = await _columnExists(exec, table, SOURCE_COLUMN);
+      const alreadyMigrated = await _columnExists(exec, table, TARGET_COLUMN);
       if (alreadyMigrated && !hasColumn) {
         results.push({ table, status: "already_done" });
         continue;
@@ -697,8 +615,8 @@ async function migrateProjectIdToEnvironmentId(driver) {
         results.push({ table, status: "table_missing" });
         continue;
       }
-      await driverAny.raw(
-        `ALTER TABLE "${table}" RENAME COLUMN project_id TO environment_id`
+      await exec(
+        `ALTER TABLE "${table}" RENAME COLUMN ${SOURCE_COLUMN} TO ${TARGET_COLUMN}`
       );
       results.push({ table, status: "renamed" });
     } catch (err) {
@@ -707,14 +625,14 @@ async function migrateProjectIdToEnvironmentId(driver) {
   }
   return results;
 }
-async function _columnExists(driver, table, column) {
+async function _columnExists(exec, table, column) {
   try {
-    const rows = await driver.raw(`PRAGMA table_info("${table}")`);
+    const rows = await exec(`PRAGMA table_info("${table}")`);
     if (Array.isArray(rows) && rows.length > 0) {
       const list2 = Array.isArray(rows[0]) ? rows[0] : rows;
       return list2.some((r) => r?.name === column);
     }
-    const result = await driver.raw(
+    const result = await exec(
       `SELECT column_name FROM information_schema.columns WHERE table_name = ? AND column_name = ?`,
       [table, column]
     );
@@ -726,6 +644,16 @@ async function _columnExists(driver, table, column) {
 }
 
 // src/loaders/database-loader.ts
+function canonicalIsoInstant(value) {
+  if (value === null || value === void 0) return void 0;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? void 0 : value.toISOString();
+  if (typeof value === "string") return value;
+  return String(value);
+}
+function isoFromValidDate(value) {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+  return value;
+}
 var DatabaseLoader = class {
   constructor(options) {
     this.contract = {
@@ -774,7 +702,7 @@ var DatabaseLoader = class {
     if (cacheEnabled) {
       const lruOpts = {
         maxSize: cacheOpts?.maxSize ?? 500,
-        ttl: cacheOpts?.ttl ?? 6e4
+        ttl: cacheOpts?.ttlMs ?? 6e4
       };
       this.loadCache = new LRUCache(lruOpts);
       this.loadManyCache = new LRUCache(lruOpts);
@@ -862,9 +790,11 @@ var DatabaseLoader = class {
     }
     return this.driver.create(table, data);
   }
+  // `null` is the driver path's not-found answer (`IDataDriver.update()`,
+  // #13878); both callers here resolve the row first and discard the result.
   async _update(table, id, data) {
     if (this.engine) {
-      return this.engine.update(table, { id, ...data });
+      return this.engine.update(table, { ...data, id });
     }
     return this.driver.update(table, id, data);
   }
@@ -909,7 +839,7 @@ var DatabaseLoader = class {
       }
       return max + 1;
     } catch (error) {
-      if (isMissingTableError(error)) return 1;
+      if ((0, import_types.isMissingTableError)(error, this.historyTableName)) return 1;
       throw error;
     }
   }
@@ -947,11 +877,11 @@ var DatabaseLoader = class {
     }
     try {
       await this.driver.syncSchema(this.tableName, {
-        ...import_metadata_core.SysMetadataObject,
+        ...import_metadata_core2.SysMetadataObject,
         name: this.tableName
       });
     } catch (error) {
-      if (!isSchemaAlreadyExistsError(error)) {
+      if (!(0, import_types.isSchemaAlreadyExistsError)(error)) {
         if (!this.schemaFailureReported) {
           this.schemaFailureReported = true;
           console.error(
@@ -986,7 +916,7 @@ var DatabaseLoader = class {
     }
     try {
       await this.driver.syncSchema(this.historyTableName, {
-        ...import_metadata_core.SysMetadataHistoryObject,
+        ...import_metadata_core2.SysMetadataHistoryObject,
         name: this.historyTableName
       });
       if (this.historySchemaFailureReported) {
@@ -997,7 +927,7 @@ var DatabaseLoader = class {
       }
       this.historySchemaReady = true;
     } catch (error) {
-      if (isSchemaAlreadyExistsError(error)) {
+      if ((0, import_types.isSchemaAlreadyExistsError)(error)) {
         this.historySchemaReady = true;
         return;
       }
@@ -1155,9 +1085,9 @@ var DatabaseLoader = class {
       source: row.source,
       tags: row.tags ? typeof row.tags === "string" ? JSON.parse(row.tags) : row.tags : void 0,
       createdBy: row.created_by,
-      createdAt: row.created_at,
+      createdAt: isoFromValidDate(row.created_at),
       updatedBy: row.updated_by,
-      updatedAt: row.updated_at
+      updatedAt: isoFromValidDate(row.updated_at)
     };
   }
   // ==========================================
@@ -1208,7 +1138,7 @@ var DatabaseLoader = class {
    *          with its empty value.
    */
   rethrowUnlessTableUnprovisioned(error) {
-    if (isMissingTableError(error)) return;
+    if ((0, import_types.isMissingTableError)(error, this.tableName)) return;
     throw error;
   }
   // ==========================================
@@ -1258,17 +1188,38 @@ var DatabaseLoader = class {
       };
     }
   }
-  async loadMany(type, _options) {
+  /**
+   * The one type-wide read both plural readers share: every row of `type`, each
+   * body paired with the `name` COLUMN it was stored under.
+   *
+   * [#14205] `name` is `null` only for a row whose key column does not hold a
+   * string. Such a row is still a body {@link loadMany} must return — dropping
+   * it would change what consumers see today — but it has no usable identity,
+   * so {@link loadManyKeyed} filters it out rather than invent one.
+   *
+   * One query and one cache entry serve both methods: `loadMany()` used to own
+   * them, and splitting them would have made every keyed `list()` read miss the
+   * cache and re-hit the database.
+   */
+  async readTypeRows(type) {
     await this.ensureSchema();
     if (this.loadManyCache) {
       const cached = this.loadManyCache.get(type);
-      if (cached !== void 0) return cached;
+      if (cached !== void 0) {
+        return cached;
+      }
     }
     try {
       const rows = await this._find(this.tableName, {
         where: this.baseFilter(type)
       });
-      const result = rows.map((row) => this.rowToData(row)).filter((data) => data !== null);
+      const result = [];
+      for (const row of rows) {
+        const data = this.rowToData(row);
+        if (data === null) continue;
+        const name = row.name;
+        result.push({ name: typeof name === "string" && name !== "" ? name : null, data });
+      }
       this.loadManyCache?.set(type, result);
       return result;
     } catch (error) {
@@ -1276,6 +1227,29 @@ var DatabaseLoader = class {
       return [];
     }
   }
+  async loadMany(type, _options) {
+    return (await this.readTypeRows(type)).map((entry) => entry.data);
+  }
+  /**
+   * [#14205] The keyed half of {@link loadMany} — see
+   * {@link MetadataKeyedItem} for why the row key travels beside the body
+   * instead of inside it.
+   *
+   * `DatabaseLoader` is where the defect was measured: an aggregated view
+   * container is written by `register('view', OBJECT, container)` and stored
+   * verbatim, so its `sys_metadata` row carries the identity in the `name`
+   * COLUMN and the body has none. {@link rowToData} returns that body without
+   * folding the column in — deliberately, and unchanged here.
+   */
+  async loadManyKeyed(type, _options) {
+    const entries = await this.readTypeRows(type);
+    const keyed = [];
+    for (const entry of entries) {
+      if (entry.name === null) continue;
+      keyed.push({ name: entry.name, data: entry.data });
+    }
+    return keyed;
+  }
   async exists(type, name) {
     await this.ensureSchema();
     if (this.loadCache) {
@@ -1311,7 +1285,7 @@ var DatabaseLoader = class {
       const metadataStr = typeof row.metadata === "string" ? row.metadata : JSON.stringify(row.metadata);
       const stats = {
         size: metadataStr.length,
-        mtime: record.updatedAt ?? record.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+        mtime: canonicalIsoInstant(record.updatedAt ?? record.createdAt) ?? (/* @__PURE__ */ new Date()).toISOString(),
         format: "json",
         etag: record.checksum
       };
@@ -1372,7 +1346,7 @@ var DatabaseLoader = class {
       changeNote: row.change_note,
       organizationId: row.organization_id,
       recordedBy: row.recorded_by,
-      recordedAt: row.recorded_at
+      recordedAt: isoFromValidDate(row.recorded_at)
     };
   }
   /**
@@ -1429,7 +1403,7 @@ var DatabaseLoader = class {
         changeNote: row.change_note,
         organizationId: row.organization_id,
         recordedBy: row.recorded_by,
-        recordedAt: row.recorded_at
+        recordedAt: isoFromValidDate(row.recorded_at)
       };
     });
     return { records: result, total, hasMore };
@@ -1578,6 +1552,33 @@ function generateId() {
   return `meta_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
 }
 
+// src/loaders/ambiguous-metadata-stem.ts
+var AMBIGUOUS_METADATA_STEM_CODE = "AMBIGUOUS_METADATA_STEM";
+var AMBIGUOUS_METADATA_STEM_STATUS = 500;
+var AMBIGUOUS_METADATA_STEM_BRAND = /* @__PURE__ */ Symbol.for("objectstack.metadata.ambiguousStem");
+var _a, _b;
+var AmbiguousMetadataStemError = class extends (_b = Error, _a = AMBIGUOUS_METADATA_STEM_BRAND, _b) {
+  constructor(type, stem, paths) {
+    const sorted = [...paths].sort();
+    super(
+      `Ambiguous metadata name \`${stem}\` for type \`${type}\`: ${sorted.length} files resolve to the same name \u2014 ${sorted.map((p) => `\`${p}\``).join(", ")}. Only the first would ever be served (extension precedence: .json, .yaml, .yml, .ts, .js), so the others are listed and unreachable. Delete or rename all but one.`
+    );
+    /** Brand — see the module doc on why this is not `instanceof`. */
+    this[_a] = true;
+    /** ADR-0112 wire code. */
+    this.code = AMBIGUOUS_METADATA_STEM_CODE;
+    /** HTTP status a transport should answer. */
+    this.status = AMBIGUOUS_METADATA_STEM_STATUS;
+    this.name = "AmbiguousMetadataStemError";
+    this.type = type;
+    this.stem = stem;
+    this.paths = sorted;
+  }
+};
+function isAmbiguousMetadataStemError(err) {
+  return typeof err === "object" && err !== null && err[AMBIGUOUS_METADATA_STEM_BRAND] === true;
+}
+
 // src/endpoint-matcher.ts
 var import_api = require("@objectstack/spec/api");
 
@@ -1725,6 +1726,36 @@ var EndpointMatcher = class {
   }
 };
 
+// src/view-container-expansion.ts
+var import_spec2 = require("@objectstack/spec");
+var import_shared2 = require("@objectstack/spec/shared");
+
+// src/view-container.ts
+function deriveViewContainerObject(container) {
+  if (!container || typeof container !== "object") return void 0;
+  const c = container;
+  const own = typeof c.object === "string" && c.object ? c.object : void 0;
+  const byName = typeof c.name === "string" && c.name ? c.name : void 0;
+  return own ?? c?.list?.data?.object ?? c?.form?.data?.object ?? byName;
+}
+
+// src/view-container-expansion.ts
+function expandRuntimeViewContainer(data) {
+  if (!(0, import_spec2.isAggregatedViewContainer)(data)) return [];
+  const container = data;
+  const viewObject = deriveViewContainerObject(container);
+  if (!viewObject) return [];
+  const out = [];
+  for (const vi of (0, import_spec2.expandViewContainer)(viewObject, container)) {
+    (0, import_shared2.applyProtection)(vi, {
+      packageId: container._packageId,
+      packageVersion: container._packageVersion
+    });
+    out.push(vi);
+  }
+  return out;
+}
+
 // src/metadata-manager.ts
 var WRITABLE_LOADER_METHODS = ["save", "delete"];
 var WRITABLE_LOADER_METHOD_SIGNATURE = {
@@ -1764,8 +1795,6 @@ var _MetadataManager = class _MetadataManager {
     this.watchCallbacks = /* @__PURE__ */ new Map();
     // In-memory metadata registry: type -> name -> data
     this.registry = /* @__PURE__ */ new Map();
-    // Overlay storage: "type:name:scope" -> MetadataOverlay
-    this.overlays = /* @__PURE__ */ new Map();
     // Type registry for metadata type info
     this.typeRegistry = [];
     // Dependency tracking: "type:name" -> dependencies
@@ -2340,6 +2369,67 @@ var _MetadataManager = class _MetadataManager {
    * result may be memoized depends on what happened to the read's registration
    * while it ran, which only `list()` can see.
    */
+  /**
+   * Merge one loader's answer for `type` into `items`, under the identity that
+   * loader holds each item by.
+   *
+   * ## [#14205] The identity of a loader-held item is its ROW KEY
+   *
+   * Both plural readers used to key a loader's items by `body.name`, and admit
+   * an item only when the body carried a string one:
+   *
+   * ```ts
+   * if (itemAny && typeof itemAny.name === 'string' && !items.has(itemAny.name))
+   * ```
+   *
+   * A body is not required to name itself. `register(type, name, data)` takes
+   * the key as its ARGUMENT, and `assertMetadataRegisterContract` says in as
+   * many words that "A document with NO `name` of its own is fine — the argument
+   * is the key". An aggregated `defineView` container is exactly that: no own
+   * `name` by design, identity carried in the row's `name` column.
+   *
+   * So the old gate dropped every such item the moment the registry went cold
+   * and only the loader could answer — a persisted view container vanished from
+   * `list('view')` after a restart, and `listDiagnosed()` called the short
+   * answer complete because no loader had thrown. Same gate, same effect, in
+   * `listForIndex()`: a nameless `api` row fell out of the endpoint index, where
+   * a miss reads as "nothing declares this route".
+   *
+   * The repair is to ask the loader for the key instead of guessing it from the
+   * body ({@link MetadataLoader.loadManyKeyed}), and to keep the key BESIDE the
+   * body: nothing is written into a body that deliberately has none, so the
+   * register contract's refusal of a disagreeing `data.name` still means what it
+   * says.
+   *
+   * Nothing consumers see today changes shape. For any item that went through
+   * `register()`, a `data.name` that exists is required to EQUAL the key, so the
+   * keyed merge produces the identical map entry; what is new is only the
+   * entries the old gate refused. The `loadMany()` fallback below is the
+   * pre-#14205 behaviour verbatim, for loaders that cannot produce keys
+   * (`RemoteLoader`'s wire format carries bodies only).
+   *
+   * Read failures are NOT caught here: `readListUncached` warns-and-continues,
+   * `listForIndex` deliberately throws, and that difference is each caller's to
+   * keep.
+   */
+  async admitLoaderItems(loader, type, items) {
+    if (typeof loader.loadManyKeyed === "function") {
+      const keyed = await loader.loadManyKeyed(type);
+      for (const entry of keyed) {
+        if (!entry || typeof entry.name !== "string" || entry.name === "") continue;
+        if (items.has(entry.name)) continue;
+        items.set(entry.name, entry.data);
+      }
+      return;
+    }
+    const loaderItems = await loader.loadMany(type);
+    for (const item of loaderItems) {
+      const itemAny = item;
+      if (itemAny && typeof itemAny.name === "string" && !items.has(itemAny.name)) {
+        items.set(itemAny.name, item);
+      }
+    }
+  }
   async readListUncached(type) {
     const items = /* @__PURE__ */ new Map();
     const typeStore = this.registry.get(type);
@@ -2352,15 +2442,12 @@ var _MetadataManager = class _MetadataManager {
     const errors = [];
     for (const loader of this.loaders.values()) {
       try {
-        const loaderItems = await loader.loadMany(type);
-        for (const item of loaderItems) {
-          const itemAny = item;
-          if (itemAny && typeof itemAny.name === "string" && !items.has(itemAny.name)) {
-            items.set(itemAny.name, item);
-          }
-        }
+        await this.admitLoaderItems(loader, type, items);
         this.reportLoaderReadRecovered(loader.contract.name);
       } catch (e) {
+        if (isAmbiguousMetadataStemError(e)) {
+          throw e;
+        }
         degraded = true;
         errors.push(`${loader.contract.name}: ${e instanceof Error ? e.message : String(e)}`);
         this.reportLoaderReadFailure(loader.contract.name, type, e);
@@ -2511,13 +2598,7 @@ var _MetadataManager = class _MetadataManager {
       }
     }
     for (const loader of this.loaders.values()) {
-      const loaderItems = await loader.loadMany(type);
-      for (const item of loaderItems) {
-        const itemAny = item;
-        if (itemAny && typeof itemAny.name === "string" && !items.has(itemAny.name)) {
-          items.set(itemAny.name, item);
-        }
-      }
+      await this.admitLoaderItems(loader, type, items);
     }
     return Array.from(items.values());
   }
@@ -2704,6 +2785,30 @@ var _MetadataManager = class _MetadataManager {
   }
   /**
    * List all names of metadata items of a given type
+   *
+   * ## [#14423] One loader's fault does not take the whole enumeration down
+   *
+   * This loop used to be bare — `const result = await loader.list(type)` with
+   * no `try`, while the two sibling plural reads (`list()` via
+   * {@link admitLoaderItems}, and {@link loadMany}) have carried a per-loader
+   * `catch` since #5108. That asymmetry is the defect, independent of any one
+   * caller: the SAME storage outage was swallowed by one plural read and
+   * thrown out of the other, so which answer a caller got depended only on
+   * which method it happened to call. A caller reading both — the action
+   * governance audit is one — saw `loadMany` report a short-but-successful
+   * set and `listNames` throw, and had no way to tell that one fact was
+   * behind both.
+   *
+   * Same shape as `loadMany`'s, deliberately, down to the helpers: the outage
+   * is spoken once per loader through {@link reportLoaderReadFailure} and
+   * un-said through {@link reportLoaderReadRecovered}. ⛔ Not a third spelling
+   * for "a loader faulted" — a second vocabulary for one event is how the two
+   * reads drifted apart in the first place.
+   *
+   * The degradation is the same one `list()` documents and is graded the same
+   * way (AGENTS.md → "Degradation log levels"): the caller still gets an
+   * array, nothing 500s, and the set is quietly short — so it is reported at
+   * `error`, by the shared helper, rather than being re-graded here.
    */
   async listNames(type) {
     type = (0, import_core.canonicalMetadataServiceType)(type);
@@ -2715,8 +2820,16 @@ var _MetadataManager = class _MetadataManager {
       }
     }
     for (const loader of this.loaders.values()) {
-      const result = await loader.list(type);
-      result.forEach((item) => names.add(item));
+      try {
+        const result = await loader.list(type);
+        result.forEach((item) => names.add(item));
+        this.reportLoaderReadRecovered(loader.contract.name);
+      } catch (e) {
+        if (isAmbiguousMetadataStemError(e)) {
+          throw e;
+        }
+        this.reportLoaderReadFailure(loader.contract.name, type, e);
+      }
     }
     return Array.from(names);
   }
@@ -2762,12 +2875,54 @@ var _MetadataManager = class _MetadataManager {
    * Runtime-authored `shared` / `personal` views (`sys_view_definition`) are
    * merged in by the REST layer; this method returns the `package` layer that
    * was registered from source.
+   *
+   * ## [#13913] Aggregated containers are expanded inline, per read
+   *
+   * `this.list('view')` is `MetadataManager`'s OWN loader-based store — the
+   * in-memory registry plus every registered loader — and is a completely
+   * different store from the `sys_metadata` rows `getMetaItems` reads. #13407
+   * taught `getMetaItems` to expand a runtime-authored aggregated container
+   * inline; this exit never called it and had no equivalent step, so a
+   * container that `GET /meta/view?object=` now serves still answered **empty**
+   * here.
+   *
+   * Merely getting the container into the store would not have helped: the
+   * filter also requires `viewKind`, and a container has none. Loosening that
+   * requirement is NOT the repair — it would answer with the container itself
+   * as a view, the behaviour #7163 ruled wrong — so what is added below is the
+   * container's **expansion**, whose items each carry the `viewKind` + `object`
+   * pair this filter has always tested. The filter itself is untouched: it
+   * reads the top-level `object`, exactly as `ViewSchema.object` declares.
+   *
+   * Registry-free and per-read, mirroring #13407's choice at the other exit and
+   * for the same reason — the registry is process-wide, so a read must not
+   * graft rows into it (see `view-container-expansion.ts`'s header, which also
+   * records why the protocol's copy of this logic cannot be imported).
+   *
+   * Already-present items win: an expansion contributes only names the store
+   * does not already hold, so a container whose expanded ViewItems were
+   * registered by a source registrar (the ObjectQL boot loop, the artifact/HMR
+   * loader) still answers with those registered, fully-enriched items and this
+   * step adds nothing.
    */
   async getViewsByObject(object) {
     const views = await this.list("view");
-    return views.filter(
+    const matches = views.filter(
       (v) => v && typeof v === "object" && v.viewKind && v.object === object
-    ).sort(
+    );
+    const known = /* @__PURE__ */ new Set();
+    for (const v of views) {
+      if (v && typeof v === "object" && typeof v.name === "string") known.add(v.name);
+    }
+    for (const v of views) {
+      for (const item of expandRuntimeViewContainer(v)) {
+        if (!item.viewKind || item.object !== object) continue;
+        if (known.has(item.name)) continue;
+        known.add(item.name);
+        matches.push(item);
+      }
+    }
+    return matches.sort(
       (a, b) => (a.order ?? 0) - (b.order ?? 0) || String(a.name).localeCompare(String(b.name))
     );
   }
@@ -3185,66 +3340,18 @@ var _MetadataManager = class _MetadataManager {
     };
   }
   // ==========================================
-  // Overlay / Customization Management
+  // Overlay / Customization Management — REMOVED (#13135, ADR-0049)
   // ==========================================
-  overlayKey(type, name, scope = "platform") {
-    return `${encodeURIComponent(type)}:${encodeURIComponent(name)}:${scope}`;
-  }
-  /**
-   * Get the active overlay for a metadata item
-   */
-  async getOverlay(type, name, scope) {
-    return this.overlays.get(this.overlayKey(type, name, scope ?? "platform"));
-  }
-  /**
-   * Save/update an overlay for a metadata item
-   */
-  async saveOverlay(overlay) {
-    if (this.config.persistence?.overlayWritable === false) {
-      const msg = `MetadataManager overlays are read-only (persistence.overlayWritable=false); refusing to save overlay for ${overlay.baseType}/${overlay.baseName}`;
-      if (this.config.validation?.throwOnError) {
-        throw new Error(msg);
-      }
-      this.logger.warn(msg);
-      return;
-    }
-    const key = this.overlayKey(overlay.baseType, overlay.baseName, overlay.scope);
-    this.overlays.set(key, overlay);
-  }
-  /**
-   * Remove an overlay, reverting to the base definition
-   */
-  async removeOverlay(type, name, scope) {
-    this.overlays.delete(this.overlayKey(type, name, scope ?? "platform"));
-  }
-  /**
-   * Get the effective (merged) metadata after applying all overlays.
-   * Resolution order: system ← merge(platform) ← merge(user)
-   */
-  async getEffective(type, name, context) {
-    const base = await this.get(type, name);
-    if (!base) return void 0;
-    let effective = { ...base };
-    const platformOverlay = await this.getOverlay(type, name, "platform");
-    if (platformOverlay?.active && platformOverlay.patch) {
-      effective = { ...effective, ...platformOverlay.patch };
-    }
-    if (context?.userId) {
-      const userOverlayKey = this.overlayKey(type, name, "user") + `:${context.userId}`;
-      const userOverlay = this.overlays.get(userOverlayKey) ?? await this.getOverlay(type, name, "user");
-      if (userOverlay?.active && userOverlay.patch) {
-        if (!userOverlay.owner || userOverlay.owner === context.userId) {
-          effective = { ...effective, ...userOverlay.patch };
-        }
-      }
-    } else {
-      const userOverlay = await this.getOverlay(type, name, "user");
-      if (userOverlay?.active && userOverlay.patch && !userOverlay.owner) {
-        effective = { ...effective, ...userOverlay.patch };
-      }
-    }
-    return effective;
-  }
+  //
+  // The in-memory overlay limb (`getOverlay` / `saveOverlay` / `removeOverlay`
+  // / `getEffective`, keyed `type:name:scope`) implemented the paper
+  // metadata-customization protocol removed from `@objectstack/spec` in the
+  // same change: no route ever served the paper `.../overlay` or
+  // `.../effective` endpoints, and the only callers of these methods were this
+  // package's own unit tests. ADR-0126 supersedes the protocol on the record.
+  // The org-scoped customization that actually ships is ADR-0005's
+  // `sys_metadata` overlay (`getMetaItemLayered` in metadata-protocol), which
+  // never lived here.
   // ==========================================
   // Watch / Subscribe (IMetadataService)
   // ==========================================
@@ -3582,6 +3689,99 @@ var _MetadataManager = class _MetadataManager {
     }
     return results;
   }
+  /**
+   * [#14423] {@link loadMany}, read under the identity the STORE holds each
+   * item by — the keyed plural read, beside the unkeyed one.
+   *
+   * ## Why a second method and not a widened `loadMany`
+   *
+   * `loadMany` keys nothing: it returns bodies, and every consumer that needs
+   * an identity reads `body.name` off them. #14205 already ruled what identity
+   * IS — the key the store holds the item under (`register(type, name, data)`
+   * takes it as the ARGUMENT, and a body is not required to name itself) — so
+   * `body.name` is a guess that happens to be right for most items and drops
+   * the rest ENTIRELY: an item whose body carries no `name` is served by
+   * `load(type, name)` and is not nameable from `loadMany`'s answer at all.
+   *
+   * Widening `loadMany`'s return would fix that and break every consumer of a
+   * published shape (the ones counted on this card all read `body.name` as the
+   * identity). So this is additive: `loadMany`'s return shape is untouched,
+   * and a caller that needs the key asks for the key.
+   *
+   * ## What it reads — the same population `loadMany` reads
+   *
+   * Loaders only, deliberately, so this is `loadMany` keyed and nothing more.
+   * It is NOT `list()`/{@link listNames}, which also merge the in-memory
+   * `register()` registry; a caller wanting that set has those. Reading the
+   * loaders alone is also what makes this the enumerable twin of
+   * {@link loadDiagnosed}, which walks the same loaders by name — that pairing
+   * is the point on the audit side of #14423, where an enumeration and a
+   * by-name read that disagree about a population make one subsystem accuse
+   * another of a defect neither has.
+   *
+   * ## Delegate first, fall back second — and why that order is not a style
+   *
+   * Per loader: {@link MetadataLoader.loadManyKeyed} where the loader offers
+   * one, else its `list()` + a per-name `load()`. Measured, on
+   * `DatabaseLoader`: the keyed method shares `loadMany`'s single query
+   * (`{find:1, findOne:0}` — zero extra cost), while enumerate-then-read-each
+   * on that same loader is a real N+1 (`{find:1, findOne:5}` for five items).
+   * The fallback exists for loaders that cannot produce keys at all
+   * (`RemoteLoader`'s wire format carries bodies only), and it recovers the
+   * nameless item the pre-#14205 `loadMany`-and-key-by-`body.name` fallback
+   * drops — which is why it is `list()` + `load()` and not `loadMany()`.
+   *
+   * ## Failure posture
+   *
+   * Per-loader `try`/`catch`, the same seam and the same helpers as
+   * {@link loadMany} and `list()` — one loader's outage does not take the
+   * enumeration down, and it is reported once through
+   * {@link reportLoaderReadFailure} rather than in a third vocabulary.
+   * Earlier loaders win a key collision, mirroring `list()`.
+   */
+  async loadManyKeyed(type, options) {
+    const items = /* @__PURE__ */ new Map();
+    for (const loader of this.loaders.values()) {
+      try {
+        await this.admitKeyedLoaderItems(loader, type, items, options);
+        this.reportLoaderReadRecovered(loader.contract.name);
+      } catch (e) {
+        this.reportLoaderReadFailure(loader.contract.name, type, e);
+      }
+    }
+    return Array.from(items, ([name, data]) => ({ name, data }));
+  }
+  /**
+   * Merge ONE loader's answer for `type` into `items`, keyed by that loader's
+   * own key for each item — {@link loadManyKeyed}'s per-loader body.
+   *
+   * Distinct from {@link admitLoaderItems} on exactly one axis, and that axis
+   * is the whole of #14423: the fallback for a loader with no
+   * `loadManyKeyed`. `admitLoaderItems` falls back to `loadMany` keyed by
+   * `data.name` — the pre-#14205 behaviour, verbatim, which drops a nameless
+   * body. Here the fallback is `list()` + a per-name `load()`, so a loader
+   * that cannot enumerate keys and bodies together still answers with both.
+   *
+   * Read failures are NOT caught here — the caller owns that verdict, as in
+   * {@link admitLoaderItems}.
+   */
+  async admitKeyedLoaderItems(loader, type, items, options) {
+    if (typeof loader.loadManyKeyed === "function") {
+      const keyed = await loader.loadManyKeyed(type, options);
+      for (const entry of keyed) {
+        if (!entry || typeof entry.name !== "string" || entry.name === "") continue;
+        if (items.has(entry.name)) continue;
+        items.set(entry.name, entry.data);
+      }
+      return;
+    }
+    for (const name of await loader.list(type)) {
+      if (typeof name !== "string" || name === "" || items.has(name)) continue;
+      const result = await loader.load(type, name, options);
+      if (result?.data == null) continue;
+      items.set(name, result.data);
+    }
+  }
   /**
    * Save metadata item to a loader
    */
@@ -4018,6 +4218,7 @@ var MetadataManager = _MetadataManager;
 // src/plugin.ts
 var import_promises = require("fs/promises");
 var import_node_crypto2 = require("crypto");
+var import_core2 = require("@objectstack/core");
 
 // src/node-metadata-manager.ts
 var path2 = __toESM(require("path"), 1);
@@ -4028,7 +4229,11 @@ var fs = __toESM(require("fs/promises"), 1);
 var path = __toESM(require("path"), 1);
 var import_glob = require("glob");
 var import_node_crypto = require("crypto");
-var FilesystemLoader = class {
+function ownNameOf(data) {
+  const own = data?.name;
+  return typeof own === "string" && own !== "" ? own : null;
+}
+var _FilesystemLoader = class _FilesystemLoader {
   constructor(rootDir, serializers, logger) {
     this.rootDir = rootDir;
     this.serializers = serializers;
@@ -4126,6 +4331,82 @@ var FilesystemLoader = class {
     }
   }
   async loadMany(type, options) {
+    return (await this.loadManyEntries(type, options)).map((entry) => entry.data);
+  }
+  /**
+   * [#14341] The keyed half of {@link loadMany} — see {@link MetadataKeyedItem}
+   * for why the store's key travels BESIDE the body instead of being folded
+   * into it.
+   *
+   * THE RULE, in one sentence: an item is keyed by this loader's own
+   * name-to-path derivation — {@link nameFromFilename}, the very basename
+   * derivation `list()` reports — ONLY where that derivation is a bijection for
+   * the file (it sits directly under `ROOT/TYPE/` and carries one of the
+   * extensions {@link findFile} tries, so `findFile(type, key)` resolves back to
+   * this same file); every other shape keeps the pre-#14205 behaviour verbatim,
+   * keyed by `body.name` when it has one and dropped when it has none.
+   *
+   * Why the rule stops there (PM ruling on #14341, 2026-09-02, knowingly over
+   * triage's "a nested path keeps whatever `list()` reports for it today"):
+   * `list()` and `findFile()` DISAGREE outside that shape. For
+   * `ROOT/TYPE/crm/account.json`, `list()` reports the bare `account`, but
+   * `findFile()` resolves that name against `ROOT/TYPE/account.json` and finds
+   * nothing — the only name reaching the file is `crm/account`, which nothing
+   * reports. An extension-less file is read by `loadMany()` and reported by
+   * `list()`, and `findFile()` resolves neither. Keying by either side would
+   * mint a name some other door cannot open, and two directories holding the
+   * same basename would collide in silence
+   * (`MetadataManager.admitLoaderItems()` keeps the first and says nothing).
+   * The card's own fence: "keying items under names nothing else uses … is
+   * worse than today's honest drop". So the drop stays exactly where the key is
+   * unsettled, and is pinned as a RECORD in
+   * `filesystem-loader-keyed-items.test.ts`.
+   *
+   * [#14486, partial] `list()` and {@link findFile} have since converged on
+   * {@link resolvableNameForPath} — the derivation this method already used —
+   * so a nested or extension-less file is now neither listed nor resolvable.
+   * What did NOT change is the WALK behind this method: `loadManyEntries()`
+   * still READS those files, so `loadMany()` still returns their bodies and
+   * this method still falls back to `body.name` for them. That half of the
+   * #14486 ruling ("nothing unlisted is returned by `loadMany()` either") is
+   * deliberately NOT taken here: it would invert the three landed #14341 pins
+   * in `filesystem-loader-keyed-items.test.ts:113,167,187` and the
+   * `loadMany()` CONTROL at `:196`, and that file was under a concurrent
+   * claim (PR #14627) when this landed. The remaining divergence — listed ⊂
+   * loaded — is pinned as a RECORD in
+   * `filesystem-loader-list-reachability.test.ts` rather than left implicit.
+   *
+   * One consequence, deliberate: a flat file whose `body.name` DISAGREES with
+   * its basename is now keyed by the BASENAME. That is #14205's rule (identity
+   * is the key the store holds an item under, not `body.name`) applied to this
+   * loader, and it aligns `MetadataManager.list()` with `listNames()` for that
+   * shape.
+   *
+   * The body is handed back by reference, unchanged: nothing is written into a
+   * body that deliberately has no `name`. `limit` bounds the items LOADED,
+   * exactly as `loadMany()` does — an entry the key rule drops has still been
+   * read and still counts against it.
+   */
+  async loadManyKeyed(type, options) {
+    const typeDir = path.join(this.rootDir, type);
+    const keyed = [];
+    for (const entry of await this.loadManyEntries(type, options)) {
+      const name = this.resolvableNameForPath(typeDir, entry.file) ?? ownNameOf(entry.data);
+      if (name) {
+        keyed.push({ name, data: entry.data });
+      }
+    }
+    return keyed;
+  }
+  /**
+   * The single walk behind {@link loadMany} and {@link loadManyKeyed}: one glob,
+   * one serializer pass, one `limit`. Shared so the two can never answer with
+   * different bodies for the same file — {@link MetadataLoader.loadManyKeyed}
+   * requires `data` to be "the same body `loadMany()` would return for the
+   * item", and a second copy of this walk is how that would quietly stop being
+   * true.
+   */
+  async loadManyEntries(type, options) {
     const { patterns = ["**/*"], recursive: _recursive = true, limit } = options || {};
     const typeDir = path.join(this.rootDir, type);
     const items = [];
@@ -4133,33 +4414,34 @@ var FilesystemLoader = class {
       const globPatterns = patterns.map(
         (pattern) => path.join(typeDir, pattern)
       );
+      const files = [];
       for (const pattern of globPatterns) {
-        const files = await (0, import_glob.glob)(pattern, {
-          ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*", "**/*[*]*"],
-          nodir: true
-        });
-        for (const file of files) {
-          if (limit && items.length >= limit) {
-            break;
-          }
-          try {
-            const content = await fs.readFile(file, "utf-8");
-            const format = this.detectFormat(file);
-            const serializer = this.getSerializer(format);
-            if (serializer) {
-              const data = serializer.deserialize(content);
-              items.push(data);
-            }
-          } catch (error) {
-            this.logger?.warn("Failed to load file", {
-              file,
-              error: error instanceof Error ? error.message : String(error)
-            });
-          }
-        }
+        files.push(
+          ...await (0, import_glob.glob)(pattern, {
+            ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*", "**/*[*]*"],
+            nodir: true
+          })
+        );
+      }
+      this.resolvableNames(type, typeDir, files);
+      for (const file of files) {
         if (limit && items.length >= limit) {
           break;
         }
+        try {
+          const content = await fs.readFile(file, "utf-8");
+          const format = this.detectFormat(file);
+          const serializer = this.getSerializer(format);
+          if (serializer) {
+            const data = serializer.deserialize(content);
+            items.push({ file, data });
+          }
+        } catch (error) {
+          this.logger?.warn("Failed to load file", {
+            file,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
       }
       return items;
     } catch (error) {
@@ -4202,19 +4484,39 @@ var FilesystemLoader = class {
       return null;
     }
   }
+  /**
+   * [#14486] The names this loader can be asked for, and ONLY those: a file
+   * directly under `ROOT/TYPE/` carrying an extension one of this instance's
+   * REGISTERED serializers claims. Every name it reports resolves back through
+   * {@link findFile}, so `listNames()` and `get()` give the same answer.
+   *
+   * It used to report `path.basename(file, ext)` for every file the glob found,
+   * nested or not, extension or not — and {@link findFile} resolves neither
+   * shape. `ROOT/TYPE/crm/account.json` was listed as `account`, which resolves
+   * against `ROOT/TYPE/account.json` and finds nothing; an extension-less
+   * `ROOT/TYPE/noext` was listed as `noext`, which resolves under no appended
+   * extension at all. A name in the list that `get()` answers `null` for is the
+   * silent failure an author (human or AI) reads as their own typo, so they
+   * retry the same word: the list and the door now agree instead.
+   *
+   * Ruling (maintainer, via the director seat on #14486, 2026-09-02): narrow
+   * the list — direction A, over B (reverse-unify: report `crm/account` and
+   * teach `findFile()` path-shaped names), which would have made a slash inside
+   * a metadata name every consumer's permanent obligation with no measured
+   * demand for it. The two-segment layout follows ADR-0008 §10, which
+   * `metadata-fs`'s `parseItemPath()` already enforces for its own store; the
+   * EXTENSION set deliberately does NOT follow §10's `.json`-only rule — see
+   * {@link resolvableExtensions} for why.
+   */
   async list(type) {
     const typeDir = path.join(this.rootDir, type);
+    let files;
     try {
-      const files = await (0, import_glob.glob)("**/*", {
+      files = await (0, import_glob.glob)("**/*", {
         cwd: typeDir,
         ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*"],
         nodir: true
       });
-      return files.map((file) => {
-        const ext = path.extname(file);
-        const basename3 = path.basename(file, ext);
-        return basename3;
-      });
     } catch (error) {
       this.logger?.error("Failed to list", void 0, {
         type,
@@ -4222,6 +4524,7 @@ var FilesystemLoader = class {
       });
       return [];
     }
+    return this.resolvableNames(type, typeDir, files.map((file) => path.join(typeDir, file)));
   }
   async save(type, name, data, options) {
     const startTime = Date.now();
@@ -4292,12 +4595,109 @@ var FilesystemLoader = class {
       throw error;
     }
   }
+  /**
+   * [#14486] The extensions a name can be resolved under, for THIS instance:
+   * the ones belonging to the serializer set it was constructed with. Shared by
+   * {@link findFile}, {@link resolvableNameForPath} and therefore {@link list},
+   * so the set a name can be RESOLVED under cannot drift from the set that is
+   * LISTED or the set {@link loadManyKeyed} is willing to KEY by.
+   *
+   * Registered, not hard-coded, and deliberately not ADR-0008 §10's `.json`
+   * only. §10 governs the `metadata-fs` store; applying it verbatim here would
+   * drop `.yaml` and `.ts` metadata out of `listNames()` — a breakage this card
+   * never asked for. Under the manager's DEFAULT format set
+   * (`typescript` / `json` / `yaml`, `metadata-manager.ts`) that leaves `.js`
+   * out, which is the card's row-4 membership mismatch closing for free: a `.js`
+   * file was listed and resolvable while `loadMany()` could never return it and
+   * `load()` threw `No serializer found for format: javascript`. Register
+   * `javascript` and it is listed, resolvable and loadable together.
+   */
+  resolvableExtensions() {
+    const extensions = [];
+    for (const [format, formatExtensions] of _FilesystemLoader.EXTENSIONS_BY_FORMAT) {
+      if (this.serializers.has(format)) {
+        extensions.push(...formatExtensions);
+      }
+    }
+    return extensions;
+  }
+  /**
+   * The metadata name this loader reports for a file: the basename with its
+   * extension stripped. One derivation, shared by {@link list} and
+   * {@link loadManyKeyed}, so the two cannot drift for the shape where they
+   * agree — `dotted.config.json` is `dotted.config` for both.
+   */
+  static nameFromFilename(file) {
+    return path.basename(file, path.extname(file));
+  }
+  /**
+   * The key for a file IF this loader's name-to-path mapping is a bijection for
+   * it: a file directly under `ROOT/TYPE/` carrying an extension
+   * {@link findFile} tries, so `findFile(type, key)` resolves back to this very
+   * file. `null` for every other shape — a nested path, an extension-less file,
+   * an extension spelled in a case `findFile()` does not compose — which is why
+   * {@link loadManyKeyed} falls back to `body.name` there rather than minting a
+   * key no other door can open.
+   */
+  resolvableNameForPath(typeDir, file) {
+    const rel = path.relative(typeDir, file);
+    if (rel === "" || rel.split(path.sep).length !== 1) {
+      return null;
+    }
+    if (!this.resolvableExtensions().includes(path.extname(rel))) {
+      return null;
+    }
+    return _FilesystemLoader.nameFromFilename(rel);
+  }
+  /**
+   * [#14921] The names this loader reports for `files` — and the ONE place an
+   * ambiguous stem is refused.
+   *
+   * Shared by {@link list} and {@link loadManyEntries} so the two can never
+   * disagree about which trees are admissible: a stem that `list()` refuses
+   * must not still be walked and returned as two bodies by `loadMany()`, which
+   * is exactly the split this card measured.
+   *
+   * Refuses on the FIRST colliding name in sorted order, so a tree holding more
+   * than one collision always names the same one — a refusal that moves
+   * between runs reads as flakiness rather than as the fixed authoring error it
+   * is. Paths are deduplicated because two overlapping `patterns` legitimately
+   * match one file twice, and counting that as a collision would refuse a
+   * perfectly good tree.
+   *
+   * ⛔ Not a precedence resolver. Picking a winner here is what the ruling
+   * declined (option 2, keep the precedence and log): the loser would stay
+   * unreachable and the listed set would stay different from the addressable
+   * one.
+   */
+  resolvableNames(type, typeDir, files) {
+    const byName = /* @__PURE__ */ new Map();
+    for (const file of files) {
+      const name = this.resolvableNameForPath(typeDir, file);
+      if (name === null) {
+        continue;
+      }
+      let paths = byName.get(name);
+      if (!paths) {
+        paths = /* @__PURE__ */ new Set();
+        byName.set(name, paths);
+      }
+      paths.add(file);
+    }
+    for (const name of [...byName.keys()].sort()) {
+      const paths = byName.get(name);
+      if (paths.size > 1) {
+        throw new AmbiguousMetadataStemError(type, name, [...paths]);
+      }
+    }
+    return [...byName.keys()];
+  }
   /**
    * Find file for a given type and name
    */
   async findFile(type, name) {
     const typeDir = path.join(this.rootDir, type);
-    const extensions = [".json", ".yaml", ".yml", ".ts", ".js"];
+    const extensions = this.resolvableExtensions();
     for (const ext of extensions) {
       const filePath = path.join(typeDir, `${name}${ext}`);
       try {
@@ -4343,6 +4743,19 @@ var FilesystemLoader = class {
     return `"${hash}"`;
   }
 };
+/**
+ * The inverse of {@link detectFormat}: which file extensions carry which
+ * format. Fixed ORDER, because it is also {@link findFile}'s precedence when
+ * two files under one type directory share a stem — registration order must
+ * not be able to change which file `ROOT/TYPE/NAME` opens.
+ */
+_FilesystemLoader.EXTENSIONS_BY_FORMAT = [
+  ["json", [".json"]],
+  ["yaml", [".yaml", ".yml"]],
+  ["typescript", [".ts"]],
+  ["javascript", [".js"]]
+];
+var FilesystemLoader = _FilesystemLoader;
 
 // src/node-metadata-manager.ts
 var NodeMetadataManager = class extends MetadataManager {
@@ -4467,6 +4880,20 @@ var MemoryLoader = class {
     if (!typeStore) return [];
     return Array.from(typeStore.values());
   }
+  /**
+   * [#14205] The keyed half of {@link loadMany}. The storage map is already
+   * `Type -> Name -> Data`, so the key this loader holds an item under is the
+   * map key — `loadMany()` was simply discarding it, which dropped every
+   * nameless body out of `MetadataManager.list()` and out of the endpoint index.
+   *
+   * The body is handed back by reference, unchanged: the key travels beside it,
+   * never folded into it.
+   */
+  async loadManyKeyed(type, _options) {
+    const typeStore = this.storage.get(type);
+    if (!typeStore) return [];
+    return Array.from(typeStore, ([name, data]) => ({ name, data }));
+  }
   async exists(type, name) {
     return this.storage.get(type)?.has(name) ?? false;
   }
@@ -4513,20 +4940,20 @@ var MemoryLoader = class {
 
 // src/plugin.ts
 var import_kernel2 = require("@objectstack/spec/kernel");
-var import_shared2 = require("@objectstack/spec/shared");
-var import_metadata_core2 = require("@objectstack/metadata-core");
-var import_spec2 = require("@objectstack/spec");
+var import_shared3 = require("@objectstack/spec/shared");
+var import_metadata_core3 = require("@objectstack/metadata-core");
 var import_spec3 = require("@objectstack/spec");
+var import_spec4 = require("@objectstack/spec");
 var queryableMetadataObjects = [
-  import_metadata_core2.SysMetadataObject,
-  import_metadata_core2.SysMetadataHistoryObject,
+  import_metadata_core3.SysMetadataObject,
+  import_metadata_core3.SysMetadataHistoryObject,
   // ADR-0067 commit log — sibling of sys_metadata_history (see note above).
-  import_metadata_core2.SysMetadataCommitObject,
-  import_metadata_core2.SysMetadataAuditObject,
+  import_metadata_core3.SysMetadataCommitObject,
+  import_metadata_core3.SysMetadataAuditObject,
   // Runtime view storage (shared / personal). Must always be provisioned so
   // end-user view creation via the generic data API has a place to write —
   // mirroring why sys_metadata is always provisioned for PUT /meta.
-  import_metadata_core2.SysViewDefinitionObject
+  import_metadata_core3.SysViewDefinitionObject
 ];
 var REPO_SUBDIR = ".objectstack/metadata";
 var ARTIFACT_FIELD_TO_TYPE = {
@@ -4549,8 +4976,37 @@ var ARTIFACT_FIELD_TO_TYPE = {
   // positions from artifact ingestion.
   positions: "position",
   permissions: "permission",
+  // [ADR-0066 D1] `capabilities` reaches the door at #12892 step 1, the
+  // maintainer's `option 1` ruling ("the door owns the registration
+  // route" for the five artifact security collections). Until #12894
+  // measured it, `AppPlugin`'s `SECURITY_FIELDS` block
+  // (packages/runtime/src/app-plugin.ts) was this collection's SOLE
+  // registrar on an artifact boot — the one security collection the door
+  // could not reach — so a declared capability was registered from bytes
+  // nothing strict-parses, with no schema default and no ADR-0010
+  // provenance. Measured on the two-reader harness, the door's copy adds
+  // exactly four keys the raw copy lacks: `scope` (the schema default)
+  // and `_packageId` / `_packageVersion` / `_provenance`.
+  //
+  // ⚠️ This entry makes the door a SECOND writer, not yet the only one:
+  // `AppPlugin` still registers `capabilities`, and it runs last, so the
+  // raw copy still wins a real artifact boot. Step 2 of the ruling (that
+  // block stops registering these five on the artifact path, after a
+  // census of the non-artifact boot paths) is what makes this the only
+  // copy. Until then the divergence is the interim reality the ruling
+  // explicitly permits, and #12878's pins are what keep it visible.
+  capabilities: "capability",
   sharingRules: "sharing_rule",
-  policies: "policy",
+  // `policies: 'policy'` removed at #12894: the stack schema is a
+  // `strictObject` that declares no top-level `policies` key, so a
+  // definition carrying one is refused by the strict parse a few lines
+  // below — the entry could never match, and nothing was ever registered
+  // under `policy` from this map. The word is real, but it lives ONE LEVEL
+  // DOWN: on a permission set it is an alias for `rowLevelSecurity`
+  // (`PERMISSION_SET_KEY_ALIASES`, packages/spec/src/security/permission.zod.ts)
+  // — a key on an ITEM, never a collection. Third retirement of this exact
+  // shape in this map (`themes` and `roles` above); the reasons are kept
+  // in place because the first two are what made this one findable.
   apis: "api",
   webhooks: "webhook",
   agents: "agent",
@@ -4593,6 +5049,21 @@ var MetadataPlugin = class {
      * degrades on purpose (objects are discovered via the legacy fallback).
      */
     this.optionalDependencies = ["com.objectstack.engine.objectql"];
+    /**
+     * Once-per-process dedupe for the summaries the versioned artifact window
+     * emits. The artifact watcher replays `_parseAndRegisterArtifact` on every
+     * file change, so without this a dev loop over a legacy artifact would
+     * re-announce the same finding on every reload — the same shape
+     * `Protocol.storedConversionWarned` guards on the stored-row pass, which
+     * this surfacing is modeled on.
+     *
+     * Two key families share the set, because they share the replay:
+     * `<conversionId>|<label>` for a forward-conversion summary (#12772), and
+     * `unbound-form-predicate-root|<label>` for the unbound-root notice
+     * (#12915) — one line per artifact there, not one per conversion, since
+     * the notice already aggregates every finding it made.
+     */
+    this.artifactConversionWarned = /* @__PURE__ */ new Set();
     this.init = async (ctx) => {
       this.initCtx = ctx;
       ctx.logger.info("Initializing Metadata Manager", {
@@ -4601,7 +5072,6 @@ var MetadataPlugin = class {
         artifactSource: this.options.artifactSource?.mode
       });
       ctx.registerService("metadata", this.manager);
-      console.log("[MetadataPlugin] Registered metadata service, has getRegisteredTypes:", typeof this.manager.getRegisteredTypes);
       const registerSysObjects = this.options.registerSystemObjects !== false;
       if (registerSysObjects) {
         try {
@@ -4623,7 +5093,7 @@ var MetadataPlugin = class {
       }
       ctx.logger.info("MetadataPlugin providing metadata service (primary mode)", {
         mode: this.options.artifactSource?.mode ?? "file-system",
-        features: ["watch", "multi-format", "query", "overlay", "type-registry"]
+        features: ["watch", "multi-format", "query", "type-registry"]
       });
     };
     this.start = async (ctx) => {
@@ -4706,7 +5176,7 @@ var MetadataPlugin = class {
         if (httpServer && typeof httpServer.getRawApp === "function") {
           const { registerMetadataHmrRoutes: registerMetadataHmrRoutes2 } = await Promise.resolve().then(() => (init_hmr_routes(), hmr_routes_exports));
           const hub = registerMetadataHmrRoutes2(httpServer.getRawApp(), this.manager);
-          hub.setOnPostReload(async (body = {}) => {
+          hub?.setOnPostReload(async (body = {}) => {
             const src3 = this.options.artifactSource;
             if (src3?.mode === "local-file") {
               try {
@@ -4746,7 +5216,7 @@ var MetadataPlugin = class {
                 pending = true;
                 try {
                   await this._reloadAndAnnounce(ctx, src2, [src2.path]);
-                  hub.broadcastReload("artifact-file-changed", [src2.path]);
+                  hub?.broadcastReload("artifact-file-changed", [src2.path]);
                   ctx.logger.info("[MetadataPlugin] artifact auto-reloaded (file watcher)", {
                     path: src2.path
                   });
@@ -4768,7 +5238,13 @@ var MetadataPlugin = class {
               ctx.logger.warn("[MetadataPlugin] artifact watcher failed to start", { error: e?.message });
             }
           }
-          console.log("[MetadataPlugin] HMR endpoint registered at /api/v1/dev/metadata-events");
+          if (hub) {
+            console.log("[MetadataPlugin] HMR endpoint registered at /api/v1/dev/metadata-events");
+          } else {
+            console.log(
+              `[MetadataPlugin] dev metadata-HMR endpoints NOT mounted \u2014 they require NODE_ENV=development (this process: ${process.env.NODE_ENV ? `NODE_ENV=${process.env.NODE_ENV}` : "NODE_ENV unset, treated as production"})`
+            );
+          }
         } else {
           console.log("[MetadataPlugin] HTTP server with getRawApp() not available \u2014 skipping HMR endpoint");
         }
@@ -4864,6 +5340,106 @@ var MetadataPlugin = class {
       if (timer) clearTimeout(timer);
     }
   }
+  /**
+   * Versioned ADR-0087 forward conversion at the artifact-ingestion door
+   * (#12772) — runs BEFORE the strict schema parse below, because the parse
+   * is the refusal point.
+   *
+   * A compiled artifact is data at rest with a version stamp: built by
+   * released tooling, then unchanged while the platform moves on. When a
+   * spec release retires an authorable key inside a protocol line (spec
+   * 17.1 → 17.2 retired the `allowRestore`/`allowPurge` permission bits),
+   * every already-built artifact carrying the key becomes unbootable at the
+   * tombstone — with no operator remedy, since `os migrate meta` targets
+   * sources, not built artifacts. The stored-row read path already replays
+   * the conversion chain for exactly this reason
+   * (`applyConversionsToStoredItem`, ADR-0087 addendum); this is the same
+   * policy at the artifact door, **keyed off the artifact's own declared
+   * `engines.protocol` floor**: an artifact authored below the running spec
+   * version converts forward, an artifact authored at the current (or a
+   * newer) surface converts nothing and answers to the strict parse,
+   * tombstones included. The version key is what keeps this a conversion
+   * rather than an amnesty — the retired keys return with the M2 lifecycle
+   * batch (#1883), and artifacts authored against that surface must never
+   * have them stripped by history.
+   *
+   * Notices surface the way the stored-row pass's do — operator-visible and
+   * deduped — as one summary line per conversion per artifact rather than
+   * one per rewritten path (a real 17.1 artifact carried 150 strips of the
+   * same two keys; 150 identical warn lines would bury the boot log).
+   */
+  _convertArtifactForward(ctx, definition, label) {
+    const result = (0, import_metadata_core3.applyArtifactForwardConversions)(definition);
+    this._warnUnboundFormPredicateRoots(ctx, result, label);
+    if (result.notices.length === 0) return result.definition;
+    const byConversion = /* @__PURE__ */ new Map();
+    for (const n of result.notices) {
+      const existing = byConversion.get(n.conversionId);
+      if (existing) existing.count += 1;
+      else byConversion.set(n.conversionId, { count: 1, firstPath: n.path, message: n.message });
+    }
+    for (const [conversionId, agg] of byConversion) {
+      const key = `${conversionId}|${label}`;
+      if (this.artifactConversionWarned.has(key)) continue;
+      this.artifactConversionWarned.add(key);
+      ctx.logger.warn(
+        `[MetadataPlugin] artifact '${label}' predates this runtime's spec (authored engines.protocol floor ${result.authoredFloor ?? "<undeclared>"}, runtime spec ${result.runtimeSpecVersion}) \u2014 converted ${agg.count} site(s) forward via ADR-0087 conversion '${conversionId}' (first at ${agg.firstPath}). ${agg.message} The artifact file itself is unchanged \u2014 rebuild it with current tooling ('os build') to persist the canonical shape.`
+      );
+    }
+    return result.definition;
+  }
+  /**
+   * Operator-facing boot notice for form-view predicates that fault OPEN on
+   * this runtime (#12915 scope C — maintainer ruling 2026-08-28, 「同意C」).
+   *
+   * A form-view predicate binds `record` / `previous` / `parent` (runtime
+   * record forms) or `data` (metadata-editing forms) — and a FIELD-level one
+   * also binds `current_user` and its ADR-0068 aliases (objectui#6010),
+   * which a SECTION-level one does not. The contract states beside that
+   * vocabulary that a bare identifier is UNBOUND and the predicate faults,
+   * and `visibleWhen`'s fault fallback is `true`. On a real
+   * 17.1-built artifact that combination dead-ends record creation in the
+   * console: the conditionally hidden field renders, and its unconditional
+   * `required: true` — authored to be gated by the visibility that no longer
+   * applies — blocks every submit, while the same payload POSTs 201 through
+   * REST. Nothing refused, nothing logged, and only the operator can fix it
+   * (by rebuilding the artifact), so this is the channel the ruling picked:
+   * service startup, server-side, never a console surface — the person at
+   * the form cannot act on "your artifact is stale".
+   *
+   * **Detection only.** No refusal, no rewrite, no behaviour change: the
+   * predicate keeps faulting open exactly as before. Rewriting a bare root to
+   * `record.` is the ADR-0087 conversion (#12915 scope A), deferred by the
+   * same ruling with an explicit start line.
+   *
+   * **Same versioned window as the conversion replay above** — and read off
+   * that pass's own verdict rather than recomputed, so the two can never
+   * disagree about which artifacts are "old". An artifact declaring the
+   * current (or a newer) floor answers to the strict parse and gets nothing
+   * from here even when it does carry bare roots; that boundary is what keeps
+   * a notice about legacy artifacts out of contract territory. An undeclared
+   * range is treated as old data at rest, matching the grandfathering posture
+   * the window already takes (`converted-undeclared`).
+   */
+  _warnUnboundFormPredicateRoots(ctx, result, label) {
+    if (result.verdict !== "converted-forward" && result.verdict !== "converted-undeclared") return;
+    const findings = (0, import_metadata_core3.detectUnboundFormViewPredicateRoots)(result.definition);
+    if (findings.length === 0) return;
+    const key = `unbound-form-predicate-root|${label}`;
+    if (this.artifactConversionWarned.has(key)) return;
+    this.artifactConversionWarned.add(key);
+    const views = [...new Set(findings.map((f) => f.view))];
+    const roots = [...new Set(findings.map((f) => f.root))];
+    const quote = (list) => list.map((v) => `'${v}'`).join(", ");
+    const surfaces = new Set(findings.map((f) => f.surface));
+    const vocabulary = [
+      surfaces.has("field") ? `on a form FIELD: ${quote(import_metadata_core3.BOUND_FORM_FIELD_PREDICATE_ROOTS)}` : null,
+      surfaces.has("section") ? `on a form SECTION: ${quote(import_metadata_core3.BOUND_FORM_VIEW_PREDICATE_ROOTS)}` : null
+    ].filter(Boolean).join("; ");
+    ctx.logger.warn(
+      `[MetadataPlugin] artifact '${label}' predates this runtime's spec (authored engines.protocol floor ${result.authoredFloor ?? "<undeclared>"}, runtime spec ${result.runtimeSpecVersion}) and carries ${findings.length} form-view predicate(s) whose root identifier is NOT bound where it evaluates \u2014 ${quote(roots)} (bound roots ${vocabulary}) \u2014 across ${views.length} view(s): ${views.join(", ")} (first at ${findings[0].path}). Each one faults at evaluation and visibility fails OPEN, so a field the predicate was authored to HIDE renders anyway \u2014 and an unconditional 'required: true' on such a field dead-ends record creation in the console while the REST door still accepts it. Nothing was rewritten and no behaviour changed here; rebuild the artifact with current tooling ('os build') so its predicates carry a bound root ('record.<field>').`
+    );
+  }
   /**
    * Parse raw artifact JSON (envelope or bare definition) and register all
    * metadata items into the MetadataManager.
@@ -4882,16 +5458,22 @@ var MetadataPlugin = class {
     let metadata;
     const obj = raw;
     if (obj?.schemaVersion && obj?.commitId && obj?.metadata !== void 0) {
-      const artifact = EnvironmentArtifactSchema.parse(obj);
+      const artifact = EnvironmentArtifactSchema.parse({
+        ...obj,
+        metadata: this._convertArtifactForward(ctx, obj.metadata, label)
+      });
       metadata = artifact.metadata;
     } else if (obj?.success && obj?.data?.metadata) {
-      const artifact = EnvironmentArtifactSchema.parse(obj.data);
+      const artifact = EnvironmentArtifactSchema.parse({
+        ...obj.data,
+        metadata: this._convertArtifactForward(ctx, obj.data.metadata, label)
+      });
       metadata = artifact.metadata;
     } else {
-      const def = ObjectStackDefinitionSchema.parse(obj);
+      const def = ObjectStackDefinitionSchema.parse(this._convertArtifactForward(ctx, obj, label));
       const canonical = JSON.stringify(def, Object.keys(def).sort());
       const checksum = (0, import_node_crypto2.createHash)("sha256").update(canonical).digest("hex");
-      const environmentId = this.options.environmentId ?? "proj_local";
+      const environmentId = this.options.environmentId ?? "env_local";
       EnvironmentArtifactSchema.parse({
         schemaVersion: "0.1",
         environmentId,
@@ -4905,53 +5487,127 @@ var MetadataPlugin = class {
     const memLoader = new MemoryLoader();
     const manifestPackageId = metadata?.manifest?.id ?? metadata?.id ?? void 0;
     const manifestVersion = metadata?.manifest?.version ?? metadata?.version ?? void 0;
+    const carriesPackages = Array.isArray(metadata?.packages);
+    const bodies = (0, import_core2.resolveArtifactPackageOrder)(metadata);
+    const ownedByPackage = /* @__PURE__ */ new Map();
+    const claim = (type, name) => {
+      let names = ownedByPackage.get(type);
+      if (!names) ownedByPackage.set(type, names = /* @__PURE__ */ new Set());
+      names.add(name);
+    };
+    const claimed = (type, name) => ownedByPackage.get(type)?.has(name) === true;
+    let totalRegistered = 0;
+    for (const body of bodies) {
+      totalRegistered += await this._registerArtifactBodyCollections(
+        ctx,
+        memLoader,
+        body,
+        carriesPackages ? {
+          packageId: (0, import_core2.artifactPackageId)(body),
+          packageVersion: body?.version ?? void 0
+        } : { packageId: manifestPackageId, packageVersion: manifestVersion },
+        { claim: carriesPackages ? claim : void 0 }
+      );
+    }
+    if (carriesPackages) {
+      const residual = await this._registerArtifactBodyCollections(
+        ctx,
+        memLoader,
+        metadata,
+        { packageId: manifestPackageId, packageVersion: manifestVersion },
+        { skip: claimed }
+      );
+      totalRegistered += residual;
+      if (residual > 0) {
+        ctx.logger.warn(
+          `[MetadataPlugin] artifact '${label}' carries ${residual} top-level metadata item(s) that none of its ${bodies.length} package bodies declare. They were registered under the artifact's own manifest id ('${manifestPackageId ?? "<none>"}') because no package in the artifact claims them, so every door will report that id as their owner. Rebuild the artifact so each collection it ships is carried by the package that owns it.`
+        );
+      }
+    }
+    this.manager.registerLoader(memLoader);
+    ctx.logger.info("[MetadataPlugin] Artifact metadata loaded", { source: label, totalRegistered });
+    return totalRegistered;
+  }
+  /**
+   * Register ONE artifact body's collections into the MetadataManager.
+   *
+   * A "body" is either the whole artifact (the single-package branch, where
+   * the artifact and its one package are the same object) or one entry of
+   * `packages[]` (ADR-0130 D4), which is an assembled
+   * `{ ...manifest, ...collections }` payload carrying the same collection
+   * keys the top level does. The loop is identical for both — that is the
+   * point: there is one ingestion of a collection here, not one per shape.
+   *
+   * @param provenance - The `(packageId, packageVersion)` every item found in
+   *   this body is stamped with (ADR-0010 §3.7, via `applyProtection`). It is
+   *   the body's OWN identity, never the enclosing artifact's, which is what
+   *   makes a multi-package artifact's items agree with the registry and with
+   *   `GET /api/v1/packages` about who owns them.
+   * @param slots.claim - Called with every `(type, name)` this pass
+   *   registered. Passed when reading package bodies; the residual sweep uses
+   *   what it recorded.
+   * @param slots.skip - Consulted before registering each `(type, name)`.
+   *   Passed ONLY by the residual sweep, so a package body's copy is never
+   *   overwritten by the flattened top-level copy of the same definition —
+   *   the overwrite that re-attributed the item to the artifact's manifest.
+   *   ⛔ It is never passed while reading the bodies themselves: two items of
+   *   one name inside one body still register as they always have (last
+   *   wins), because suppressing that would be a behaviour change on the
+   *   single-package branch D7 pins.
+   * @returns How many items this body registered.
+   */
+  async _registerArtifactBodyCollections(ctx, memLoader, body, provenance, slots = {}) {
+    const { packageId, packageVersion } = provenance;
     let totalRegistered = 0;
     for (const [field, metaType] of Object.entries(ARTIFACT_FIELD_TO_TYPE)) {
-      const items = metadata[field];
+      const items = body[field];
       if (!Array.isArray(items) || items.length === 0) continue;
       for (const item of items) {
-        if (metaType === "view" && (0, import_spec3.isAggregatedViewContainer)(item)) {
-          const viewObject = item?.list?.data?.object ?? item?.form?.data?.object;
+        if (metaType === "view" && (0, import_spec4.isAggregatedViewContainer)(item)) {
+          const viewObject = deriveViewContainerObject(item);
           if (!viewObject) continue;
-          (0, import_shared2.applyProtection)(item, {
-            packageId: manifestPackageId,
-            packageVersion: manifestVersion
+          if (slots.skip?.("view", viewObject)) continue;
+          (0, import_shared3.applyProtection)(item, {
+            packageId,
+            packageVersion
           });
           await memLoader.save("view", viewObject, item);
           await this.manager.register("view", viewObject, item, { notify: false });
           totalRegistered++;
-          for (const vi of (0, import_spec3.expandViewContainer)(viewObject, item)) {
+          slots.claim?.("view", viewObject);
+          for (const vi of (0, import_spec4.expandViewContainer)(viewObject, item)) {
             for (const w of vi._diagnostics?.warnings ?? []) {
               ctx.logger.warn(`[MetadataPlugin] View expansion warning for '${vi.name}': ${w.message}`);
             }
-            (0, import_shared2.applyProtection)(vi, {
-              packageId: manifestPackageId,
-              packageVersion: manifestVersion
+            (0, import_shared3.applyProtection)(vi, {
+              packageId,
+              packageVersion
             });
             await memLoader.save("view", vi.name, vi);
             await this.manager.register("view", vi.name, vi, { notify: false });
             totalRegistered++;
+            slots.claim?.("view", vi.name);
           }
           continue;
         }
         let name = item?.name;
         if (!name) {
           if (metaType === "view") {
-            name = item?.list?.data?.object ?? item?.form?.data?.object;
+            name = deriveViewContainerObject(item);
           }
         }
         if (!name) continue;
-        (0, import_shared2.applyProtection)(item, {
-          packageId: manifestPackageId,
-          packageVersion: manifestVersion
+        if (slots.skip?.(metaType, name)) continue;
+        (0, import_shared3.applyProtection)(item, {
+          packageId,
+          packageVersion
         });
         await memLoader.save(metaType, name, item);
         await this.manager.register(metaType, name, item, { notify: false });
         totalRegistered++;
+        slots.claim?.(metaType, name);
       }
     }
-    this.manager.registerLoader(memLoader);
-    ctx.logger.info("[MetadataPlugin] Artifact metadata loaded", { source: label, totalRegistered });
     return totalRegistered;
   }
   /**
@@ -5027,7 +5683,7 @@ var MetadataPlugin = class {
           for (const item of items) {
             const meta = item;
             if (meta?.name) {
-              (0, import_shared2.applyProtection)(meta, {
+              (0, import_shared3.applyProtection)(meta, {
                 packageId: this.options.packageId
               });
               await this.manager.register(entry.type, meta.name, item, { notify: false });
@@ -5123,9 +5779,43 @@ var RemoteLoader = class {
       format: "json"
     };
   }
+  /**
+   * [#15037] Report only the names that ARE names.
+   *
+   * This read used to be `loadMany<{ name: string }>(type)` mapped straight to
+   * `items.map(i => i.name)`. That type argument is an ASSERTION about bodies
+   * that arrived over HTTP, and nothing checked it: a body with no top-level
+   * `name` yielded `undefined`, which went into an array this signature
+   * declares as `string[]` and reached consumers through
+   * `MetadataManager.listNames()` — a runtime violation of a declared type,
+   * not an untidy entry. A consumer that keys by it, lower-cases it, or feeds
+   * it back to a by-name `load()` gets `undefined` where the type says it
+   * cannot be.
+   *
+   * The guard is `DatabaseLoader.list()`'s, one file away: same cast-then-map
+   * spelling, one `typeof` filter behind it. Silently dropping is the landed
+   * direction, not a preference — `DatabaseLoader` drops rather than throws,
+   * and `FilesystemLoader`'s narrowing carries a maintainer ruling (via the
+   * director seat on #14486, 2026-09-02) that chose narrowing (A) over
+   * refusing loudly (B), because a name in the list that the door answers
+   * `null` for is the silent failure an author reads as their own typo. An
+   * `undefined` here is the extreme form of that name.
+   *
+   * ⛔ NOT copied from the siblings: `MemoryLoader` answers with its store
+   * keys, and #14205 ruled that identity is the key the store holds an item
+   * under rather than `body.name`. This loader reads over HTTP and holds no
+   * store key, so `body.name` is the only identity it has — the list is
+   * narrowed to agree with the door instead. `loadMany()` is deliberately
+   * untouched: it keys nothing, so a nameless body is still served there.
+   *
+   * The predicate is spelled as a type guard, and the mapped element type left
+   * `unknown`, so `tsc` PROVES the declared `string[]` instead of a cast
+   * asserting it — otherwise the compiler reads the filter as always-true and
+   * a later reader deletes it as dead.
+   */
   async list(type) {
     const items = await this.loadMany(type);
-    return items.map((i) => i.name);
+    return items.map((item) => item.name).filter((name) => typeof name === "string");
   }
   async save(type, name, data, _options) {
     const response = await fetch(`${this.baseUrl}/${type}/${name}`, {
@@ -5145,7 +5835,7 @@ var RemoteLoader = class {
 };
 
 // src/index.ts
-var import_metadata_core3 = require("@objectstack/metadata-core");
+var import_metadata_core4 = require("@objectstack/metadata-core");
 
 // src/utils/history-cleanup.ts
 var import_kernel3 = require("@objectstack/spec/kernel");
@@ -5165,9 +5855,9 @@ var HistoryCleanupManager = class {
       return;
     }
     const intervalMs = (this.policy.cleanupIntervalHours ?? 24) * 60 * 60 * 1e3;
-    void this.runCleanup();
+    void runCleanupAndReport(this);
     this.cleanupTimer = setInterval(() => {
-      void this.runCleanup();
+      void runCleanupAndReport(this);
     }, intervalMs);
   }
   /**
@@ -5194,7 +5884,7 @@ var HistoryCleanupManager = class {
     try {
       if (this.policy.maxAgeDays) {
         const cutoffDate = /* @__PURE__ */ new Date();
-        cutoffDate.setDate(cutoffDate.getDate() - this.policy.maxAgeDays);
+        cutoffDate.setUTCDate(cutoffDate.getUTCDate() - this.policy.maxAgeDays);
         const cutoffISO = cutoffDate.toISOString();
         const filter = {
           recorded_at: { $lt: cutoffISO }
@@ -5314,7 +6004,7 @@ var HistoryCleanupManager = class {
       if (organizationId) baseWhere.organization_id = organizationId;
       if (this.policy.maxAgeDays) {
         const cutoffDate = /* @__PURE__ */ new Date();
-        cutoffDate.setDate(cutoffDate.getDate() - this.policy.maxAgeDays);
+        cutoffDate.setUTCDate(cutoffDate.getUTCDate() - this.policy.maxAgeDays);
         const cutoffISO = cutoffDate.toISOString();
         const filter = {
           recorded_at: { $lt: cutoffISO },
@@ -5361,6 +6051,23 @@ var HistoryCleanupManager = class {
     };
   }
 };
+async function runCleanupAndReport(manager) {
+  let outcome;
+  try {
+    outcome = await manager.runCleanup();
+  } catch (error) {
+    console.error(
+      "History cleanup: the run did not complete, so no history row past the retention policy was deleted and the table keeps growing while the system reports healthy. Fix: the cause below comes from the configured data driver, not from the retention policy; call `runCleanup()` directly to reproduce it. Cause:",
+      error
+    );
+    return;
+  }
+  if (outcome.errors > 0) {
+    console.error(
+      `History cleanup: ${outcome.errors} delete operation(s) failed and ${outcome.deleted} row(s) were deleted. The history rows those deletes were meant to remove are still in the table, nothing retries them, and the table grows past the retention policy while the system keeps reporting healthy. Fix: check the data driver delete path for the metadata history table. The per-failure causes are not carried out of \`runCleanup()\`, so reproduce them against the driver directly.`
+    );
+  }
+}
 
 // src/migration/index.ts
 var migration_exports = {};
@@ -5419,6 +6126,9 @@ var MigrationExecutor = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AMBIGUOUS_METADATA_STEM_CODE,
+  AMBIGUOUS_METADATA_STEM_STATUS,
+  AmbiguousMetadataStemError,
   DatabaseLoader,
   FilesystemLoader,
   HistoryCleanupManager,
@@ -5434,7 +6144,9 @@ var MigrationExecutor = class {
   TypeScriptSerializer,
   YAMLSerializer,
   calculateChecksum,
+  deriveViewContainerObject,
   generateDiffSummary,
-  generateSimpleDiff
+  generateSimpleDiff,
+  isAmbiguousMetadataStemError
 });
 //# sourceMappingURL=node.cjs.map