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

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as System from '@objectstack/spec/system';
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataDiffResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataDiffResult, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
-import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWriteOptions, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
+import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWriteOptions, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ApiEndpointMatch, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
 export { IMetadataService, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
 import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
@@ -117,13 +117,66 @@ interface MetadataLoader {
      */
     list(type: string): Promise<string[]>;
     /**
-     * Save metadata item
+     * Save metadata item into this loader's store.
+     *
+     * [#5654] Optional on the interface, **mandatory for a `datasource:` loader
+     * that declares `capabilities.write`** — `MetadataManager.registerLoader()`
+     * refuses to register such a loader when this method is missing, so the
+     * combination "declared writable, cannot persist" never reaches the runtime.
+     *
+     * The reason it is enforced at registration rather than tolerated at the write
+     * site: `MetadataManager.register()` persists into every writable
+     * `datasource:` loader, and it used to read `loader.save &&` first — a loader
+     * that declares it can be written to but has no `save()` made every write a
+     * silent lie. `register()` would skip it, then write the in-memory registry,
+     * invalidate the list cache, announce a `created`/`updated` event and notify
+     * watchers, so the caller is told the write succeeded; the item reads back
+     * correctly for the life of the process and is **gone at the next restart**,
+     * with nothing to retry it.
+     *
+     * Loaders on the other protocols (`file:`, `memory:`, `http:`, `s3:`) are not
+     * gated: `MetadataManager` never persists to them at runtime — `register()`
+     * filters on `datasource:` — so a missing `save()` there loses nothing.
+     *
      * @param type The metadata type
      * @param name The item name
      * @param data The data to save
      * @param options Save options
      */
     save?(type: string, name: string, data: any, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
+    /**
+     * Delete a metadata item from this loader's store.
+     *
+     * [#5276, #5654] Optional on the interface, **mandatory for a `datasource:`
+     * loader that declares `capabilities.write`** — `MetadataManager.registerLoader()`
+     * refuses to register such a loader when this method is missing, so the
+     * combination "declared writable, cannot delete" never reaches the runtime.
+     *
+     * The reason it is enforced at registration rather than tolerated at the
+     * delete site: `MetadataManager.register()` persists into every writable
+     * `datasource:` loader, and `unregister()` has to take those rows back out
+     * again. A loader that can be written to but not deleted from makes every
+     * deletion a silent lie — `unregister()` would skip it, then drop the
+     * registry entry, invalidate the list cache and announce a `deleted` event,
+     * so the caller is told the delete succeeded while the row is read straight
+     * back out of this loader by the next `list()`/`get()`. `capabilities.write`
+     * therefore means *both* directions of the write, on both ends of the item's
+     * life — declared = enforced.
+     *
+     * One gate covers both halves: `assertWritableLoaderContract` in
+     * `metadata-manager.ts` requires `save()` **and** `delete()` for this
+     * combination and names whichever is missing. #5276 built it for `delete`;
+     * #5654 widened it to `save`, which had the identical silent skip in
+     * `register()` — see the note on `save?` above.
+     *
+     * Loaders on the other protocols (`file:`, `memory:`, `http:`, `s3:`) are not
+     * gated: `MetadataManager` never writes to them at runtime, so it never has a
+     * deletion of its own to take back.
+     *
+     * @param type The metadata type
+     * @param name The item name
+     */
+    delete?(type: string, name: string): Promise<void>;
 }
 
 /**
@@ -159,6 +212,67 @@ declare class MetadataManager implements IMetadataService {
     private dependencies;
     private listCache;
     private static readonly LIST_CACHE_TTL_MS;
+    /**
+     * [#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.
+     */
+    private static readonly DEGRADED_LIST_CACHE_TTL_MS;
+    /**
+     * [#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.
+     */
+    private readonly inflightListReads;
+    private readonly loaderReadFailureReported;
     private realtimeService?;
     private clusterPubSub?;
     private clusterNodeId?;
@@ -167,6 +281,8 @@ declare class MetadataManager implements IMetadataService {
     protected repository?: MetadataRepository;
     private repoWatchIter?;
     private repoWatchClosed;
+    private static readonly ENDPOINT_METADATA_TYPE;
+    private readonly endpointMatcher;
     constructor(config: MetadataManagerOptions);
     /**
      * Set the type registry for metadata type discovery.
@@ -223,6 +339,13 @@ declare class MetadataManager implements IMetadataService {
     private publishRealtimeMetadataEvent;
     /**
      * 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: MetadataLoader): void;
     /**
@@ -259,15 +382,183 @@ declare class MetadataManager implements IMetadataService {
     /**
      * 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`.
      */
     get(type: string, name: string): Promise<unknown | undefined>;
     /**
-     * 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.
+     */
+    getDiagnosed(type: string, name: string): Promise<{
+        data: unknown | undefined;
+        degraded: boolean;
+        errors: string[];
+    }>;
+    /**
+     * 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`.
      */
     list(type: string): Promise<unknown[]>;
+    /**
+     * 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.
+     */
+    private readListUncached;
+    /**
+     * 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.
+     */
+    private reportLoaderReadFailure;
+    /** Un-say {@link reportLoaderReadFailure} once the loader answers again. */
+    private reportLoaderReadRecovered;
+    /**
+     * 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.
+     */
     private cacheListResult;
-    /** Internal helper: drop the cached `list()` result for a type. */
+    /**
+     * 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`.
+     */
+    private readCachedList;
+    /**
+     * 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.
+     */
     private invalidateListCache;
+    /**
+     * 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`.)
+     */
+    private listForIndex;
     /**
      * Unregister/remove a metadata item by type and name.
      * Deletes from database-backed loaders only (same rationale as register()).
@@ -276,8 +567,122 @@ declare class MetadataManager implements IMetadataService {
      * {@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.
      */
     unregister(type: string, name: string, options?: MetadataWriteOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    private deleteMetaItemFromLoader;
+    /**
+     * 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.
+     */
+    private reportMetaItemDeleteFailure;
     /**
      * Check if a metadata item exists
      */
@@ -333,12 +738,70 @@ declare class MetadataManager implements IMetadataService {
      * 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.
      */
     publishPackage(packageId: string, options?: {
         changeNote?: string;
         publishedBy?: string;
         validate?: boolean;
+        /**
+         * [#5189] The package manifest's EXPLICIT `manifest.namespace` (ADR-0121
+         * D2), supplied by a caller that holds the manifest.
+         *
+         * `MetadataManager` has no manifest concept — it indexes items by
+         * `packageId` and nothing else — so it cannot prove a namespace on its
+         * own, and an `api` item's own `namespace`-ish fields are author-supplied
+         * data, not identity (reading them would make the D1/D2 carve-out gate
+         * vacuous: an author would simply declare the namespace their path
+         * already uses). Absent this option the namespace gate fails and `api`
+         * items in the package cannot publish through this path — which is the
+         * correct outcome, not a limitation to route around: a publish that
+         * cannot prove a namespace must not mint a URL under one.
+         */
+        namespace?: string;
     }): Promise<PackagePublishResult>;
+    /**
+     * [#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).
+     */
+    private gateApiItemsForPublish;
     /**
      * Revert entire package to last published state.
      * Restores all metadata definitions from their published snapshots.
@@ -463,6 +926,36 @@ declare class MetadataManager implements IMetadataService {
      * Duplicate dependencies (same source, target, and kind) are ignored.
      */
     addDependency(dep: MetadataDependency): void;
+    /**
+     * 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.
+     */
+    matchEndpoint(query: {
+        path: string;
+        method: string;
+    }): Promise<ApiEndpointMatch | undefined>;
     /**
      * Load a single metadata item from loaders.
      * Iterates through registered loaders until found.
@@ -539,6 +1032,42 @@ declare class MetadataManager implements IMetadataService {
      */
     dispose(): Promise<void>;
     private startRepositoryWatch;
+    /**
+     * 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.
+     */
+    protected invalidateForForeignWrite(type: string, name?: string): void;
     /** Translate a repo event to the legacy MetadataWatchEvent + invalidate caches. */
     private applyRepoEvent;
     protected notifyWatchers(type: string, event: MetadataWatchEvent): void;
@@ -1052,6 +1581,51 @@ declare class DatabaseLoader implements MetadataLoader {
      * Convert a database row to a MetadataRecord-like object.
      */
     private rowToRecord;
+    /**
+     * 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.
+     */
+    private rethrowUnlessTableUnprovisioned;
     load(type: string, name: string, _options?: MetadataLoadOptions): Promise<MetadataLoadResult>;
     loadMany<T = any>(type: string, _options?: MetadataLoadOptions): Promise<T[]>;
     exists(type: string, name: string): Promise<boolean>;