@objectstack/metadata 17.0.0-rc.5 → 17.0.0

package/dist/index.cjs

@@ -553,6 +553,7 @@ var LRUCache = class {
 };
 
 // src/utils/schema-sync-errors.ts
+var import_types = require("@objectstack/types");
 var ALREADY_EXISTS = {
   codes: /* @__PURE__ */ new Set([
     // PostgreSQL SQLSTATE (class 42 — syntax error or access rule violation)
@@ -596,14 +597,67 @@ var MISSING_TABLE = {
    *   - 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
+  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
+  }
 };
 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") return signature.message.test(error);
+  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;
@@ -616,48 +670,6 @@ function isMissingTableError(error, depth = 0) {
   return matchesDriverError(error, MISSING_TABLE, depth);
 }
 
-// src/migrations/add-sys-metadata-overlay-index.ts
-var INDEX_NAME = "idx_sys_metadata_overlay_active";
-var TABLE = "sys_metadata";
-var COLUMNS = "(type, name, organization_id, environment_id, scope)";
-var WHERE = "state = 'active'";
-async function addSysMetadataOverlayIndex(driver) {
-  const driverAny = driver;
-  const exec = async (sql) => {
-    if (typeof driverAny.raw === "function") {
-      await driverAny.raw(sql);
-    } else if (typeof driverAny.execute === "function") {
-      await driverAny.execute(sql);
-    } else {
-      throw new Error("driver has neither raw nor execute");
-    }
-  };
-  const partialSql = `CREATE UNIQUE INDEX IF NOT EXISTS ${INDEX_NAME} ON ${TABLE} ${COLUMNS} WHERE ${WHERE}`;
-  const fallbackSql = `CREATE INDEX IF NOT EXISTS ${INDEX_NAME} ON ${TABLE} ${COLUMNS}`;
-  try {
-    await exec(partialSql);
-    return { index: INDEX_NAME, status: "created" };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (/partial|where clause|syntax/i.test(msg)) {
-      try {
-        await exec(fallbackSql);
-        return { index: INDEX_NAME, status: "fallback_non_unique" };
-      } catch (fallbackErr) {
-        return {
-          index: INDEX_NAME,
-          status: "error",
-          error: fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)
-        };
-      }
-    }
-    if (/already exists/i.test(msg)) {
-      return { index: INDEX_NAME, status: "already_exists" };
-    }
-    return { index: INDEX_NAME, status: "error", error: msg };
-  }
-}
-
 // src/migrations/migrate-project-id-to-environment-id.ts
 var AFFECTED_TABLES = [
   "sys_metadata",
@@ -807,23 +819,40 @@ var DatabaseLoader = class {
   // ==========================================
   // Internal CRUD helpers (driver vs engine)
   // ==========================================
+  // NOTE (#6231, closed out by #7178): BOTH branches below now take `query`
+  // unchanged and uncast. `DriverQuery` is `Omit<QueryAST, 'object'>`, so the
+  // object name travels as argument one only — that was always enough for the
+  // driver branch. The ENGINE branch used to carry `as any`, for one reason:
+  // `EngineQueryOptionsSchema.search` admitted only the structured
+  // `FullTextSearchSchema`, while `QueryAST.search` (hence `DriverQuery`) also
+  // admits the bare query string that ADR-0061 D1 calls the canonical Tier-1
+  // spelling and that the engine actually serves, so `DriverQuery` was not
+  // assignable to `EngineQueryOptionsParsed`. #7178 aligned the two schemas;
+  // the casts are now genuinely vestigial and are gone, which restores real
+  // `where`/`orderBy`/`fields` checking on the metadata main read path — this
+  // schema is not `.strict()`, so an unknown key here is SILENTLY DROPPED
+  // (`check:query-options-erasure`'s own rationale) and the erased type was
+  // the only thing standing between a typo and that silence.
+  //
+  // If a future edit makes one of these stop compiling, the honest fix is to
+  // reconcile the two schemas again — not to reinstate the cast.
   async _find(table, query) {
     if (this.engine) {
       return this.engine.find(table, query);
     }
-    return this.driver.find(table, { object: table, ...query });
+    return this.driver.find(table, query);
   }
   async _findOne(table, query) {
     if (this.engine) {
       return this.engine.findOne(table, query);
     }
-    return this.driver.findOne(table, { object: table, ...query });
+    return this.driver.findOne(table, query);
   }
   async _count(table, query) {
     if (this.engine) {
       return this.engine.count(table, query);
     }
-    return this.driver.count(table, { object: table, ...query });
+    return this.driver.count(table, query);
   }
   async _create(table, data) {
     if (this.engine) {
@@ -905,9 +934,12 @@ var DatabaseLoader = class {
         }
         if (driver) {
           await migrateProjectIdToEnvironmentId(driver).catch(() => void 0);
-          await addSysMetadataOverlayIndex(driver);
         }
-      } catch {
+      } catch (error) {
+        console.warn(
+          `[Metadata] Could not resolve a raw-SQL driver from the engine for \`${this.tableName}\` \u2014 the project_id\u2192environment_id forward migration was SKIPPED. Legacy rows (if any) keep the pre-v5.0 column and read back as unset. Metadata reads and writes are otherwise unaffected. Re-run it explicitly with \`migrateProjectIdToEnvironmentId(driver)\` from \`@objectstack/metadata/migrations\` once the datasource is reachable.`,
+          error
+        );
       }
       return;
     }
@@ -939,10 +971,6 @@ var DatabaseLoader = class {
       await migrateProjectIdToEnvironmentId(this.driver);
     } catch {
     }
-    try {
-      await addSysMetadataOverlayIndex(this.driver);
-    } catch {
-    }
   }
   /**
    * Ensure the history table exists.
@@ -1550,6 +1578,60 @@ function generateId() {
 
 // src/endpoint-matcher.ts
 var import_api = require("@objectstack/spec/api");
+
+// src/stored-envelope.ts
+var STORED_ENVELOPE_KEYS = Object.freeze([
+  "package",
+  "packageId",
+  "publishedAt",
+  "publishedBy",
+  "publishedDefinition",
+  "state",
+  "version"
+]);
+var STORED_BODY_KEY = "metadata";
+var ENVELOPE_KEYS = /* @__PURE__ */ new Set([...STORED_ENVELOPE_KEYS, STORED_BODY_KEY]);
+var EMPTY_ENVELOPE = Object.freeze({});
+function peelStoredEnvelope(item) {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) {
+    return { envelope: EMPTY_ENVELOPE, body: item, wrapped: false };
+  }
+  const row = item;
+  const wrappedBody = row[STORED_BODY_KEY];
+  if (wrappedBody !== void 0 && wrappedBody !== null) {
+    const envelope2 = {};
+    for (const key of Object.keys(row)) {
+      if (key === STORED_BODY_KEY) continue;
+      envelope2[key] = row[key];
+    }
+    return { envelope: Object.freeze(envelope2), body: wrappedBody, wrapped: true };
+  }
+  let envelope;
+  for (const key of Object.keys(row)) {
+    if (!ENVELOPE_KEYS.has(key)) continue;
+    envelope ?? (envelope = {});
+    envelope[key] = row[key];
+  }
+  if (!envelope) return { envelope: EMPTY_ENVELOPE, body: row, wrapped: false };
+  const body = {};
+  for (const key of Object.keys(row)) {
+    if (ENVELOPE_KEYS.has(key)) continue;
+    body[key] = row[key];
+  }
+  return { envelope: Object.freeze(envelope), body, wrapped: false };
+}
+function storedItemName(peeled) {
+  const fromEnvelope = peeled.envelope.name;
+  if (typeof fromEnvelope === "string") return fromEnvelope;
+  const body = peeled.body;
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    const fromBody = body.name;
+    if (typeof fromBody === "string") return fromBody;
+  }
+  return void 0;
+}
+
+// src/endpoint-matcher.ts
 function normalizeEndpointMethod(method) {
   return String(method ?? "").toUpperCase();
 }
@@ -1559,9 +1641,10 @@ function endpointIndexKey(method, path3) {
 function buildEndpointIndex(items, logger) {
   const index = /* @__PURE__ */ new Map();
   for (const item of items) {
-    const parsed = import_api.ApiEndpointSchema.safeParse(item);
+    const peeled = peelStoredEnvelope(item);
+    const parsed = import_api.ApiEndpointSchema.safeParse(peeled.body);
     if (!parsed.success) {
-      const declaredName = item && typeof item === "object" && typeof item.name === "string" ? item.name : "<unnamed>";
+      const declaredName = storedItemName(peeled) ?? "<unnamed>";
       logger.error(
         `[EndpointMatcher] stored api item '${declaredName}' does not satisfy ApiEndpointSchema \u2014 it is EXCLUDED from endpoint matching and its declared route will answer 404. Fix the declaration (or remove it); the endpoint index never serves a half-valid shape.`,
         void 0,
@@ -1700,16 +1783,40 @@ var _MetadataManager = class _MetadataManager {
     // above. The concurrent half is delivered by `inflightListReads` below, which
     // is why the two fields are one policy and are documented together.
     //
-    // [#5184] That hazard is NOT historical — it was re-verified on the current
-    // driver stack before this policy was chosen. `DatabaseLoader._find()` still
-    // issues `engine.find('sys_metadata', …)` without threading the caller's
-    // transaction, and `driver-sql` still treats SQLite as a single-connection
-    // pool (`activeTransactions`, `assertBareKnexSafe` — the latter a dev/test
-    // guard that is a no-op in production, so production still waits the timeout
-    // out). `plugin-audit`'s `captureBefore` threads the transaction by hand for
-    // exactly this reason. Hence the policy below keeps caching degraded reads
-    // rather than skipping them: "don't cache a degraded read" would trade one
-    // 30s silent window for a fresh 60s stall per call.
+    // [#5184; re-measured under #7708 on 2026-08-11] That hazard is NOT
+    // historical — and the re-measurement NARROWED it rather than retiring it.
+    // Measured on the current stack: real `ObjectQL` + real `SqlDriver`
+    // (better-sqlite3), a real `DatabaseLoader.list()` with the loader's own
+    // cache off, `knex.client.pool.max === 1` confirmed for the SQLite dialect
+    // and `acquireConnectionTimeout` left at the knex default of 60s.
+    //
+    //   • Transaction opened DIRECTLY on the driver (`driver.beginTransaction()`)
+    //     → the read STALLS for the full timeout and then throws knex's "Timeout
+    //     acquiring a connection" (measured: 60_085ms). `DatabaseLoader._find()`
+    //     forwards no options, so nothing threads the caller's transaction, and
+    //     `driver-sql` still models SQLite as a single-connection pool
+    //     (`activeTransactions`, `assertBareKnexSafe` — the latter a dev/test
+    //     guard that is a no-op in production, so production still waits the
+    //     timeout out). `list()` catches that throw and degrades, which is
+    //     precisely the entry whose TTL this policy is choosing.
+    //   • Transaction opened through `engine.transaction()` / `ScopedContext`
+    //     → returns immediately (measured: 12ms, with `activeTransactions === 1`
+    //     and the driver observably receiving the handle on the call). Those
+    //     publish the transaction into the engine's ambient `txStore` (ADR-0034)
+    //     and `buildDriverOptions` threads it onto the read for the loader.
+    //
+    // So the stall shape is live but CONDITIONAL: it needs an open transaction
+    // that the engine's ambient store cannot see. `SqlDriver.ensureSequencesTable()`
+    // is the live witness that this is worth designing against — it takes
+    // `parentTrx` and runs its DDL on the caller's transaction for exactly this
+    // reason, with `assertBareKnexSafe` as the tripwire for callers that forget;
+    // `sql-driver-sqlite-tx-guard.test.ts` pins both halves. (Until #7708 the
+    // witness cited here was `plugin-audit`'s `captureBefore`, retired by #6656.
+    // It was REPLACED rather than dropped: the example died, the hazard did not.)
+    //
+    // Hence the policy below keeps caching degraded reads rather than skipping
+    // them: "don't cache a degraded read" would trade one 30s silent window for
+    // a fresh 60s stall per call on every caller in the first bullet.
     //
     // [#5184] WHAT IS ACTUALLY CACHED, AND FOR HOW LONG — this paragraph is the
     // contract, and it describes `cacheListResult()` / `readCachedList()` below.
@@ -1796,6 +1903,15 @@ var _MetadataManager = class _MetadataManager {
      * only, so a fresh read that already replaced it keeps its slot. Nothing
      * accumulates — a wave of callers arriving after settle finds the cache the
      * settle just wrote, and once that lapses it starts one new read.
+     *
+     * [#6504] The shared value is the whole {@link ListReadResult}, not just
+     * `items`. "Sharers share the outcome" above is stated about the answer *and*
+     * its degraded verdict, and while the promise carried only `items` that was
+     * true of `list()` alone: a {@link listDiagnosed} caller joining an in-flight
+     * read had no way to reach the verdict that read had already computed, and
+     * would have had to either re-walk the loaders (defeating this map) or invent
+     * a second, unmemoized answer. `list()` narrows to `.items` at its own return
+     * instead, so every sharer still receives the same array instance.
      */
     this.inflightListReads = /* @__PURE__ */ new Map();
     // [#5108] Loader names whose read failure has already been reported at
@@ -1992,6 +2108,8 @@ var _MetadataManager = class _MetadataManager {
    * {@link MetadataWriteOptions.notify} before doing so.
    */
   async register(type, name, data, options) {
+    (0, import_core.assertMetadataRegisterContract)(type, name, data);
+    type = (0, import_core.canonicalMetadataServiceType)(type);
     if (this.config.persistence?.writable === false) {
       const msg = `MetadataManager is read-only (persistence.writable=false); refusing to register ${type}/${name}`;
       if (this.config.validation?.throwOnError) {
@@ -2044,6 +2162,7 @@ var _MetadataManager = class _MetadataManager {
    * consumers will read the pre-write definition until restart.
    */
   registerInMemory(type, name, data) {
+    type = (0, import_core.canonicalMetadataServiceType)(type);
     if (!this.registry.has(type)) {
       this.registry.set(type, /* @__PURE__ */ new Map());
     }
@@ -2060,18 +2179,33 @@ var _MetadataManager = class _MetadataManager {
    * has with {@link loadDiagnosed}, so every existing caller keeps its exact
    * behaviour and only callers that ASK for the verdict pay for it.
    *
-   * [#5840] Deliberately NOT expressed as `(await getDiagnosed(…)).data`,
-   * although that is what it computes. The obvious delegation adds one
-   * `await` hop, and a registry hit here is observed one microtask sooner than
-   * it would be through a second async frame — which `register()`'s watchers
-   * depend on, because `notifyWatchers` does not await its handlers and
-   * ObjectQL's bridge re-reads through `get()` on the event rather than
-   * trusting the payload (`register-notifies-watchers.test.ts` pins it, and
-   * went red on the delegating version). The duplication is three lines and is
-   * pinned from the other side: `get()` and `getDiagnosed().data` are asserted
-   * to agree on every case in `metadata-manager-get-diagnosed.test.ts`.
+   * Not expressed as `(await getDiagnosed(…)).data`, although that is what it
+   * computes — and the reason has CHANGED, so do not read the duplication as a
+   * standing constraint.
+   *
+   * [#5840] recorded the delegation as unsafe: it adds one `await` hop, and
+   * `register-notifies-watchers.test.ts` went red on the delegating version, so
+   * three lines were duplicated to hold the frame count fixed. [#6043] measured
+   * that test and found it was pinning this method's microtask depth rather than
+   * the ordering guarantee it named — `notifyWatchers` never awaits its handlers,
+   * so a subscriber's `await get(…)` had simply been settling inside the
+   * microtasks `await register(…)` yields. That case now asserts the ordering
+   * synchronously against the registry and does not observe this method's frame
+   * count at all; the whole `@objectstack/metadata` suite was re-measured on the
+   * delegating version and stayed green.
+   *
+   * What survives is a plain, local reason: the registry hit is the hot path and
+   * answering it without a second async frame is worth three lines. Nothing
+   * external depends on the hop count any more. Consolidating the two into one
+   * delegation is therefore a viable, deliberately un-taken change (#6043 was
+   * test-scoped) — if you take it, note that `get()`'s callers outside this
+   * package were never surveyed for timing sensitivity, only this package's
+   * tests. Either way the two stay pinned to each other from the other side:
+   * `get()` and `getDiagnosed().data` are asserted to agree on every case in
+   * `metadata-manager-get-diagnosed.test.ts`.
    */
   async get(type, name) {
+    type = (0, import_core.canonicalMetadataServiceType)(type);
     const typeStore = this.registry.get(type);
     if (typeStore?.has(name)) {
       return typeStore.get(name);
@@ -2103,6 +2237,7 @@ var _MetadataManager = class _MetadataManager {
    * cannot prove the item is absent, so we decline to claim it is.
    */
   async getDiagnosed(type, name) {
+    type = (0, import_core.canonicalMetadataServiceType)(type);
     const typeStore = this.registry.get(type);
     if (typeStore?.has(name)) {
       return { data: typeStore.get(name), degraded: false, errors: [] };
@@ -2124,19 +2259,64 @@ var _MetadataManager = class _MetadataManager {
    * `listCache`.
    */
   async list(type) {
+    return (await this.readList((0, import_core.canonicalMetadataServiceType)(type))).items;
+  }
+  /**
+   * `list`, plus whether the answer can be trusted as complete.
+   *
+   * [#6504] The plural counterpart of {@link getDiagnosed}, and the same defect
+   * one read over: `readListUncached` has computed this verdict since #5184 and
+   * `list()` spent it entirely on a cache TTL, so a consumer receiving a short
+   * set could not ask whether it was short because that is all anyone declared
+   * or because a loader was down. {@link reportLoaderReadFailure}'s own message
+   * says what that costs — "every list served from now on is a PARTIAL set
+   * presented as a complete one, and the server keeps reporting healthy" — and
+   * until this member existed that sentence was addressed to a log reader only,
+   * because no caller had a way to ask.
+   *
+   * Sharper than the singular case rather than merely analogous: `list` is the
+   * read whose answer carries a **count**, and a consumer restating
+   * `items.length` as "this environment contains N items" makes a positive,
+   * numeric claim about what an author declared out of a read that partly did
+   * not happen.
+   *
+   * Reads through exactly the same cache and single-flight machinery `list()`
+   * does — same entry, same TTLs, same in-flight join — so asking for the
+   * verdict costs no extra loader walk, and `list()` and
+   * `listDiagnosed().items` cannot drift: they are the same read, narrowed at
+   * different points. `degraded` is true when at least one loader threw while
+   * this set was assembled; unlike {@link getDiagnosed} it does NOT additionally
+   * require that nothing answered, because a plural read that lost one loader is
+   * partial even when the others answered plenty — which is the whole fact.
+   */
+  async listDiagnosed(type) {
+    const { items, degraded, errors } = await this.readList((0, import_core.canonicalMetadataServiceType)(type));
+    return { items, degraded, errors };
+  }
+  /**
+   * The cached / single-flight read behind {@link list} and
+   * {@link listDiagnosed}.
+   *
+   * [#6504] Extracted so the two members are one read seen at two widths rather
+   * than two implementations that have to be kept in agreement — the shape
+   * `get`/`getDiagnosed` pay for with a duplicated body and a test pinning them
+   * to each other. Everything below is unchanged in behaviour from when it was
+   * inlined in `list()`; only the verdict now survives the return.
+   */
+  async readList(type) {
     const cached = this.readCachedList(type);
     if (cached) {
-      return cached.items;
+      return cached;
     }
     const joined = this.inflightListReads.get(type);
     if (joined) {
       return joined;
     }
-    const shared = this.readListUncached(type).then(({ items, degraded }) => {
+    const shared = this.readListUncached(type).then((result) => {
       if (this.inflightListReads.get(type) === shared) {
-        this.cacheListResult(type, items, degraded);
+        this.cacheListResult(type, result);
       }
-      return items;
+      return result;
     });
     this.inflightListReads.set(type, shared);
     try {
@@ -2167,6 +2347,7 @@ var _MetadataManager = class _MetadataManager {
       }
     }
     let degraded = false;
+    const errors = [];
     for (const loader of this.loaders.values()) {
       try {
         const loaderItems = await loader.loadMany(type);
@@ -2179,10 +2360,11 @@ var _MetadataManager = class _MetadataManager {
         this.reportLoaderReadRecovered(loader.contract.name);
       } catch (e) {
         degraded = true;
+        errors.push(`${loader.contract.name}: ${e instanceof Error ? e.message : String(e)}`);
         this.reportLoaderReadFailure(loader.contract.name, type, e);
       }
     }
-    return { items: Array.from(items.values()), degraded };
+    return { items: Array.from(items.values()), degraded, errors };
   }
   /**
    * Report — at `error`, once per outage episode — that a loader could not be
@@ -2244,9 +2426,14 @@ var _MetadataManager = class _MetadataManager {
    * one thing this cache used to throw away. A result assembled while a loader
    * was unreadable is stored, but stored *as* what it is, so it expires on the
    * degraded TTL and any reader can tell it apart from a complete answer.
+   *
+   * [#6504] Takes the whole read result rather than its parts for the same
+   * reason: a signature that spreads the verdict across positional arguments is
+   * one a later caller can quietly fill with `false`, which is how the verdict
+   * was lost on the way out in the first place.
    */
-  cacheListResult(type, items, degraded) {
-    this.listCache.set(type, { ts: Date.now(), items, degraded });
+  cacheListResult(type, result) {
+    this.listCache.set(type, { ts: Date.now(), ...result });
   }
   /**
    * Read a still-fresh {@link listCache} entry, or `undefined` when there is
@@ -2399,6 +2586,7 @@ var _MetadataManager = class _MetadataManager {
    * before the await would buy nothing and would re-open step 1's window.
    */
   async unregister(type, name, options) {
+    type = (0, import_core.canonicalMetadataServiceType)(type);
     for (const loader of this.loaders.values()) {
       if (loader.contract.protocol !== "datasource:" || !loader.contract.capabilities.write) continue;
       if (typeof loader.delete !== "function") continue;
@@ -2501,6 +2689,7 @@ var _MetadataManager = class _MetadataManager {
    * Check if a metadata item exists
    */
   async exists(type, name) {
+    type = (0, import_core.canonicalMetadataServiceType)(type);
     if (this.registry.get(type)?.has(name)) {
       return true;
     }
@@ -2515,6 +2704,7 @@ var _MetadataManager = class _MetadataManager {
    * List all names of metadata items of a given type
    */
   async listNames(type) {
+    type = (0, import_core.canonicalMetadataServiceType)(type);
     const names = /* @__PURE__ */ new Set();
     const typeStore = this.registry.get(type);
     if (typeStore) {
@@ -2745,10 +2935,16 @@ var _MetadataManager = class _MetadataManager {
    * ## What it judges, and on what
    *
    * The registry stores either a raw spec document or a publish envelope
-   * (`{ name, packageId, state, metadata: {…spec} }`); the endpoint is read
-   * out with the SAME rule this method's caller uses for
-   * `publishedDefinition` (`data.metadata ?? data`), so publish gates exactly
-   * the document publish is about to snapshot. An item that does not satisfy
+   * (`{ name, packageId, state, metadata: {…spec} }`), and in BOTH shapes the
+   * row carries the metadata layer's bookkeeping. [#5309] The envelope is
+   * peeled off first (`peelStoredEnvelope`) and the gate judges the authored
+   * BODY: the wrapped half of that peel is the `data.metadata ?? data` rule
+   * this method used to spell inline — the same document `publishedDefinition`
+   * snapshots — and the flat half additionally removes `packageId` / `state` /
+   * `version` / `published*`, which are storage identity, never endpoint
+   * vocabulary. (What publish SNAPSHOTS is unchanged: `publishedDefinition`
+   * still stores `data.metadata ?? data` verbatim, envelope included, because
+   * `revertPackage` restores from it.) An item whose body does not satisfy
    * `ApiEndpointSchema` fails here too — not extra strictness but a
    * precondition: an unparsed shape cannot be gated, and it could never be
    * served either (the matcher's own loud skip refuses it at load).
@@ -2766,8 +2962,8 @@ var _MetadataManager = class _MetadataManager {
     const endpoints = [];
     const gatedItems = [];
     for (const item of apiItems) {
-      const document = item.data?.metadata ?? item.data;
-      const parsed = import_api3.ApiEndpointSchema.safeParse(document);
+      const { body } = peelStoredEnvelope(item.data);
+      const parsed = import_api3.ApiEndpointSchema.safeParse(body);
       if (!parsed.success) {
         for (const issue of parsed.error.issues) {
           errors.push({
@@ -2814,11 +3010,21 @@ var _MetadataManager = class _MetadataManager {
       }
     }
     if (packageItems.length === 0) {
-      throw new Error(`No metadata items found for package '${packageId}'`);
+      const err = new Error(
+        `No metadata items found for package '${packageId}'`
+      );
+      err.code = "RESOURCE_NOT_FOUND";
+      err.status = 404;
+      throw err;
     }
     const hasPublished = packageItems.some((item) => item.data.publishedDefinition !== void 0);
     if (!hasPublished) {
-      throw new Error(`Package '${packageId}' has never been published`);
+      const err = new Error(
+        `Package '${packageId}' has never been published`
+      );
+      err.code = "RESOURCE_CONFLICT";
+      err.status = 409;
+      throw err;
     }
     for (const item of packageItems) {
       if (item.data.publishedDefinition !== void 0) {
@@ -3071,6 +3277,7 @@ var _MetadataManager = class _MetadataManager {
    * @returns An unsubscribe function.
    */
   subscribe(type, callback) {
+    type = (0, import_core.canonicalMetadataServiceType)(type);
     this.addWatchCallback(type, callback);
     return () => this.removeWatchCallback(type, callback);
   }
@@ -4351,8 +4558,16 @@ var ARTIFACT_FIELD_TO_TYPE = {
   connectors: "connector",
   emailTemplates: "email_template",
   docs: "doc",
-  books: "book",
-  data: "dataset"
+  books: "book"
+  // `data:` (the SEED collection) is deliberately absent — #6242 row 4(a).
+  // It used to map to `'dataset'`, the ADR-0021 analytics kind: the exact name
+  // collision `metadata-plugin.zod.ts` warns about in prose. The entry never
+  // registered anything (SeedSchema declares no `name`, and the loop below
+  // skips nameless items) — a dead pointer aimed at the wrong kind, which
+  // would have begun mis-registering the day either side moved. Removed rather
+  // than repointed at `'seed'`: seeds are APPLIED by SeedLoaderService off the
+  // bundle, never registered as metadata items, so a `seed` mapping would be
+  // new behaviour rather than a corrected name.
 };
 var MetadataPlugin = class {
   constructor(options = {}) {