@objectstack/metadata 17.0.0-rc.2 → 17.0.0-rc.4

package/dist/index.js

@@ -173,6 +173,10 @@ import {
   MetadataEventType,
   MetadataEventSchema
 } from "@objectstack/spec/api";
+import {
+  ApiEndpointSchema as ApiEndpointSchema2,
+  validateApiEndpointDeclarations
+} from "@objectstack/spec/api";
 import { createLogger } from "@objectstack/core";
 
 // src/serializers/json-serializer.ts
@@ -1090,6 +1094,57 @@ var DatabaseLoader = class {
     };
   }
   // ==========================================
+  // Read-failure classification (#5108)
+  // ==========================================
+  /**
+   * Decide what a failed READ against {@link tableName} means, and rethrow
+   * unless it is the ONE benign reason.
+   *
+   * #5108 (rule from #4632; same shape as #4728 and #4825) — discriminate by
+   * error TYPE. Every read method below used to `catch {}` into its own empty
+   * value: `load` → `null`, `loadMany` → `[]`, `exists` → `false`, `stat` →
+   * `null`, `list` → `[]`. That made a database the metadata plane cannot
+   * reach **indistinguishable** from an environment where nothing of that type
+   * was ever declared — and it erased the failure *inside the loader*, so
+   * neither `MetadataManager`'s own `try/catch` degradation branches nor
+   * {@link import('../metadata-manager.js').MetadataManager.loadDiagnosed}
+   * (ADR-0110 D3, whose whole purpose is to tell a miss from an outage) could
+   * report anything. Nowhere on the chain was there a line saying the read
+   * failed.
+   *
+   * Why that is worse than a noisy error: every consumer that gates on a
+   * *declared set* — permissions, sharing rules, policies, endpoint
+   * declarations — reads the empty answer as "the author declared none". Some
+   * then fail open (grant), some fail closed (lock out); both look healthy
+   * from outside. This is the AGENTS.md → "Degradation log levels" shape the
+   * repo has already paid for twice, one layer up from #4825.
+   *
+   * Exactly one failure reason is benign: `sys_metadata` has not been
+   * provisioned yet. There are then genuinely no rows, so "nothing declared"
+   * IS the truth, and a first boot must not explode. Every other reason —
+   * connection drop, timeout, insufficient privileges, malformed query — means
+   * the rows may well be there and simply were not seen.
+   *
+   * Classification is conservative in the same direction as
+   * {@link isMissingTableError} itself: an unrecognised error is NOT benign.
+   * A false "benign" silently mis-answers a security question; a false "real"
+   * costs one loud error.
+   *
+   * @param error The value thrown by `_find` / `_findOne` / `_count`.
+   * @throws The underlying driver error, unchanged — deliberately, matching
+   *         {@link nextEventSeq}. The loader does not log it: the caller owns
+   *         the consequence and is the only layer that knows what an
+   *         incomplete answer costs it (`MetadataManager.list()` reports it at
+   *         `error`; `listForIndex()`/`matchEndpoint` let it propagate so an
+   *         outage can never be served as a 404).
+   * @returns normally ONLY for the benign case, licensing the caller to answer
+   *          with its empty value.
+   */
+  rethrowUnlessTableUnprovisioned(error) {
+    if (isMissingTableError(error)) return;
+    throw error;
+  }
+  // ==========================================
   // MetadataLoader Interface Implementation
   // ==========================================
   async load(type, name, _options) {
@@ -1128,7 +1183,8 @@ var DatabaseLoader = class {
         etag: record.checksum,
         loadTime: Date.now() - startTime
       };
-    } catch {
+    } catch (error) {
+      this.rethrowUnlessTableUnprovisioned(error);
       return {
         data: null,
         loadTime: Date.now() - startTime
@@ -1148,7 +1204,8 @@ var DatabaseLoader = class {
       const result = rows.map((row) => this.rowToData(row)).filter((data) => data !== null);
       this.loadManyCache?.set(type, result);
       return result;
-    } catch {
+    } catch (error) {
+      this.rethrowUnlessTableUnprovisioned(error);
       return [];
     }
   }
@@ -1163,7 +1220,8 @@ var DatabaseLoader = class {
         where: this.baseFilter(type, name)
       });
       return count > 0;
-    } catch {
+    } catch (error) {
+      this.rethrowUnlessTableUnprovisioned(error);
       return false;
     }
   }
@@ -1192,7 +1250,8 @@ var DatabaseLoader = class {
       };
       this.statCache?.set(key, stats);
       return stats;
-    } catch {
+    } catch (error) {
+      this.rethrowUnlessTableUnprovisioned(error);
       return null;
     }
   }
@@ -1210,7 +1269,8 @@ var DatabaseLoader = class {
       const names = rows.map((row) => row.name).filter((name) => typeof name === "string");
       this.listCache?.set(type, names);
       return names;
-    } catch {
+    } catch (error) {
+      this.rethrowUnlessTableUnprovisioned(error);
       return [];
     }
   }
@@ -1451,7 +1511,124 @@ function generateId() {
   return `meta_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
 }
 
+// src/endpoint-matcher.ts
+import {
+  ApiEndpointSchema,
+  identityFreeEndpointGateFailure,
+  normalizeEndpointPath
+} from "@objectstack/spec/api";
+function normalizeEndpointMethod(method) {
+  return String(method ?? "").toUpperCase();
+}
+function endpointIndexKey(method, path3) {
+  return `${normalizeEndpointMethod(method)} ${normalizeEndpointPath(path3)}`;
+}
+function buildEndpointIndex(items, logger) {
+  const index = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const parsed = ApiEndpointSchema.safeParse(item);
+    if (!parsed.success) {
+      const declaredName = item && typeof item === "object" && typeof item.name === "string" ? item.name : "<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,
+        { issues: parsed.error.issues }
+      );
+      continue;
+    }
+    const endpoint = parsed.data;
+    const gateFailure = identityFreeEndpointGateFailure(endpoint);
+    if (gateFailure) {
+      logger.error(
+        `[EndpointMatcher] stored api item '${endpoint.name}' was stored WITHOUT passing the endpoint publish gates (#5040 E7 / ADR-0121) \u2014 it is EXCLUDED from endpoint matching and its declared route will answer 404. Republish it through a gated path (a stack artifact, or \`publishPackage\` with the package's \`manifest.namespace\`); a direct metadata write is not a publish. Gate failure: ${gateFailure.message}`,
+        void 0,
+        { name: endpoint.name, issue: { path: gateFailure.path, message: gateFailure.message } }
+      );
+      continue;
+    }
+    const key = endpointIndexKey(endpoint.method, endpoint.path);
+    const incumbent = index.get(key);
+    if (!incumbent) {
+      index.set(key, endpoint);
+      continue;
+    }
+    const challengerWins = endpoint.name < incumbent.name;
+    const winner = challengerWins ? endpoint : incumbent;
+    const loser = challengerWins ? incumbent : endpoint;
+    if (challengerWins) index.set(key, endpoint);
+    logger.error(
+      `[EndpointMatcher] duplicate endpoint claim on '${key}': api items '${incumbent.name}' and '${endpoint.name}' both declare it. '${winner.name}' KEEPS the route and '${loser.name}' is IGNORED \u2014 the rule is lexicographically-first \`name\` wins, chosen so every node and every boot resolves it identically. Rename or repath '${loser.name}' to make it reachable.`,
+      void 0,
+      { key, winner: winner.name, ignored: loser.name }
+    );
+  }
+  return index;
+}
+var EndpointMatcher = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  /** Mark the index stale; the next {@link match} rebuilds it. */
+  invalidate() {
+    this.index = void 0;
+    this.building = void 0;
+  }
+  /**
+   * Resolve `method`+`path` to the owning declaration.
+   *
+   * @returns the parsed endpoint plus `params: {}`, or `undefined` on a miss.
+   * @throws whatever the store read threw — an outage is never a miss.
+   */
+  async match(query) {
+    const index = await this.ensureIndex();
+    const endpoint = index.get(endpointIndexKey(query.method, query.path));
+    if (!endpoint) return void 0;
+    return { endpoint, params: {} };
+  }
+  async ensureIndex() {
+    if (this.index) return this.index;
+    if (this.building) return this.building;
+    const build = (async () => {
+      const items = await this.deps.listApiItems();
+      return buildEndpointIndex(items, this.deps.logger);
+    })();
+    this.building = build;
+    try {
+      const built = await build;
+      if (this.building === build) {
+        this.index = built;
+        this.building = void 0;
+      }
+      return built;
+    } catch (error) {
+      if (this.building === build) this.building = void 0;
+      throw error;
+    }
+  }
+};
+
 // src/metadata-manager.ts
+var WRITABLE_LOADER_METHODS = ["save", "delete"];
+var WRITABLE_LOADER_METHOD_SIGNATURE = {
+  save: "save(type: string, name: string, data: any, options?: MetadataSaveOptions): Promise<MetadataSaveResult>",
+  delete: "delete(type: string, name: string): Promise<void>"
+};
+function buildWritableLoaderMissingMethodsMessage(loaderName, missing) {
+  const missingPhrase = missing.length === 2 ? "implements neither a `save()` nor a `delete()` method" : `implements no \`${missing[0]}()\` method`;
+  const consequences = missing.map(
+    (method) => method === "save" ? `Registered as-is, every write would be a silent lie: \`register()\` skips a loader that cannot save, then writes the in-memory registry, invalidates the list cache, announces a \`created\`/\`updated\` event and notifies watchers, so the caller (Studio/Setup, REST PUT, the CLI, a package publish) is told the write succeeded while nothing ever reaches \`${loaderName}\` \u2014 the item reads back correctly for the life of this process and is gone at the next restart, with nothing to retry it. ` : `Registered as-is, every deletion would be a silent lie: \`unregister()\` skips a loader that cannot delete, then drops the registry entry, invalidates the list cache and announces a \`deleted\` event, so the caller (Studio/Setup, REST DELETE, the CLI, a package teardown) is told the delete succeeded while the row stays in \`${loaderName}\` and is read straight back out by the very next \`list()\`/\`get()\` \u2014 across restarts, with nothing to retry it. `
+  );
+  const repair = missing.map((method) => `\`${WRITABLE_LOADER_METHOD_SIGNATURE[method]}\``).join(" and ");
+  return `[MetadataManager] Refusing to register metadata loader \`${loaderName}\`: it declares \`protocol: 'datasource:'\` with \`capabilities.write: true\` but ${missingPhrase}. A write-capable datasource loader is written to AND deleted from \u2014 \`register()\` persists every item into it, and \`unregister()\` has to take those rows back out again. ` + consequences.join("") + `Fix: either implement ${repair} on \`${loaderName}\` (\`DatabaseLoader\` in this package is the reference implementation), or, if the loader is genuinely read-only, declare \`capabilities.write: false\` \u2014 a read-only \`datasource:\` loader registers without complaint and is never written to in the first place.`;
+}
+function assertWritableLoaderContract(loader) {
+  const { name, protocol, capabilities } = loader.contract;
+  if (protocol !== "datasource:" || capabilities.write !== true) return;
+  const missing = WRITABLE_LOADER_METHODS.filter((method) => typeof loader[method] !== "function");
+  if (missing.length === 0) return;
+  throw new Error(buildWritableLoaderMissingMethodsMessage(name, missing));
+}
+var PUBLISH_NAMESPACE_REMEDY = "From `MetadataManager.publishPackage` specifically: this method indexes items by `packageId` and carries no manifest, so it cannot prove a namespace on its own and will not infer one from the items being published (an author-supplied value would make the carve-out gate vacuous). Pass the package's explicit namespace as `publishPackage(id, { namespace })`, or publish the endpoints as part of a stack artifact (`defineStack` \u2192 compile \u2192 artifact ingest), which carries the manifest and runs these same gates at parse time.";
 function generateEventUuid() {
   const c = globalThis.crypto;
   if (c && typeof c.randomUUID === "function") {
@@ -1482,14 +1659,127 @@ var _MetadataManager = class _MetadataManager {
     // acquire a fresh knex connection while the transaction is still holding
     // SQLite's single connection — knex waits the full `acquireConnectionTimeout`
     // (60s) before returning []. The cache absorbs the repeated lookups so the
-    // loader is only hit once per TTL window.
+    // loader is only hit once per TTL window — for CONCURRENT callers as well as
+    // sequential ones, since #5253. The cache on its own could only ever deliver
+    // the sequential half of that promise: nothing is written until a read
+    // completes, so everything issued before the first read returned used to miss
+    // and walk every loader — N callers, N × 60s on the very stall described
+    // 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] WHAT IS ACTUALLY CACHED, AND FOR HOW LONG — this paragraph is the
+    // contract, and it describes `cacheListResult()` / `readCachedList()` below.
+    // (An earlier version of this comment claimed the cache kept "only positive
+    // (non-empty) hits or repeated hits with a stable miss signature". No such
+    // condition ever existed in the code. Comment is contract; a comment that
+    // describes a policy nothing implements is a declared ≠ enforced defect in
+    // its own right, so it is replaced rather than patched.)
+    //
+    //   • EVERY completed `list()` is cached, empty results included. There is
+    //     no non-empty test and no "miss signature" concept.
+    //   • An entry assembled while at least one loader THREW is a known-partial
+    //     answer: it is cached with `degraded: true` and expires after
+    //     `DEGRADED_LIST_CACHE_TTL_MS`, not `LIST_CACHE_TTL_MS`. So the burst of
+    //     repeated lookups the knex path above depends on is still absorbed,
+    //     while the window in which the manager serves a known-short set without
+    //     re-asking anyone shrinks from 30s to ~2s. Recovery is therefore also
+    //     noticed (and `reportLoaderReadRecovered` logged) within ~2s of storage
+    //     healing instead of up to 30s later.
+    //   • `degraded` lives ON the entry, not in a side table, so every consumer
+    //     of the cache can tell a complete answer from a partial one. Read
+    //     entries through `readCachedList()` rather than `listCache.get()`, so
+    //     the flag and its TTL are applied in one place.
     //
     // Invalidated on every `register()` / `unregister()` to keep CRUD writes
     // visible to subsequent reads.
+    //
+    // [#5259] WHERE in a write the invalidation sits is part of that promise, not
+    // an implementation detail. `list()` merges registry ∪ loaders, so an
+    // invalidation issued while only ONE of the two has been updated lets the
+    // next read memoize the half-applied view for a full TTL. The rule both
+    // writers follow: **invalidate last, once every store already holds the state
+    // being announced** — `register()` satisfies it by writing the registry
+    // first (the registry outranks loaders in the merge, so its save window
+    // already shows the post-write value); `unregister()` satisfies it by
+    // deleting from storage first and invalidating after, with nothing awaited
+    // between the registry drop and the invalidation. See `unregister()`.
     this.listCache = /* @__PURE__ */ new Map();
+    /**
+     * [#5253] The `list()` read currently in flight for a metadata type — the
+     * concurrent half of the `listCache` policy above.
+     *
+     * `listCache` memoizes an answer only once a read has *finished*, so it can
+     * absorb the caller that arrives second in time but never the caller that
+     * arrives second in flight. Everything issued while the first read is still
+     * walking the loaders used to miss and start its own identical walk; on the
+     * knex/SQLite path the field comment above is built for, that is 60s burned
+     * per concurrent caller instead of once for all of them. A type is read once
+     * at a time: whoever finds a read already running joins it.
+     *
+     * **Sharers share the outcome. This is a contract, not an accident.** Every
+     * caller joining an in-flight read receives that read's exact result — the
+     * same array instance, and, when a loader was unreadable, the same
+     * known-partial set that gets memoized `degraded: true` on the short TTL.
+     * There is no per-caller retry: `list()` is the best-effort listing seam and
+     * does not throw (see {@link reportLoaderReadFailure}; the strict
+     * counterparts are `listForIndex()` and {@link loadDiagnosed}), so a lost
+     * loader is not an error to fail over from — it is the answer. Re-running the
+     * read privately for a joiner would walk the same loaders in the same window
+     * against the same outage, which is precisely what this map exists to
+     * prevent. Should the seam ever acquire a rejecting path, that rejection is
+     * shared by the same mechanism and for the same reason.
+     *
+     * **The registration is also the permission to cache.** An entry here says
+     * "this read still describes the current state". {@link invalidateListCache}
+     * retracts it, which is what makes a write landing mid-read safe in both
+     * directions:
+     *   • the retracted read does NOT write its result into `listCache` when it
+     *     settles, so an answer assembled before the write cannot outlive the
+     *     write it predates (the invalidation wins — it is the later, better
+     *     informed fact);
+     *   • a `list()` issued after the invalidation starts a FRESH read instead of
+     *     joining one that predates the write.
+     * That second point is the #5219 / #5229 ordering bar restated for
+     * concurrency: a consumer woken by a metadata change must not observe the
+     * event and pre-event state together, and handing a woken watcher an
+     * in-flight read that began before the event would be exactly that.
+     * Callers *already waiting* on the retracted read still receive its (now
+     * possibly stale) result — they asked before the write, and restarting the
+     * read under them would turn a write burst into an unbounded retry loop on
+     * the one path the cache exists to keep off the loaders.
+     *
+     * Self-cleaning: the entry is dropped when the read settles, by that read
+     * 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.
+     */
+    this.inflightListReads = /* @__PURE__ */ new Map();
+    // [#5108] Loader names whose read failure has already been reported at
+    // `error` by `list()`. AGENTS.md → "Degradation log levels": say it once, at
+    // the first degradation — `list()` is hot enough that one line per failed
+    // read would bury the one line that matters. Cleared when the loader answers
+    // again, so a second outage is reported again. Same once-only discipline as
+    // `DatabaseLoader.schemaFailureReported`.
+    this.loaderReadFailureReported = /* @__PURE__ */ new Set();
     this.repoWatchClosed = false;
     this.config = config;
     this.logger = createLogger({ level: "info", format: "pretty" });
+    this.endpointMatcher = new EndpointMatcher({
+      listApiItems: () => this.listForIndex(_MetadataManager.ENDPOINT_METADATA_TYPE),
+      logger: this.logger
+    });
+    this.subscribe(_MetadataManager.ENDPOINT_METADATA_TYPE, () => this.endpointMatcher.invalidate());
     this.serializers = /* @__PURE__ */ new Map();
     const formats = config.formats || ["typescript", "json", "yaml"];
     if (formats.includes("json")) {
@@ -1639,8 +1929,16 @@ var _MetadataManager = class _MetadataManager {
   }
   /**
    * Register a new metadata loader (data source)
+   *
+   * [#5276, #5654] Rejects — loudly, before the loader is stored — a
+   * `datasource:` loader that declares `capabilities.write` without
+   * implementing `save()` **and** `delete()`. This is the **only** way into
+   * `this.loaders` (the constructor's `config.loaders` come through here too),
+   * which is what lets every later write-capability guard be defensive rather
+   * than load-bearing.
    */
   registerLoader(loader) {
+    assertWritableLoaderContract(loader);
     this.loaders.set(loader.contract.name, loader);
     this.logger.info(`Registered metadata loader: ${loader.contract.name} (${loader.contract.protocol})`);
   }
@@ -1676,9 +1974,9 @@ var _MetadataManager = class _MetadataManager {
     this.registry.get(type).set(name, data);
     this.invalidateListCache(type);
     for (const loader of this.loaders.values()) {
-      if (loader.save && loader.contract.protocol === "datasource:" && loader.contract.capabilities.write) {
-        await loader.save(type, name, data);
-      }
+      if (loader.contract.protocol !== "datasource:" || !loader.contract.capabilities.write) continue;
+      if (typeof loader.save !== "function") continue;
+      await loader.save(type, name, data);
     }
     await this.publishRealtimeMetadataEvent(existed ? "updated" : "created", type, name, {
       definition: data,
@@ -1722,6 +2020,23 @@ var _MetadataManager = class _MetadataManager {
   /**
    * Get a metadata item by type and name.
    * Checks in-memory registry first, then falls back to loaders.
+   *
+   * Returns `undefined` both when nothing declares the item and when every
+   * loader that could have held it FAILED — see {@link getDiagnosed} when the
+   * caller must tell those apart. This is the same relationship {@link load}
+   * 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`.
    */
   async get(type, name) {
     const typeStore = this.registry.get(type);
@@ -1732,13 +2047,85 @@ var _MetadataManager = class _MetadataManager {
     return result ?? void 0;
   }
   /**
-   * List all metadata items of a given type
+   * `get`, plus whether the answer can be trusted as complete.
+   *
+   * [#5840] {@link loadDiagnosed} already computes this verdict — and `get()`
+   * threw it away two hops later (`load` kept only `.data`, `get` turned that
+   * `null` into `undefined`), so no caller of `get` could reach the one fact
+   * ADR-0110 D3 exists to preserve: **a miss and an outage are different facts
+   * with opposite security meanings.** A consumer that gates on a declaration
+   * MUST NOT read `undefined` as "the author declared nothing" — an
+   * availability failure would silently widen access (the REST `/actions`
+   * fail-open branch, #3935) or make a positive claim about authorship from a
+   * read that never happened (`code: null` in the layered read, #5707/#5532).
+   *
+   * This is the registry-first counterpart of {@link loadDiagnosed}, and that
+   * difference is why callers of `get` cannot simply switch to `loadDiagnosed`:
+   * doing so would skip the in-memory registry and change what they resolve.
+   *
+   * `degraded` is true when at least one loader threw AND nothing answered with
+   * the item — never when the in-memory registry answered, because that answer
+   * needed no loader. A clean miss (every loader answered, none had it) is NOT
+   * degraded. The posture is deliberately conservative: with a loader down we
+   * cannot prove the item is absent, so we decline to claim it is.
+   */
+  async getDiagnosed(type, name) {
+    const typeStore = this.registry.get(type);
+    if (typeStore?.has(name)) {
+      return { data: typeStore.get(name), degraded: false, errors: [] };
+    }
+    const { data, degraded, errors } = await this.loadDiagnosed(type, name);
+    return { data: data ?? void 0, degraded, errors };
+  }
+  /**
+   * List all metadata items of a given type.
+   *
+   * Best-effort by contract: a loader that cannot be read is reported once and
+   * skipped ({@link reportLoaderReadFailure}), so this resolves with what the
+   * reachable loaders hold rather than throwing.
+   *
+   * [#5253] Reads of one type are single-flight — concurrent callers join the
+   * read already running instead of each walking every loader. What they are
+   * promised, and what happens when a write lands mid-read, is the contract on
+   * `inflightListReads`; what is memoized afterwards is the contract on
+   * `listCache`.
    */
   async list(type) {
-    const cached = this.listCache.get(type);
-    if (cached && Date.now() - cached.ts < _MetadataManager.LIST_CACHE_TTL_MS) {
+    const cached = this.readCachedList(type);
+    if (cached) {
       return cached.items;
     }
+    const joined = this.inflightListReads.get(type);
+    if (joined) {
+      return joined;
+    }
+    const shared = this.readListUncached(type).then(({ items, degraded }) => {
+      if (this.inflightListReads.get(type) === shared) {
+        this.cacheListResult(type, items, degraded);
+      }
+      return items;
+    });
+    this.inflightListReads.set(type, shared);
+    try {
+      return await shared;
+    } finally {
+      if (this.inflightListReads.get(type) === shared) {
+        this.inflightListReads.delete(type);
+      }
+    }
+  }
+  /**
+   * Assemble the `list()` answer for `type` from the in-memory registry plus
+   * every loader, reporting (but not rethrowing) loaders that could not be
+   * read.
+   *
+   * The body {@link list} used to inline, extracted so the caching and
+   * single-flight bookkeeping around it has one thing to run at most once per
+   * type (#5253). Deliberately does NOT touch `listCache` itself: whether this
+   * result may be memoized depends on what happened to the read's registration
+   * while it ran, which only `list()` can see.
+   */
+  async readListUncached(type) {
     const items = /* @__PURE__ */ new Map();
     const typeStore = this.registry.get(type);
     if (typeStore) {
@@ -1746,6 +2133,7 @@ var _MetadataManager = class _MetadataManager {
         items.set(name, data);
       }
     }
+    let degraded = false;
     for (const loader of this.loaders.values()) {
       try {
         const loaderItems = await loader.loadMany(type);
@@ -1755,20 +2143,161 @@ var _MetadataManager = class _MetadataManager {
             items.set(itemAny.name, item);
           }
         }
+        this.reportLoaderReadRecovered(loader.contract.name);
       } catch (e) {
-        this.logger.warn(`Loader ${loader.contract.name} failed to loadMany ${type}`, { error: e });
+        degraded = true;
+        this.reportLoaderReadFailure(loader.contract.name, type, e);
       }
     }
-    const result = Array.from(items.values());
-    this.cacheListResult(type, result);
-    return result;
+    return { items: Array.from(items.values()), degraded };
   }
-  cacheListResult(type, items) {
-    this.listCache.set(type, { ts: Date.now(), items });
+  /**
+   * Report — at `error`, once per outage episode — that a loader could not be
+   * read while serving {@link list}.
+   *
+   * [#5108] This branch used to be dead for the loader that matters. Before
+   * #5108 `DatabaseLoader` caught its own read failures and answered `[]`, so
+   * `list()` received a *successful empty read* and never entered this `catch`
+   * at all: an unreachable `sys_metadata` and "this environment declares no
+   * `permission`" produced byte-identical results with not one line logged.
+   * With the loader rethrowing everything but the benign not-provisioned case,
+   * this is where the outage finally becomes speakable.
+   *
+   * `error`, not `warn`, per AGENTS.md → "Degradation log levels". Apply its
+   * one question — *does the system still look normal from outside while
+   * something it claims to know has not actually landed?* — and the answer is
+   * yes: `list()` still returns, callers still get an array, nothing 500s, and
+   * the set they gate on is quietly short. Which way that cuts depends on the
+   * consumer, and both ways are silent (#3935 is the fail-open precedent).
+   *
+   * Said **once** per loader, and un-said on recovery, because `list()` is a
+   * hot path — one line per outage, not one per read.
+   *
+   * [#5184] The once-only guard carries more weight than it used to: a
+   * degraded `list()` result is now memoized for `DEGRADED_LIST_CACHE_TTL_MS`
+   * rather than `LIST_CACHE_TTL_MS`, so during an outage the loader is
+   * re-asked (and this method re-entered) roughly every 2s instead of every
+   * 30s. That is the point — the outage stops being a 30s silent window and
+   * recovery is noticed within seconds — and it costs nothing in log volume
+   * precisely because `loaderReadFailureReported` still speaks only once.
+   *
+   * Deliberately does NOT rethrow: `list()` is the best-effort listing seam and
+   * must keep serving what the reachable loaders hold. The strict counterpart
+   * for callers whose answer is a security decision is `listForIndex()` (no
+   * `catch`, feeding `matchEndpoint`) and {@link loadDiagnosed} (ADR-0110 D3)
+   * for the singular read — both of which only became honest for
+   * `DatabaseLoader` with the same #5108 change.
+   */
+  reportLoaderReadFailure(loaderName, type, error) {
+    if (this.loaderReadFailureReported.has(loaderName)) return;
+    this.loaderReadFailureReported.add(loaderName);
+    this.logger.error(
+      `[MetadataManager] Loader \`${loaderName}\` could NOT be read (first failure seen while listing \`${type}\`) \u2014 every list served from now on is a PARTIAL set presented as a complete one, and the server keeps reporting healthy. Consumers that gate on a declared set (permissions, sharing rules, policies, api endpoints) will read the declarations this loader holds as "never declared" \u2014 which grants or locks out depending on the consumer, silently either way. Fix: check the datasource behind \`${loaderName}\` \u2014 connection, credentials, and that its metadata table exists. The read is retried on the next list once the ${_MetadataManager.DEGRADED_LIST_CACHE_TTL_MS}ms degraded-result list cache lapses (a known-partial listing is memoized far more briefly than a complete one \u2014 #5184), so a transient cause recovers on its own within seconds and the recovery is logged.`,
+      error instanceof Error ? error : void 0,
+      { loader: loaderName, type, error }
+    );
   }
-  /** Internal helper: drop the cached `list()` result for a type. */
+  /** Un-say {@link reportLoaderReadFailure} once the loader answers again. */
+  reportLoaderReadRecovered(loaderName) {
+    if (!this.loaderReadFailureReported.delete(loaderName)) return;
+    this.logger.info(
+      `[MetadataManager] Loader \`${loaderName}\` is readable again \u2014 listings are complete once more.`
+    );
+  }
+  /**
+   * Memoize a completed {@link list} result.
+   *
+   * [#5184] `degraded` is not optional at the call site by accident — it is the
+   * 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.
+   */
+  cacheListResult(type, items, degraded) {
+    this.listCache.set(type, { ts: Date.now(), items, degraded });
+  }
+  /**
+   * Read a still-fresh {@link listCache} entry, or `undefined` when there is
+   * none / it has expired.
+   *
+   * [#5184] The single place the TTL policy is applied, so "a degraded entry
+   * expires sooner" cannot be forgotten by a second reader. Returns the whole
+   * entry rather than just `items` so callers keep access to `degraded`.
+   */
+  readCachedList(type) {
+    const cached = this.listCache.get(type);
+    if (!cached) return void 0;
+    const ttl = cached.degraded ? _MetadataManager.DEGRADED_LIST_CACHE_TTL_MS : _MetadataManager.LIST_CACHE_TTL_MS;
+    return Date.now() - cached.ts < ttl ? cached : void 0;
+  }
+  /**
+   * Internal helper: drop every memoized or in-progress `list()` answer for a
+   * type, so the next read observes the write that called this.
+   *
+   * [#5253] Retracting the in-flight read (not just the finished entry) is the
+   * whole mid-read story, and it is pinned by test: the read keeps running for
+   * the callers already waiting on it, but it loses the right to memoize its
+   * pre-write answer, and a caller arriving after this point gets a fresh read
+   * instead of joining a pre-write one. The reasoning — including why waiting
+   * callers are NOT restarted — is on the `inflightListReads` field.
+   *
+   * [#5259] Both halves are only as good as WHEN the caller invokes this. This
+   * clears what is stale *as of now*; it cannot pre-empt a store the caller has
+   * not finished updating yet. Callers must therefore invalidate only once
+   * every store already holds the state they are about to announce — see the
+   * `listCache` field comment and {@link unregister}, whose pre-#5259 ordering
+   * invalidated one await too early and let the next read cache a view in which
+   * the registry was empty and the loader was not.
+   */
   invalidateListCache(type) {
     this.listCache.delete(type);
+    this.inflightListReads.delete(type);
+    if (type === _MetadataManager.ENDPOINT_METADATA_TYPE) {
+      this.endpointMatcher.invalidate();
+    }
+  }
+  /**
+   * Enumerate stored items of `type` for an index build — like {@link list},
+   * but a store that cannot be read THROWS instead of contributing nothing.
+   *
+   * [#5089] `list()` deliberately logs a failing loader and skips it so a
+   * partially-available metadata plane still serves what it can. That posture
+   * is wrong for `matchEndpoint`: its `undefined` becomes an HTTP 404, and a
+   * store outage that silently yields "zero declarations" would turn every
+   * declared endpoint into a semantic "nothing declares this route". Same
+   * distinction {@link loadDiagnosed} draws on the singular read (ADR-0110
+   * D3) — a miss and an outage are different facts with opposite meanings.
+   *
+   * Deliberately private and single-purpose: it is not a second `list()`, it
+   * is `list()`'s failure posture inverted for the one caller whose answer is
+   * a security/availability decision rather than a best-effort listing.
+   *
+   * This surfaces only failures a loader actually reports — which, since
+   * #5108, includes `DatabaseLoader`: it used to swallow its own read errors
+   * into `[]`, making a DB outage invisible even here. It now rethrows every
+   * read failure except the benign "table not provisioned yet", so this seam
+   * holds against the real datasource-backed loader and not just the memory /
+   * remote ones. (`database-loader.test.ts` pins that end to end: a broken
+   * driver behind a real `DatabaseLoader` makes `matchEndpoint` reject rather
+   * than answer a 404-shaped `undefined`.)
+   */
+  async listForIndex(type) {
+    const items = /* @__PURE__ */ new Map();
+    const typeStore = this.registry.get(type);
+    if (typeStore) {
+      for (const [name, data] of typeStore) {
+        items.set(name, data);
+      }
+    }
+    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);
+        }
+      }
+    }
+    return Array.from(items.values());
   }
   /**
    * Unregister/remove a metadata item by type and name.
@@ -1778,8 +2307,74 @@ var _MetadataManager = class _MetadataManager {
    * {@link MetadataWatchEvent} — the delete half of the {@link register}
    * contract. Pass `{ notify: false }` only for teardown that announces by
    * other means.
+   *
+   * ## [#5259] Storage FIRST, in-memory second — the order is the fix
+   *
+   * This method used to drop the registry entry and call
+   * {@link invalidateListCache} *before* awaiting `loader.delete()`. Those two
+   * steps are separated by a real await window (one DB round-trip per writable
+   * loader), and inside it the manager was in a state that exists nowhere else:
+   * **registry already empty, loader not yet empty**. `list()` merges the two,
+   * so a read arriving in that window
+   *
+   *   • missed the cache (it had just been invalidated),
+   *   • assembled the still-stored row into its answer, and
+   *   • memoized that answer as a COMPLETE read — the full 30s healthy TTL,
+   *     because no loader threw, so #5184's 2s degraded TTL never applied.
+   *
+   * Nothing invalidated again afterwards ({@link notifyWatchers} does not touch
+   * `listCache`), so a row that was gone from storage kept being enumerated for
+   * up to 30s — and `get()`, which never consulted that cache, disagreed with
+   * `list()` the whole time. For a gating type (`permission`, `api`) the two
+   * faces of the same manager answered opposite questions about whether a
+   * declaration exists.
+   *
+   * {@link register} never had this defect, and the reason is instructive: it
+   * writes the registry *first*, and the registry outranks every loader in the
+   * merge, so throughout its own save window the merged view already equals the
+   * post-write state. The invariant that makes register correct is not "where
+   * the invalidate sits" but **the invalidate must be the last thing after
+   * every store already holds the announced state**. Restated for delete, that
+   * means storage first:
+   *
+   *   1. `await loader.delete()` on every writable loader. Throughout this
+   *      window registry AND loaders still hold the item, so a concurrent
+   *      `list()` observes a coherent pre-delete state — which is the truth,
+   *      because the delete has not landed and has not been announced.
+   *   2. Drop the registry entry and `invalidateListCache(type)` — with **no
+   *      await between them**, so no read can interleave and observe the
+   *      half-applied state that produced the bug. Everything cached or
+   *      in-flight from step 1 is dropped here, at the moment the final state
+   *      becomes true.
+   *   3. Publish + announce. #5219's invalidate-before-notify bar, unchanged:
+   *      a watcher woken by the `deleted` event and re-reading through `list()`
+   *      gets a fresh read of the post-delete state.
+   *
+   * **Composition with #5253's single-flight (this is the load-bearing half).**
+   * A `list()` that is still walking the loaders when step 2 runs cannot be
+   * fixed by dropping `listCache` alone — it has not written its entry yet, and
+   * it would write the pre-delete answer *after* the invalidation. The
+   * mechanism that covers it is `invalidateListCache()` also retracting the
+   * read's registration in `inflightListReads`: a retracted read still resolves
+   * for the callers already waiting on it (they asked before the delete) but
+   * loses the right to memoize, and any caller arriving after step 2 starts a
+   * fresh read rather than joining the pre-delete one. So every read is
+   * covered: one that FINISHED in the window has its entry deleted, one still
+   * IN FLIGHT loses its permission to cache, and one starting later reads the
+   * post-delete state. That is why the invalidate must come after the deletes
+   * rather than being duplicated on both sides of them — a second invalidate
+   * before the await would buy nothing and would re-open step 1's window.
    */
   async unregister(type, name, options) {
+    for (const loader of this.loaders.values()) {
+      if (loader.contract.protocol !== "datasource:" || !loader.contract.capabilities.write) continue;
+      if (typeof loader.delete !== "function") continue;
+      try {
+        await this.deleteMetaItemFromLoader(loader, type, name);
+      } catch (error) {
+        this.reportMetaItemDeleteFailure(loader.contract.name, type, name, error);
+      }
+    }
     const typeStore = this.registry.get(type);
     if (typeStore) {
       typeStore.delete(name);
@@ -1788,16 +2383,6 @@ var _MetadataManager = class _MetadataManager {
       }
     }
     this.invalidateListCache(type);
-    for (const loader of this.loaders.values()) {
-      if (loader.contract.protocol !== "datasource:" || !loader.contract.capabilities.write) continue;
-      if (typeof loader.delete === "function") {
-        try {
-          await loader.delete(type, name);
-        } catch (error) {
-          this.logger.warn(`Failed to delete ${type}/${name} from loader ${loader.contract.name}`, { error });
-        }
-      }
-    }
     await this.publishRealtimeMetadataEvent("deleted", type, name, {
       userId: options?.userId
     });
@@ -1812,6 +2397,73 @@ var _MetadataManager = class _MetadataManager {
       });
     }
   }
+  /**
+   * Delete one metadata item from one writable loader — the storage half of
+   * {@link unregister}.
+   *
+   * A one-line wrapper on purpose: it gives this durability seam a **name**.
+   * `check:durability-log-level` matches by callee name against an explicit
+   * vocabulary, and the raw call is `loader.delete(...)` — putting `delete` in
+   * that vocabulary would claim every `.delete()` in the monorepo (`Map`,
+   * `Set`, cache handles, `URLSearchParams`) and the gate would drown in false
+   * positives, which is exactly the failure mode its own header warns about.
+   * Named here, `deleteMetaItemFromLoader` is in `DURABILITY_CRITICAL_CALLEES`
+   * with a blast radius of precisely this call site, mirroring `saveMetaItem`
+   * on the write side (#4754).
+   *
+   * [#5276] `MetadataLoader` now declares `delete?`, so no cast is left here.
+   * It stays *optional* on the interface — `file:`/`memory:`/`http:`/`s3:`
+   * loaders legitimately have none — and the guard below is therefore a type
+   * narrowing rather than a policy decision. The policy lives at
+   * `registerLoader()`: a `datasource:` loader that declares
+   * `capabilities.write` cannot be registered without a `delete()`, which is
+   * exactly the set of loaders this method is ever called for.
+   */
+  async deleteMetaItemFromLoader(loader, type, name) {
+    const del = loader.delete;
+    if (typeof del !== "function") return;
+    await del.call(loader, type, name);
+  }
+  /**
+   * Report — at `error` — that a loader refused to delete an item the runtime
+   * has already dropped and announced as deleted.
+   *
+   * [#5259] This used to be a `logger.warn('Failed to delete …')` and continue.
+   * AGENTS.md → "Degradation log levels" decides the level with one question:
+   * *after the degradation, does the system still look normal from the outside
+   * while something it claims is persisted has not actually landed?* Here it is
+   * the deletion that did not land, which is the same class and the same
+   * silence: `unregister()` resolves normally, the caller is told the delete
+   * succeeded, and the surviving row is read straight back out of storage —
+   * permanently, since nothing ever retries this. Durability/consistency
+   * degradation ⇒ `error`, naming the **consequence** and the **fix**.
+   *
+   * **Why the registry entry is still dropped when this fires.** The
+   * alternative — keep the item registered so runtime state matches storage —
+   * looks safer and is not. The loader still holds the row, and `list()`/`get()`
+   * merge registry ∪ loaders, so the item is served either way; the only thing
+   * the surviving registry entry would change is *which copy wins*, pinning an
+   * in-memory definition that outranks the stored row nobody is maintaining
+   * anymore. Dropping it makes the very next read fall through to storage,
+   * which is the actual truth after a failed delete — the item still exists —
+   * and it surfaces that immediately (the item visibly reappears) instead of at
+   * the next restart. One truth, read from where it lives; the divergence is
+   * reported here rather than papered over with a second in-memory copy.
+   *
+   * **Said once per un-deleted item, not once per loader.** The once-per-outage
+   * discipline of {@link reportLoaderReadFailure} exists because `list()` is hot
+   * and its repeats are *identical*; these are not. Each line names a different
+   * item that is still in storage and that nothing will ever retry, so
+   * collapsing them would hand an operator the first casualty and silently drop
+   * the rest of the list — the failure this level was raised to prevent.
+   */
+  reportMetaItemDeleteFailure(loaderName, type, name, error) {
+    this.logger.error(
+      `[MetadataManager] Loader \`${loaderName}\` could NOT delete \`${type}/${name}\` \u2014 the row is STILL in its store, while the runtime has already dropped the item from its registry and announced it as deleted. Nothing looks broken: \`unregister()\` resolves normally and the caller (Studio/Setup, REST DELETE, the CLI, a package teardown) is told the delete succeeded \u2014 but the surviving row is read straight back out of storage by the very next \`list()\`/\`get()\`, so the "deleted" item reappears and keeps reappearing across restarts. Nothing retries this delete. Fix: check the datasource behind \`${loaderName}\` \u2014 connection, credentials, and that its metadata table exists and is writable \u2014 then re-issue the delete for \`${type}/${name}\`. Until that succeeds the item is NOT deleted, whatever the delete call reported.`,
+      error instanceof Error ? error : void 0,
+      { loader: loaderName, type, name, error }
+    );
+  }
   /**
    * Check if a metadata item exists
    */
@@ -1932,6 +2584,12 @@ var _MetadataManager = class _MetadataManager {
    * 2. Snapshot all items in the package (publishedDefinition = clone(metadata))
    * 3. Increment version
    * 4. Set all items state → active
+   *
+   * [#5189, #5040 E7b] Step 1 additionally runs the **endpoint publish gates**
+   * over every `api` item — see {@link gateApiItemsForPublish}. That pass is
+   * NOT governed by `options.validate`: the gates are a contract, not a
+   * lint (ADR-0121 D6 says publish REJECTS an unmetered anonymous endpoint),
+   * and an opt-out flag on a security gate is the bypass this issue closed.
    */
   async publishPackage(packageId, options) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1956,8 +2614,9 @@ var _MetadataManager = class _MetadataManager {
         validationErrors: [{ type: "", name: "", message: `No metadata items found for package '${packageId}'` }]
       };
     }
+    const validationErrors = [];
+    validationErrors.push(...this.gateApiItemsForPublish(packageItems, options?.namespace));
     if (shouldValidate) {
-      const validationErrors = [];
       for (const item of packageItems) {
         const result = await this.validate(item.type, item.data);
         if (!result.valid && result.errors) {
@@ -1995,16 +2654,16 @@ var _MetadataManager = class _MetadataManager {
           }
         }
       }
-      if (validationErrors.length > 0) {
-        return {
-          success: false,
-          packageId,
-          version: 0,
-          publishedAt: now,
-          itemsPublished: 0,
-          validationErrors
-        };
-      }
+    }
+    if (validationErrors.length > 0) {
+      return {
+        success: false,
+        packageId,
+        version: 0,
+        publishedAt: now,
+        itemsPublished: 0,
+        validationErrors
+      };
     }
     let maxVersion = 0;
     for (const item of packageItems) {
@@ -2031,6 +2690,82 @@ var _MetadataManager = class _MetadataManager {
       itemsPublished: packageItems.length
     };
   }
+  /**
+   * [#5189, #5040 E7b] Run the endpoint publish gates over a package's `api`
+   * items and report every failure as a publish-blocking validation error.
+   *
+   * ## Why this exists at all
+   *
+   * E7 (#5111) hung the five per-endpoint gates on
+   * `ObjectStackDefinitionSchema`, which covers every path that parses a
+   * STACK — `defineStack`, `os validate`, the lint scorer, artifact ingest,
+   * `EnvironmentArtifactSchema.metadata`. It does not cover this one: an `api`
+   * item can be minted item-by-item (`metadata.register()`, a Studio write)
+   * and published here without a stack ever being parsed. Three of the gates
+   * degrade safely when bypassed (the executor answers a structured 501; a
+   * mis-namespaced path matches nothing), but **ADR-0121 D6 has no runtime
+   * counterpart**: `authRequired: false` is honoured faithfully and an
+   * unarmed `rateLimit` meters nothing, so the bypass mints an anonymous,
+   * zero-quota execution entry point. Hence a gate here, on the same
+   * function, rather than a second set of criteria that would drift.
+   *
+   * ## 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
+   * `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).
+   *
+   * @param packageItems every item collected for this package (all types).
+   * @param namespace the caller-supplied `manifest.namespace`; `undefined`
+   *   fails the namespace gate, deliberately — see `publishPackage`'s option.
+   * @returns one entry per gate failure, `[]` when the package declares no
+   *   `api` items (a package without endpoints is untouched by this pass).
+   */
+  gateApiItemsForPublish(packageItems, namespace) {
+    const apiItems = packageItems.filter((i) => i.type === _MetadataManager.ENDPOINT_METADATA_TYPE);
+    if (apiItems.length === 0) return [];
+    const errors = [];
+    const endpoints = [];
+    const gatedItems = [];
+    for (const item of apiItems) {
+      const document = item.data?.metadata ?? item.data;
+      const parsed = ApiEndpointSchema2.safeParse(document);
+      if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+          errors.push({
+            type: item.type,
+            name: item.name,
+            message: `api item '${item.name}' does not satisfy ApiEndpointSchema and cannot be published: ${issue.message} (at ${issue.path.join(".") || "<root>"}). An endpoint that does not parse cannot be gated and would be excluded from endpoint matching at load anyway.`
+          });
+        }
+        continue;
+      }
+      endpoints.push(parsed.data);
+      gatedItems.push({ name: item.name });
+    }
+    for (const issue of validateApiEndpointDeclarations(endpoints, { namespace })) {
+      const index = typeof issue.path[1] === "number" ? issue.path[1] : void 0;
+      if (index === void 0) {
+        errors.push({
+          type: _MetadataManager.ENDPOINT_METADATA_TYPE,
+          name: "",
+          message: `${issue.message} ${PUBLISH_NAMESPACE_REMEDY}`
+        });
+        continue;
+      }
+      errors.push({
+        type: _MetadataManager.ENDPOINT_METADATA_TYPE,
+        name: gatedItems[index]?.name ?? "",
+        message: issue.message
+      });
+    }
+    return errors;
+  }
   /**
    * Revert entire package to last published state.
    * Restores all metadata definitions from their published snapshots.
@@ -2505,6 +3240,38 @@ var _MetadataManager = class _MetadataManager {
     }
   }
   // ==========================================
+  // API Endpoint Resolution
+  // ==========================================
+  /**
+   * Resolve a request's `method`+`path` to the declared `api` metadata item
+   * that owns it — `IMetadataService.matchEndpoint` (#5080 contract, #5089
+   * implementation, #5040 E2).
+   *
+   * The behaviour is specified by the contract text in
+   * `packages/spec/src/contracts/metadata-service.ts`; the mechanics
+   * (normalization, lazy index, loud parse-skip, duplicate resolution) live in
+   * `./endpoint-matcher.ts` and are documented there.
+   *
+   * Scope is THIS instance. There is no environment parameter, because callers
+   * already resolve the `metadata` service for the environment they serve —
+   * adding one here would create a second scoping mechanism.
+   *
+   * This method is reached over HTTP on a real boot. The dispatcher seam
+   * landed as #5090 (`packages/runtime/src/api-endpoint-step.ts`, called from
+   * the `setFallbackHandler` the dispatcher plugin installs), and #4936's
+   * wholesale publish refusal of a non-empty `apis:` was replaced by the
+   * #5040 E7 per-shape gates (`packages/spec/src/api/endpoint-publish-gate.ts`)
+   * — so declarations exist and requests arrive here. The showcase's two
+   * declared endpoints are matched and executed through this path in
+   * `packages/qa/dogfood/test/showcase-declarative-endpoints.dogfood.test.ts`.
+   *
+   * @throws when the metadata store cannot be read — an outage must never be
+   *   reported as a miss, because a miss becomes a 404.
+   */
+  async matchEndpoint(query) {
+    return this.endpointMatcher.match(query);
+  }
+  // ==========================================
   // Legacy Loader API (backward compatible)
   // ==========================================
   /**
@@ -2566,8 +3333,9 @@ var _MetadataManager = class _MetadataManager {
           }
           results.push(item);
         }
+        this.reportLoaderReadRecovered(loader.contract.name);
       } catch (e) {
-        this.logger.warn(`Loader ${loader.contract.name} failed to loadMany ${type}`, { error: e });
+        this.reportLoaderReadFailure(loader.contract.name, type, e);
       }
     }
     return results;
@@ -2693,6 +3461,7 @@ var _MetadataManager = class _MetadataManager {
     await this.stopWatching().catch(() => void 0);
     await this.stopRepositoryWatch().catch(() => void 0);
     this.listCache.clear();
+    this.endpointMatcher.invalidate();
   }
   async startRepositoryWatch() {
     const repo = this.repository;
@@ -2722,17 +3491,57 @@ var _MetadataManager = class _MetadataManager {
       if (this.repoWatchIter === iter) this.repoWatchIter = void 0;
     }
   }
+  /**
+   * Drop every local cache of `type` (and of `name` within it) that a change
+   * we did not perform ourselves has just invalidated, so the next read falls
+   * through to the source of truth.
+   *
+   * The callers are the manager's *foreign-write* seams — the repository watch
+   * loop ({@link applyRepoEvent}), the cluster peer replay in
+   * {@link attachClusterPubSub}, and — since #5218 — `NodeMetadataManager`'s
+   * chokidar handler, which is why this is `protected` rather than `private`.
+   * All three learn about a write that landed somewhere else (the repo head;
+   * another node's `sys_metadata`; an editor writing `rootDir/view/x.json`) and
+   * hold caches that the write silently aged out. A file event qualifies on
+   * exactly the definition that matters here: it did not come through this
+   * manager's write API, so nothing has updated the caches on its behalf.
+   * Local writes do not come through here: `register()` / `unregister()` /
+   * `registerInMemory()` update the registry to the value they just wrote and
+   * call `invalidateListCache()` themselves.
+   *
+   * **Delete, do not pre-fill.** Even when the event carries a body we drop the
+   * registry entry rather than writing the body into it: the body reaching us
+   * is a snapshot of *someone else's* write, already possibly superseded, and
+   * pre-filling would race with the true head and require us to re-canonicalise
+   * a definition we did not load. Lazy invalidation is the safer default —
+   * `get()` then falls through to the loaders / repository, which is where the
+   * truth is. (This paragraph is the rationale `applyRepoEvent` carried since
+   * ADR-0008 PR-6; #5109 extended the same choice to the cluster path, #5218 to
+   * the filesystem watcher — where "the truth" is the file chokidar just
+   * reported, served by the `FilesystemLoader` the registry entry was shadowing.)
+   *
+   * `name` is optional because `MetadataWatchEvent.name` is: a nameless event
+   * cannot address a registry entry, so it invalidates the list cache only.
+   * Dropping the whole type store instead would evict `registerInMemory()`
+   * artefacts (code-owned datasources, ADR-0015 Addendum) that no loader can
+   * restore — an unrecoverable loss in exchange for a guess.
+   */
+  invalidateForForeignWrite(type, name) {
+    if (name) {
+      const typeStore = this.registry.get(type);
+      if (typeStore) {
+        typeStore.delete(name);
+        if (typeStore.size === 0) this.registry.delete(type);
+      }
+    }
+    this.invalidateListCache(type);
+  }
   /** Translate a repo event to the legacy MetadataWatchEvent + invalidate caches. */
   applyRepoEvent(evt) {
     const ref = evt.ref;
     const type = ref.type;
     const name = ref.name;
-    const typeStore = this.registry.get(type);
-    if (typeStore) {
-      typeStore.delete(name);
-      if (typeStore.size === 0) this.registry.delete(type);
-    }
-    this.listCache.delete(type);
+    this.invalidateForForeignWrite(type, name);
     const legacyType = evt.op === "create" ? "added" : evt.op === "delete" ? "deleted" : "changed";
     const legacyEvent = {
       type: legacyType,
@@ -2806,6 +3615,14 @@ var _MetadataManager = class _MetadataManager {
         const p = msg.payload;
         if (p?.originNode && p.originNode === this.clusterNodeId) return;
         if (!p?.type || !p.event) return;
+        try {
+          this.invalidateForForeignWrite(p.type, p.event.name);
+        } catch (err) {
+          this.logger.error("Cluster remote invalidation failed", void 0, {
+            type: p.type,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
         setImmediate(() => {
           try {
             this.notifyWatchersLocal(p.type, p.event);
@@ -2936,7 +3753,24 @@ var _MetadataManager = class _MetadataManager {
   }
 };
 _MetadataManager.LIST_CACHE_TTL_MS = 3e4;
+/**
+ * [#5184] TTL for an entry produced by a degraded read (≥1 loader threw).
+ *
+ * Deliberately at the top of the 1–2s band: the point of keeping degraded
+ * results cached at all is to absorb a burst of `list()` calls issued from
+ * inside one open transaction, and those bursts are milliseconds apart but
+ * can be spread by per-row work. Two seconds covers that while still being
+ * 15× shorter than the healthy TTL.
+ */
+_MetadataManager.DEGRADED_LIST_CACHE_TTL_MS = 2e3;
 _MetadataManager.CLUSTER_CHANNEL = "metadata.changed";
+// ── #5089 (#5040 E2): declared-endpoint index ────────────────────────
+// Backs `matchEndpoint`. Lazily built from `api` items on the first call
+// and invalidated by every path that can change them — see
+// `invalidateListCache` (local writes, repo events, HMR/artifact ingest
+// which registers with `notify:false`, and — since #5109 — cluster peer
+// replay) and the `subscribe('api', …)` registration below.
+_MetadataManager.ENDPOINT_METADATA_TYPE = "api";
 var MetadataManager = _MetadataManager;
 
 // src/plugin.ts
@@ -3330,17 +4164,20 @@ var NodeMetadataManager = class extends MetadataManager {
     const type = parts[0];
     const fileName = parts[parts.length - 1];
     const name = path2.basename(fileName, path2.extname(fileName));
+    this.invalidateForForeignWrite(type, name);
     let data = void 0;
     if (eventType !== "deleted") {
-      try {
-        data = await this.load(type, name, { useCache: false });
-      } catch (error) {
+      const read = await this.loadDiagnosed(type, name, { useCache: false });
+      if (read.degraded) {
         this.logger.error("Failed to load changed file", void 0, {
           filePath,
-          error: error instanceof Error ? error.message : String(error)
+          metadataType: type,
+          name,
+          errors: read.errors
         });
         return;
       }
+      data = read.data;
     }
     const event = {
       type: eventType,
@@ -4106,7 +4943,6 @@ var HistoryCleanupManager = class {
           const baseWhere = {};
           if (organizationId) baseWhere.organization_id = organizationId;
           const metaItems = await driver.find(historyTableName, {
-            object: historyTableName,
             where: baseWhere,
             fields: ["type", "name"]
           });
@@ -4123,7 +4959,6 @@ var HistoryCleanupManager = class {
             const filter = { type, name, ...baseWhere };
             try {
               const historyRecords = await driver.find(historyTableName, {
-                object: historyTableName,
                 where: filter,
                 orderBy: [{ field: "version", order: "desc" }],
                 fields: ["id"]
@@ -4158,7 +4993,7 @@ var HistoryCleanupManager = class {
       const count = await driverAny.deleteMany(table, filter);
       return { deleted: typeof count === "number" ? count : 0, errors: 0 };
     }
-    const records = await driver.find(table, { object: table, where: filter, fields: ["id"] });
+    const records = await driver.find(table, { where: filter, fields: ["id"] });
     const ids = records.map((r) => r.id).filter(Boolean);
     return this.bulkDeleteByIds(driver, table, ids);
   }
@@ -4214,13 +5049,11 @@ var HistoryCleanupManager = class {
           filter.type = { $nin: pinnedTypes };
         }
         recordsByAge = await driver.count(historyTableName, {
-          object: historyTableName,
           where: filter
         });
       }
       if (this.policy.maxVersions) {
         const metaItems = await driver.find(historyTableName, {
-          object: historyTableName,
           where: baseWhere,
           fields: ["type", "name"]
         });
@@ -4236,7 +5069,6 @@ var HistoryCleanupManager = class {
           const [type, name] = key.split("");
           const filter = { type, name, ...baseWhere };
           const count = await driver.count(historyTableName, {
-            object: historyTableName,
             where: filter
           });
           if (count > this.policy.maxVersions) {