@objectstack/metadata 17.1.0 → 17.3.0

package/dist/index.js

@@ -16,9 +16,14 @@ var __export = (target, all) => {
 // 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) => {
@@ -351,7 +356,7 @@ export default metadata;
 };
 
 // src/loaders/database-loader.ts
-import { SysMetadataObject, SysMetadataHistoryObject } from "@objectstack/metadata-core";
+import { SysMetadataObject as SysMetadataObject2, SysMetadataHistoryObject as SysMetadataHistoryObject2 } from "@objectstack/metadata-core";
 import { applyConversionsToStoredItem } from "@objectstack/spec";
 import { PLURAL_TO_SINGULAR } from "@objectstack/spec/shared";
 
@@ -519,141 +524,49 @@ var LRUCache = class {
   }
 };
 
-// src/utils/schema-sync-errors.ts
-import { isRelationSubObjectPhrase } from "@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: isRelationSubObjectPhrase
+// src/loaders/database-loader.ts
+import { isMissingTableError, isSchemaAlreadyExistsError } from "@objectstack/types";
+
+// 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"
-];
+import { SysMetadataObject, SysMetadataHistoryObject } from "@objectstack/metadata-core";
+var SOURCE_COLUMN = "project_id";
+var TARGET_COLUMN = "environment_id";
+var CANDIDATE_OBJECTS = [SysMetadataObject, 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;
@@ -662,8 +575,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) {
@@ -672,14 +585,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]
     );
@@ -691,6 +604,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 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 = {
@@ -827,9 +750,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);
   }
@@ -874,7 +799,7 @@ var DatabaseLoader = class {
       }
       return max + 1;
     } catch (error) {
-      if (isMissingTableError(error)) return 1;
+      if (isMissingTableError(error, this.historyTableName)) return 1;
       throw error;
     }
   }
@@ -912,7 +837,7 @@ var DatabaseLoader = class {
     }
     try {
       await this.driver.syncSchema(this.tableName, {
-        ...SysMetadataObject,
+        ...SysMetadataObject2,
         name: this.tableName
       });
     } catch (error) {
@@ -951,7 +876,7 @@ var DatabaseLoader = class {
     }
     try {
       await this.driver.syncSchema(this.historyTableName, {
-        ...SysMetadataHistoryObject,
+        ...SysMetadataHistoryObject2,
         name: this.historyTableName
       });
       if (this.historySchemaFailureReported) {
@@ -1120,9 +1045,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)
     };
   }
   // ==========================================
@@ -1173,7 +1098,7 @@ var DatabaseLoader = class {
    *          with its empty value.
    */
   rethrowUnlessTableUnprovisioned(error) {
-    if (isMissingTableError(error)) return;
+    if (isMissingTableError(error, this.tableName)) return;
     throw error;
   }
   // ==========================================
@@ -1223,17 +1148,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) {
@@ -1241,6 +1187,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) {
@@ -1276,7 +1245,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
       };
@@ -1337,7 +1306,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)
     };
   }
   /**
@@ -1394,7 +1363,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 };
@@ -1694,6 +1663,35 @@ var EndpointMatcher = class {
   }
 };
 
+// src/view-container-expansion.ts
+import {
+  expandViewContainer,
+  isAggregatedViewContainer
+} from "@objectstack/spec";
+import { applyProtection } from "@objectstack/spec/shared";
+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;
+}
+function expandRuntimeViewContainer(data) {
+  if (!isAggregatedViewContainer(data)) return [];
+  const container = data;
+  const viewObject = deriveViewContainerObject(container);
+  if (!viewObject) return [];
+  const out = [];
+  for (const vi of expandViewContainer(viewObject, container)) {
+    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 = {
@@ -1733,8 +1731,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
@@ -2309,6 +2305,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);
@@ -2321,13 +2378,7 @@ 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) {
         degraded = true;
@@ -2480,13 +2531,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());
   }
@@ -2731,12 +2776,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))
     );
   }
@@ -3154,66 +3241,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)
   // ==========================================
@@ -3987,6 +4026,7 @@ var MetadataManager = _MetadataManager;
 // src/plugin.ts
 import { readFile as readFile2 } from "fs/promises";
 import { createHash as createHash2 } from "crypto";
+import { resolveArtifactPackageOrder, artifactPackageId } from "@objectstack/core";
 
 // src/node-metadata-manager.ts
 import * as path2 from "path";
@@ -3997,7 +4037,11 @@ import * as fs from "fs/promises";
 import * as path from "path";
 import { glob } from "glob";
 import { createHash } from "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;
@@ -4095,6 +4139,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 = [];
@@ -4117,7 +4237,7 @@ var FilesystemLoader = class {
             const serializer = this.getSerializer(format);
             if (serializer) {
               const data = serializer.deserialize(content);
-              items.push(data);
+              items.push({ file, data });
             }
           } catch (error) {
             this.logger?.warn("Failed to load file", {
@@ -4171,6 +4291,30 @@ 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);
     try {
@@ -4179,11 +4323,7 @@ var FilesystemLoader = class {
         ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*"],
         nodir: true
       });
-      return files.map((file) => {
-        const ext = path.extname(file);
-        const basename3 = path.basename(file, ext);
-        return basename3;
-      });
+      return files.map((file) => this.resolvableNameForPath(typeDir, path.join(typeDir, file))).filter((name) => name !== null);
     } catch (error) {
       this.logger?.error("Failed to list", void 0, {
         type,
@@ -4261,12 +4401,66 @@ 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);
+  }
   /**
    * 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 {
@@ -4312,6 +4506,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 {
@@ -4436,6 +4643,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;
   }
@@ -4482,19 +4703,23 @@ var MemoryLoader = class {
 
 // src/plugin.ts
 import { DEFAULT_METADATA_TYPE_REGISTRY } from "@objectstack/spec/kernel";
-import { applyProtection } from "@objectstack/spec/shared";
+import { applyProtection as applyProtection2 } from "@objectstack/spec/shared";
 import {
-  SysMetadataObject as SysMetadataObject2,
-  SysMetadataHistoryObject as SysMetadataHistoryObject2,
+  SysMetadataObject as SysMetadataObject3,
+  SysMetadataHistoryObject as SysMetadataHistoryObject3,
   SysMetadataCommitObject,
   SysMetadataAuditObject,
-  SysViewDefinitionObject
+  SysViewDefinitionObject,
+  applyArtifactForwardConversions,
+  detectUnboundFormViewPredicateRoots,
+  BOUND_FORM_VIEW_PREDICATE_ROOTS,
+  BOUND_FORM_FIELD_PREDICATE_ROOTS
 } from "@objectstack/metadata-core";
-import { isAggregatedViewContainer, expandViewContainer } from "@objectstack/spec";
 import { isAggregatedViewContainer as isAggregatedViewContainer2, expandViewContainer as expandViewContainer2 } from "@objectstack/spec";
+import { isAggregatedViewContainer as isAggregatedViewContainer3, expandViewContainer as expandViewContainer3 } from "@objectstack/spec";
 var queryableMetadataObjects = [
-  SysMetadataObject2,
-  SysMetadataHistoryObject2,
+  SysMetadataObject3,
+  SysMetadataHistoryObject3,
   // ADR-0067 commit log — sibling of sys_metadata_history (see note above).
   SysMetadataCommitObject,
   SysMetadataAuditObject,
@@ -4513,7 +4738,10 @@ var ARTIFACT_FIELD_TO_TYPE = {
   dashboards: "dashboard",
   reports: "report",
   actions: "action",
-  themes: "theme",
+  // `themes: 'theme'` removed at #10485 (ADR-0049): the carrier key is
+  // retired, so a parsed artifact can no longer carry the field — and the
+  // ingest half of the dead pipeline (items stored, read by nothing) goes
+  // with the authoring half rather than surviving it as drift.
   workflows: "workflow",
   flows: "flow",
   // ADR-0090 D3: stacks declare `positions` (stack.zod.ts); the retired
@@ -4521,8 +4749,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",
@@ -4565,14 +4822,29 @@ 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", {
         root: this.options.rootDir || process.cwd(),
         watch: this.options.watch,
         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 {
@@ -4594,7 +4866,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) => {
@@ -4677,7 +4949,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 {
@@ -4717,7 +4989,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
                   });
@@ -4739,7 +5011,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");
         }
@@ -4747,7 +5025,22 @@ var MetadataPlugin = class {
         console.warn("[MetadataPlugin] Failed to register HMR endpoint", e?.message);
       }
     };
-    this.stop = async (ctx) => {
+    /**
+     * Teardown — the kernel's ONLY teardown hook.
+     *
+     * [#10772] This body used to be spelled `stop(ctx)`. `Plugin`
+     * (`@objectstack/core`'s `types.ts`) declares `init()`, `start?(ctx)` and
+     * `destroy?()` and no `stop()`, and `ObjectKernel.performShutdown()` /
+     * `LiteKernel.destroy()` walk the plugins in reverse calling
+     * `plugin.destroy()` — so the artifact watcher, the manager and the
+     * repository were all still held after `await kernel.shutdown()` had
+     * RESOLVED. The `start`/`stop` pair read symmetric to a reviewer because
+     * `start()` really is on the interface; only one half was ever called.
+     *
+     * Idempotent: every handle is cleared as it is released, so a second
+     * teardown is a no-op rather than a second close.
+     */
+    this.destroy = async () => {
       if (this.artifactWatcher) {
         try {
           await this.artifactWatcher.close();
@@ -4758,7 +5051,7 @@ var MetadataPlugin = class {
       try {
         await this.manager.dispose();
       } catch (e) {
-        ctx.logger.warn("[MetadataPlugin] manager.dispose() failed", { error: e?.message });
+        this.initCtx?.logger?.warn?.("[MetadataPlugin] manager.dispose() failed", { error: e?.message });
       }
       const repo = this.repository;
       if (repo && typeof repo.close === "function") {
@@ -4769,6 +5062,18 @@ var MetadataPlugin = class {
       }
       this.repository = void 0;
     };
+    /**
+     * Retained alias for {@link destroy}. Kept because it is public API of an
+     * exported class: an embedder may have learned to call it directly
+     * precisely BECAUSE the kernel never did, and deleting it would break them.
+     * Still an arrow property, so a detached `const { stop } = plugin` call
+     * keeps working too. The parameter is now optional and ignored —
+     * `destroy()` takes no context, so teardown logs through the context
+     * captured in `init()`.
+     */
+    this.stop = async (_ctx) => {
+      await this.destroy();
+    };
     this.options = {
       ...options,
       watch: options.watch ?? false
@@ -4808,6 +5113,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 = 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 = 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(BOUND_FORM_FIELD_PREDICATE_ROOTS)}` : null,
+      surfaces.has("section") ? `on a form SECTION: ${quote(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.
@@ -4826,16 +5231,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 = createHash2("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,
@@ -4849,53 +5260,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 = 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: 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" && isAggregatedViewContainer2(item)) {
-          const viewObject = item?.list?.data?.object ?? item?.form?.data?.object;
+        if (metaType === "view" && isAggregatedViewContainer3(item)) {
+          const viewObject = deriveViewContainerObject(item);
           if (!viewObject) continue;
-          applyProtection(item, {
-            packageId: manifestPackageId,
-            packageVersion: manifestVersion
+          if (slots.skip?.("view", viewObject)) continue;
+          applyProtection2(item, {
+            packageId,
+            packageVersion
           });
           await memLoader.save("view", viewObject, item);
           await this.manager.register("view", viewObject, item, { notify: false });
           totalRegistered++;
-          for (const vi of expandViewContainer2(viewObject, item)) {
+          slots.claim?.("view", viewObject);
+          for (const vi of expandViewContainer3(viewObject, item)) {
             for (const w of vi._diagnostics?.warnings ?? []) {
               ctx.logger.warn(`[MetadataPlugin] View expansion warning for '${vi.name}': ${w.message}`);
             }
-            applyProtection(vi, {
-              packageId: manifestPackageId,
-              packageVersion: manifestVersion
+            applyProtection2(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;
-        applyProtection(item, {
-          packageId: manifestPackageId,
-          packageVersion: manifestVersion
+        if (slots.skip?.(metaType, name)) continue;
+        applyProtection2(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;
   }
   /**
@@ -4971,7 +5456,7 @@ var MetadataPlugin = class {
           for (const item of items) {
             const meta = item;
             if (meta?.name) {
-              applyProtection(meta, {
+              applyProtection2(meta, {
                 packageId: this.options.packageId
               });
               await this.manager.register(entry.type, meta.name, item, { notify: false });
@@ -5089,7 +5574,7 @@ var RemoteLoader = class {
 };
 
 // src/index.ts
-import { SysMetadataObject as SysMetadataObject3, SysMetadataHistoryObject as SysMetadataHistoryObject3 } from "@objectstack/metadata-core";
+import { SysMetadataObject as SysMetadataObject4, SysMetadataHistoryObject as SysMetadataHistoryObject4 } from "@objectstack/metadata-core";
 
 // src/utils/history-cleanup.ts
 import { DEFAULT_METADATA_TYPE_REGISTRY as DEFAULT_METADATA_TYPE_REGISTRY2 } from "@objectstack/spec/kernel";
@@ -5370,11 +5855,12 @@ export {
   MetadataPlugin,
   migration_exports as Migration,
   RemoteLoader,
-  SysMetadataHistoryObject3 as SysMetadataHistoryObject,
-  SysMetadataObject3 as SysMetadataObject,
+  SysMetadataHistoryObject4 as SysMetadataHistoryObject,
+  SysMetadataObject4 as SysMetadataObject,
   TypeScriptSerializer,
   YAMLSerializer,
   calculateChecksum,
+  deriveViewContainerObject,
   generateDiffSummary,
   generateSimpleDiff
 };