@objectstack/metadata 17.2.0 → 17.4.0

package/dist/index.d.cts

@@ -3,12 +3,13 @@ import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLo
 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, ApiEndpointMatch, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
 export { IMetadataService, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
-import { MetadataTypeRegistryEntryParsed, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
+import { MetadataTypeRegistryEntryParsed, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
 import { z } from 'zod';
 import { MetadataRepository } from '@objectstack/metadata-core';
 export { HistoryOptions, MetaRef, MetadataEvent, MetadataItem, MetadataItemHeader, MetadataRepository, SysMetadataHistoryObject, SysMetadataObject, WatchFilter } from '@objectstack/metadata-core';
+export { deriveViewContainerObject } from './view-container.cjs';
 
 /**
  * Metadata Serializer Interface
@@ -72,6 +73,29 @@ interface MetadataSerializer {
  * Defines the contract for loading metadata from various sources
  */
 
+/**
+ * [#14205] One loaded item paired with the KEY its store holds it under.
+ *
+ * The pair exists because a metadata body is not required to name itself. Most
+ * do — and for those the key and `data.name` agree, because
+ * `assertMetadataRegisterContract` refuses a `register(type, name, data)` whose
+ * `data.name` disagrees with the `name` argument. But an aggregated `defineView`
+ * container has no own `name` BY DESIGN (its identity is the target object), and
+ * `register()` explicitly allows that: "A document with NO `name` of its own is
+ * fine — the argument is the key".
+ *
+ * So the key is a fact about the STORE, not about the body, and it is the only
+ * identity a nameless item has. Carrying it BESIDE `data` rather than folding it
+ * into `data` is the whole point: the body stays byte-identical to what was
+ * stored, so no consumer sees a synthesised `name` and the register contract's
+ * `data.name` check keeps meaning what it means.
+ */
+interface MetadataKeyedItem<T = any> {
+    /** The key this item is stored under — `register()`'s `name` argument. */
+    readonly name: string;
+    /** The stored body, exactly as {@link MetadataLoader.loadMany} would return it. */
+    readonly data: T;
+}
 /**
  * Abstract interface for metadata loaders
  * Implementations can load from filesystem, HTTP, S3, databases, etc.
@@ -96,6 +120,34 @@ interface MetadataLoader {
      * @returns Array of loaded items
      */
     loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * Load multiple items of a type, each paired with the KEY this loader holds
+     * it under.
+     *
+     * [#14205] Optional, and the reason it is a second method rather than a
+     * widened `loadMany()`: `MetadataLoader` is exported from this package's
+     * public entry, with implementors outside it (`packages/objectql`'s
+     * conformance fixtures among them). Changing `loadMany()`'s return type would
+     * break every one of them; an optional member breaks none, and a loader that
+     * cannot produce keys — `RemoteLoader`, whose wire format carries bodies only
+     * — simply does not declare it.
+     *
+     * `MetadataManager` prefers this method wherever it merges a loader's answer
+     * into a keyed set (`list()`, and the endpoint index), and falls back to
+     * `loadMany()` keyed by `data.name` when it is absent. That fallback is
+     * exactly the pre-#14205 behaviour, so it drops items whose body has no
+     * top-level `name`: implement this method on any loader that can be asked to
+     * hold one.
+     *
+     * `data` MUST be the same body `loadMany()` would return for the item —
+     * unmodified, in particular with no `name` folded in. `name` is the store's
+     * key, carried beside the body, never written into it.
+     *
+     * @param type The metadata type
+     * @param options Load options with patterns
+     * @returns Array of (key, body) pairs
+     */
+    loadManyKeyed?<T = any>(type: string, options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
     /**
      * Check if item exists
      * @param type The metadata type
@@ -224,7 +276,6 @@ declare class MetadataManager implements IMetadataService {
     protected watchCallbacks: Map<string, Set<WatchCallback>>;
     protected config: MetadataManagerOptions;
     private registry;
-    private overlays;
     private typeRegistry;
     private dependencies;
     private listCache;
@@ -534,6 +585,50 @@ declare class MetadataManager implements IMetadataService {
      * result may be memoized depends on what happened to the read's registration
      * while it ran, which only `list()` can see.
      */
+    /**
+     * Merge one loader's answer for `type` into `items`, under the identity that
+     * loader holds each item by.
+     *
+     * ## [#14205] The identity of a loader-held item is its ROW KEY
+     *
+     * Both plural readers used to key a loader's items by `body.name`, and admit
+     * an item only when the body carried a string one:
+     *
+     * ```ts
+     * if (itemAny && typeof itemAny.name === 'string' && !items.has(itemAny.name))
+     * ```
+     *
+     * A body is not required to name itself. `register(type, name, data)` takes
+     * the key as its ARGUMENT, and `assertMetadataRegisterContract` says in as
+     * many words that "A document with NO `name` of its own is fine — the argument
+     * is the key". An aggregated `defineView` container is exactly that: no own
+     * `name` by design, identity carried in the row's `name` column.
+     *
+     * So the old gate dropped every such item the moment the registry went cold
+     * and only the loader could answer — a persisted view container vanished from
+     * `list('view')` after a restart, and `listDiagnosed()` called the short
+     * answer complete because no loader had thrown. Same gate, same effect, in
+     * `listForIndex()`: a nameless `api` row fell out of the endpoint index, where
+     * a miss reads as "nothing declares this route".
+     *
+     * The repair is to ask the loader for the key instead of guessing it from the
+     * body ({@link MetadataLoader.loadManyKeyed}), and to keep the key BESIDE the
+     * body: nothing is written into a body that deliberately has none, so the
+     * register contract's refusal of a disagreeing `data.name` still means what it
+     * says.
+     *
+     * Nothing consumers see today changes shape. For any item that went through
+     * `register()`, a `data.name` that exists is required to EQUAL the key, so the
+     * keyed merge produces the identical map entry; what is new is only the
+     * entries the old gate refused. The `loadMany()` fallback below is the
+     * pre-#14205 behaviour verbatim, for loaders that cannot produce keys
+     * (`RemoteLoader`'s wire format carries bodies only).
+     *
+     * Read failures are NOT caught here: `readListUncached` warns-and-continues,
+     * `listForIndex` deliberately throws, and that difference is each caller's to
+     * keep.
+     */
+    private admitLoaderItems;
     private readListUncached;
     /**
      * Report — at `error`, once per outage episode — that a loader could not be
@@ -774,6 +869,30 @@ declare class MetadataManager implements IMetadataService {
     exists(type: string, name: string): Promise<boolean>;
     /**
      * List all names of metadata items of a given type
+     *
+     * ## [#14423] One loader's fault does not take the whole enumeration down
+     *
+     * This loop used to be bare — `const result = await loader.list(type)` with
+     * no `try`, while the two sibling plural reads (`list()` via
+     * {@link admitLoaderItems}, and {@link loadMany}) have carried a per-loader
+     * `catch` since #5108. That asymmetry is the defect, independent of any one
+     * caller: the SAME storage outage was swallowed by one plural read and
+     * thrown out of the other, so which answer a caller got depended only on
+     * which method it happened to call. A caller reading both — the action
+     * governance audit is one — saw `loadMany` report a short-but-successful
+     * set and `listNames` throw, and had no way to tell that one fact was
+     * behind both.
+     *
+     * Same shape as `loadMany`'s, deliberately, down to the helpers: the outage
+     * is spoken once per loader through {@link reportLoaderReadFailure} and
+     * un-said through {@link reportLoaderReadRecovered}. ⛔ Not a third spelling
+     * for "a loader faulted" — a second vocabulary for one event is how the two
+     * reads drifted apart in the first place.
+     *
+     * The degradation is the same one `list()` documents and is graded the same
+     * way (AGENTS.md → "Degradation log levels"): the caller still gets an
+     * array, nothing 500s, and the set is quietly short — so it is reported at
+     * `error`, by the shared helper, rather than being re-graded here.
      */
     listNames(type: string): Promise<string[]>;
     /**
@@ -803,6 +922,35 @@ declare class MetadataManager implements IMetadataService {
      * Runtime-authored `shared` / `personal` views (`sys_view_definition`) are
      * merged in by the REST layer; this method returns the `package` layer that
      * was registered from source.
+     *
+     * ## [#13913] Aggregated containers are expanded inline, per read
+     *
+     * `this.list('view')` is `MetadataManager`'s OWN loader-based store — the
+     * in-memory registry plus every registered loader — and is a completely
+     * different store from the `sys_metadata` rows `getMetaItems` reads. #13407
+     * taught `getMetaItems` to expand a runtime-authored aggregated container
+     * inline; this exit never called it and had no equivalent step, so a
+     * container that `GET /meta/view?object=` now serves still answered **empty**
+     * here.
+     *
+     * Merely getting the container into the store would not have helped: the
+     * filter also requires `viewKind`, and a container has none. Loosening that
+     * requirement is NOT the repair — it would answer with the container itself
+     * as a view, the behaviour #7163 ruled wrong — so what is added below is the
+     * container's **expansion**, whose items each carry the `viewKind` + `object`
+     * pair this filter has always tested. The filter itself is untouched: it
+     * reads the top-level `object`, exactly as `ViewSchema.object` declares.
+     *
+     * Registry-free and per-read, mirroring #13407's choice at the other exit and
+     * for the same reason — the registry is process-wide, so a read must not
+     * graft rows into it (see `view-container-expansion.ts`'s header, which also
+     * records why the protocol's copy of this logic cannot be imported).
+     *
+     * Already-present items win: an expansion contributes only names the store
+     * does not already hold, so a container whose expanded ViewItems were
+     * registered by a source registrar (the ObjectQL boot loop, the artifact/HMR
+     * loader) still answers with those registered, fully-enriched items and this
+     * step adds nothing.
      */
     getViewsByObject(object: string): Promise<unknown[]>;
     /**
@@ -931,29 +1079,6 @@ declare class MetadataManager implements IMetadataService {
         type: string;
         name: string;
     }>, options?: MetadataWriteOptions): Promise<MetadataBulkResult>;
-    private overlayKey;
-    /**
-     * Get the active overlay for a metadata item
-     */
-    getOverlay(type: string, name: string, scope?: 'platform' | 'user'): Promise<MetadataOverlay | undefined>;
-    /**
-     * Save/update an overlay for a metadata item
-     */
-    saveOverlay(overlay: MetadataOverlay): Promise<void>;
-    /**
-     * Remove an overlay, reverting to the base definition
-     */
-    removeOverlay(type: string, name: string, scope?: 'platform' | 'user'): Promise<void>;
-    /**
-     * Get the effective (merged) metadata after applying all overlays.
-     * Resolution order: system ← merge(platform) ← merge(user)
-     */
-    getEffective(type: string, name: string, context?: {
-        userId?: string;
-        tenantId?: string;
-        roles?: string[];
-        permissions?: string[];
-    }): Promise<unknown | undefined>;
     /**
      * Watch for metadata changes (IMetadataService contract).
      * Returns a handle for unsubscribing.
@@ -1081,6 +1206,72 @@ declare class MetadataManager implements IMetadataService {
      * Aggregates results from all loaders.
      */
     loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * [#14423] {@link loadMany}, read under the identity the STORE holds each
+     * item by — the keyed plural read, beside the unkeyed one.
+     *
+     * ## Why a second method and not a widened `loadMany`
+     *
+     * `loadMany` keys nothing: it returns bodies, and every consumer that needs
+     * an identity reads `body.name` off them. #14205 already ruled what identity
+     * IS — the key the store holds the item under (`register(type, name, data)`
+     * takes it as the ARGUMENT, and a body is not required to name itself) — so
+     * `body.name` is a guess that happens to be right for most items and drops
+     * the rest ENTIRELY: an item whose body carries no `name` is served by
+     * `load(type, name)` and is not nameable from `loadMany`'s answer at all.
+     *
+     * Widening `loadMany`'s return would fix that and break every consumer of a
+     * published shape (the ones counted on this card all read `body.name` as the
+     * identity). So this is additive: `loadMany`'s return shape is untouched,
+     * and a caller that needs the key asks for the key.
+     *
+     * ## What it reads — the same population `loadMany` reads
+     *
+     * Loaders only, deliberately, so this is `loadMany` keyed and nothing more.
+     * It is NOT `list()`/{@link listNames}, which also merge the in-memory
+     * `register()` registry; a caller wanting that set has those. Reading the
+     * loaders alone is also what makes this the enumerable twin of
+     * {@link loadDiagnosed}, which walks the same loaders by name — that pairing
+     * is the point on the audit side of #14423, where an enumeration and a
+     * by-name read that disagree about a population make one subsystem accuse
+     * another of a defect neither has.
+     *
+     * ## Delegate first, fall back second — and why that order is not a style
+     *
+     * Per loader: {@link MetadataLoader.loadManyKeyed} where the loader offers
+     * one, else its `list()` + a per-name `load()`. Measured, on
+     * `DatabaseLoader`: the keyed method shares `loadMany`'s single query
+     * (`{find:1, findOne:0}` — zero extra cost), while enumerate-then-read-each
+     * on that same loader is a real N+1 (`{find:1, findOne:5}` for five items).
+     * The fallback exists for loaders that cannot produce keys at all
+     * (`RemoteLoader`'s wire format carries bodies only), and it recovers the
+     * nameless item the pre-#14205 `loadMany`-and-key-by-`body.name` fallback
+     * drops — which is why it is `list()` + `load()` and not `loadMany()`.
+     *
+     * ## Failure posture
+     *
+     * Per-loader `try`/`catch`, the same seam and the same helpers as
+     * {@link loadMany} and `list()` — one loader's outage does not take the
+     * enumeration down, and it is reported once through
+     * {@link reportLoaderReadFailure} rather than in a third vocabulary.
+     * Earlier loaders win a key collision, mirroring `list()`.
+     */
+    loadManyKeyed<T = any>(type: string, options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
+    /**
+     * Merge ONE loader's answer for `type` into `items`, keyed by that loader's
+     * own key for each item — {@link loadManyKeyed}'s per-loader body.
+     *
+     * Distinct from {@link admitLoaderItems} on exactly one axis, and that axis
+     * is the whole of #14423: the fallback for a loader with no
+     * `loadManyKeyed`. `admitLoaderItems` falls back to `loadMany` keyed by
+     * `data.name` — the pre-#14205 behaviour, verbatim, which drops a nameless
+     * body. Here the fallback is `list()` + a per-name `load()`, so a loader
+     * that cannot enumerate keys and bodies together still answers with both.
+     *
+     * Read failures are NOT caught here — the caller owns that verdict, as in
+     * {@link admitLoaderItems}.
+     */
+    private admitKeyedLoaderItems;
     /**
      * Save metadata item to a loader
      */
@@ -1294,7 +1485,7 @@ interface MetadataPluginOptions {
 }
 declare class MetadataPlugin implements Plugin {
     name: string;
-    type: string;
+    type: "standard";
     version: string;
     /**
      * Services init() UNCONDITIONALLY registers (ADR-0116, #4131) — lets the
@@ -1330,6 +1521,21 @@ declare class MetadataPlugin implements Plugin {
      * `name` and are skipped by `_parseAndRegisterArtifact`'s register loop.
      */
     private lastParsedMetadata?;
+    /**
+     * Once-per-process dedupe for the summaries the versioned artifact window
+     * emits. The artifact watcher replays `_parseAndRegisterArtifact` on every
+     * file change, so without this a dev loop over a legacy artifact would
+     * re-announce the same finding on every reload — the same shape
+     * `Protocol.storedConversionWarned` guards on the stored-row pass, which
+     * this surfacing is modeled on.
+     *
+     * Two key families share the set, because they share the replay:
+     * `<conversionId>|<label>` for a forward-conversion summary (#12772), and
+     * `unbound-form-predicate-root|<label>` for the unbound-root notice
+     * (#12915) — one line per artifact there, not one per conversion, since
+     * the notice already aggregates every finding it made.
+     */
+    private artifactConversionWarned;
     constructor(options?: MetadataPluginOptions);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
@@ -1363,6 +1569,69 @@ declare class MetadataPlugin implements Plugin {
      * Fetch JSON content from a URL with configurable timeout.
      */
     private _fetchJson;
+    /**
+     * Versioned ADR-0087 forward conversion at the artifact-ingestion door
+     * (#12772) — runs BEFORE the strict schema parse below, because the parse
+     * is the refusal point.
+     *
+     * A compiled artifact is data at rest with a version stamp: built by
+     * released tooling, then unchanged while the platform moves on. When a
+     * spec release retires an authorable key inside a protocol line (spec
+     * 17.1 → 17.2 retired the `allowRestore`/`allowPurge` permission bits),
+     * every already-built artifact carrying the key becomes unbootable at the
+     * tombstone — with no operator remedy, since `os migrate meta` targets
+     * sources, not built artifacts. The stored-row read path already replays
+     * the conversion chain for exactly this reason
+     * (`applyConversionsToStoredItem`, ADR-0087 addendum); this is the same
+     * policy at the artifact door, **keyed off the artifact's own declared
+     * `engines.protocol` floor**: an artifact authored below the running spec
+     * version converts forward, an artifact authored at the current (or a
+     * newer) surface converts nothing and answers to the strict parse,
+     * tombstones included. The version key is what keeps this a conversion
+     * rather than an amnesty — the retired keys return with the M2 lifecycle
+     * batch (#1883), and artifacts authored against that surface must never
+     * have them stripped by history.
+     *
+     * Notices surface the way the stored-row pass's do — operator-visible and
+     * deduped — as one summary line per conversion per artifact rather than
+     * one per rewritten path (a real 17.1 artifact carried 150 strips of the
+     * same two keys; 150 identical warn lines would bury the boot log).
+     */
+    private _convertArtifactForward;
+    /**
+     * Operator-facing boot notice for form-view predicates that fault OPEN on
+     * this runtime (#12915 scope C — maintainer ruling 2026-08-28, 「同意C」).
+     *
+     * A form-view predicate binds `record` / `previous` / `parent` (runtime
+     * record forms) or `data` (metadata-editing forms) — and a FIELD-level one
+     * also binds `current_user` and its ADR-0068 aliases (objectui#6010),
+     * which a SECTION-level one does not. The contract states beside that
+     * vocabulary that a bare identifier is UNBOUND and the predicate faults,
+     * and `visibleWhen`'s fault fallback is `true`. On a real
+     * 17.1-built artifact that combination dead-ends record creation in the
+     * console: the conditionally hidden field renders, and its unconditional
+     * `required: true` — authored to be gated by the visibility that no longer
+     * applies — blocks every submit, while the same payload POSTs 201 through
+     * REST. Nothing refused, nothing logged, and only the operator can fix it
+     * (by rebuilding the artifact), so this is the channel the ruling picked:
+     * service startup, server-side, never a console surface — the person at
+     * the form cannot act on "your artifact is stale".
+     *
+     * **Detection only.** No refusal, no rewrite, no behaviour change: the
+     * predicate keeps faulting open exactly as before. Rewriting a bare root to
+     * `record.` is the ADR-0087 conversion (#12915 scope A), deferred by the
+     * same ruling with an explicit start line.
+     *
+     * **Same versioned window as the conversion replay above** — and read off
+     * that pass's own verdict rather than recomputed, so the two can never
+     * disagree about which artifacts are "old". An artifact declaring the
+     * current (or a newer) floor answers to the strict parse and gets nothing
+     * from here even when it does carry bare roots; that boundary is what keeps
+     * a notice about legacy artifacts out of contract territory. An undeclared
+     * range is treated as old data at rest, matching the grandfathering posture
+     * the window already takes (`converted-undeclared`).
+     */
+    private _warnUnboundFormPredicateRoots;
     /**
      * Parse raw artifact JSON (envelope or bare definition) and register all
      * metadata items into the MetadataManager.
@@ -1376,6 +1645,35 @@ declare class MetadataPlugin implements Plugin {
      * landing.
      */
     private _parseAndRegisterArtifact;
+    /**
+     * Register ONE artifact body's collections into the MetadataManager.
+     *
+     * A "body" is either the whole artifact (the single-package branch, where
+     * the artifact and its one package are the same object) or one entry of
+     * `packages[]` (ADR-0130 D4), which is an assembled
+     * `{ ...manifest, ...collections }` payload carrying the same collection
+     * keys the top level does. The loop is identical for both — that is the
+     * point: there is one ingestion of a collection here, not one per shape.
+     *
+     * @param provenance - The `(packageId, packageVersion)` every item found in
+     *   this body is stamped with (ADR-0010 §3.7, via `applyProtection`). It is
+     *   the body's OWN identity, never the enclosing artifact's, which is what
+     *   makes a multi-package artifact's items agree with the registry and with
+     *   `GET /api/v1/packages` about who owns them.
+     * @param slots.claim - Called with every `(type, name)` this pass
+     *   registered. Passed when reading package bodies; the residual sweep uses
+     *   what it recorded.
+     * @param slots.skip - Consulted before registering each `(type, name)`.
+     *   Passed ONLY by the residual sweep, so a package body's copy is never
+     *   overwritten by the flattened top-level copy of the same definition —
+     *   the overwrite that re-attributed the item to the artifact's manifest.
+     *   ⛔ It is never passed while reading the bodies themselves: two items of
+     *   one name inside one body still register as they always have (last
+     *   wins), because suppressing that would be a behaviour change on the
+     *   single-package branch D7 pins.
+     * @returns How many items this body registered.
+     */
+    private _registerArtifactBodyCollections;
     /**
      * Reload the artifact from disk into the MetadataManager, then announce a
      * generic `metadata:reloaded` hook. Used by BOTH reload paths (the HMR POST
@@ -1418,6 +1716,16 @@ declare class MemoryLoader implements MetadataLoader {
     private storage;
     load(type: string, name: string, _options?: MetadataLoadOptions): Promise<MetadataLoadResult>;
     loadMany<T = any>(type: string, _options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * [#14205] The keyed half of {@link loadMany}. The storage map is already
+     * `Type -> Name -> Data`, so the key this loader holds an item under is the
+     * map key — `loadMany()` was simply discarding it, which dropped every
+     * nameless body out of `MetadataManager.list()` and out of the endpoint index.
+     *
+     * The body is handed back by reference, unchanged: the key travels beside it,
+     * never folded into it.
+     */
+    loadManyKeyed<T = any>(type: string, _options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
     exists(type: string, name: string): Promise<boolean>;
     stat(type: string, name: string): Promise<MetadataStats | null>;
     list(type: string): Promise<string[]>;
@@ -1445,6 +1753,40 @@ declare class RemoteLoader implements MetadataLoader {
     loadMany<T = any>(type: string, _options?: MetadataLoadOptions): Promise<T[]>;
     exists(type: string, name: string): Promise<boolean>;
     stat(type: string, name: string): Promise<MetadataStats | null>;
+    /**
+     * [#15037] Report only the names that ARE names.
+     *
+     * This read used to be `loadMany<{ name: string }>(type)` mapped straight to
+     * `items.map(i => i.name)`. That type argument is an ASSERTION about bodies
+     * that arrived over HTTP, and nothing checked it: a body with no top-level
+     * `name` yielded `undefined`, which went into an array this signature
+     * declares as `string[]` and reached consumers through
+     * `MetadataManager.listNames()` — a runtime violation of a declared type,
+     * not an untidy entry. A consumer that keys by it, lower-cases it, or feeds
+     * it back to a by-name `load()` gets `undefined` where the type says it
+     * cannot be.
+     *
+     * The guard is `DatabaseLoader.list()`'s, one file away: same cast-then-map
+     * spelling, one `typeof` filter behind it. Silently dropping is the landed
+     * direction, not a preference — `DatabaseLoader` drops rather than throws,
+     * and `FilesystemLoader`'s narrowing carries a maintainer ruling (via the
+     * director seat on #14486, 2026-09-02) that chose narrowing (A) over
+     * refusing loudly (B), because a name in the list that the door answers
+     * `null` for is the silent failure an author reads as their own typo. An
+     * `undefined` here is the extreme form of that name.
+     *
+     * ⛔ NOT copied from the siblings: `MemoryLoader` answers with its store
+     * keys, and #14205 ruled that identity is the key the store holds an item
+     * under rather than `body.name`. This loader reads over HTTP and holds no
+     * store key, so `body.name` is the only identity it has — the list is
+     * narrowed to agree with the door instead. `loadMany()` is deliberately
+     * untouched: it keys nothing, so a nameless body is still served there.
+     *
+     * The predicate is spelled as a type guard, and the mapped element type left
+     * `unknown`, so `tsc` PROVES the declared `string[]` instead of a cast
+     * asserting it — otherwise the compiler reads the filter as always-true and
+     * a later reader deletes it as dead.
+     */
     list(type: string): Promise<string[]>;
     save(type: string, name: string, data: any, _options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
 }
@@ -1523,8 +1865,14 @@ interface DatabaseLoaderCacheOptions {
     enabled?: boolean;
     /** Max number of cached `(type, name)` entries. Default: `500`. */
     maxSize?: number;
-    /** TTL in milliseconds. Set to `0` to disable expiry. Default: `60_000`. */
-    ttl?: number;
+    /**
+     * TTL in milliseconds. Set to `0` to disable expiry. Default: `60_000`.
+     *
+     * Renamed from `ttl` (#14478) in lockstep with the spec key it mirrors,
+     * `MetadataManagerConfig.cache.databaseLoader.ttlMs`: the unit now lives in
+     * the name, not only in this comment.
+     */
+    ttlMs?: number;
 }
 /**
  * Configuration for the DatabaseLoader.
@@ -1750,7 +2098,33 @@ declare class DatabaseLoader implements MetadataLoader {
      */
     private rethrowUnlessTableUnprovisioned;
     load(type: string, name: string, _options?: MetadataLoadOptions): Promise<MetadataLoadResult>;
+    /**
+     * The one type-wide read both plural readers share: every row of `type`, each
+     * body paired with the `name` COLUMN it was stored under.
+     *
+     * [#14205] `name` is `null` only for a row whose key column does not hold a
+     * string. Such a row is still a body {@link loadMany} must return — dropping
+     * it would change what consumers see today — but it has no usable identity,
+     * so {@link loadManyKeyed} filters it out rather than invent one.
+     *
+     * One query and one cache entry serve both methods: `loadMany()` used to own
+     * them, and splitting them would have made every keyed `list()` read miss the
+     * cache and re-hit the database.
+     */
+    private readTypeRows;
     loadMany<T = any>(type: string, _options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * [#14205] The keyed half of {@link loadMany} — see
+     * {@link MetadataKeyedItem} for why the row key travels beside the body
+     * instead of inside it.
+     *
+     * `DatabaseLoader` is where the defect was measured: an aggregated view
+     * container is written by `register('view', OBJECT, container)` and stored
+     * verbatim, so its `sys_metadata` row carries the identity in the `name`
+     * COLUMN and the body has none. {@link rowToData} returns that body without
+     * folding the column in — deliberately, and unchanged here.
+     */
+    loadManyKeyed<T = any>(type: string, _options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
     exists(type: string, name: string): Promise<boolean>;
     stat(type: string, name: string): Promise<MetadataStats | null>;
     list(type: string): Promise<string[]>;
@@ -1791,6 +2165,99 @@ declare class DatabaseLoader implements MetadataLoader {
     delete(type: string, name: string): Promise<void>;
 }
 
+/**
+ * [#14921] The refusal a metadata source tree earns by naming one item twice.
+ *
+ * ## The invariant this restores
+ *
+ * *What is listed is what is loadable.* `FilesystemLoader` derives a metadata
+ * name by stripping the extension from a flat file's basename, and resolves a
+ * name back to a file under a FIXED extension precedence (`.json` → `.yaml` →
+ * `.yml` → `.ts` → `.js`). Two files sharing a stem therefore produced one name
+ * TWICE in `list()` while only the first-precedence file was reachable through
+ * any name at all: the listed set and the addressable set stopped being the
+ * same set, and `loadMany()` kept returning both bodies. The loser was
+ * invisible — not missing, not reported, just never served.
+ *
+ * The failure is silent in the direction that matters for authoring, and the
+ * trigger is a move authors (human and AI) make constantly: convert
+ * `twin.json` to `twin.yaml` and leave the old file behind, or land one from
+ * each of two packages. Today the JSON one is served forever with no
+ * diagnostic anywhere, and `MetadataManager.admitLoaderItems()`'s documented
+ * "keep the first and say nothing" absorbs the collision a second time.
+ *
+ * ## The ruling (maintainer, via the director seat on #14921, 2026-09-05)
+ *
+ * Option 1 of three: **refuse the ambiguous stem loudly at list time.** Two
+ * files sharing a stem across the registered extensions is an AUTHORING ERROR,
+ * reported with both paths named, never resolved by precedence. Not taken:
+ * option 2 (keep the precedence and log at `warn` — with zero instances in any
+ * measured tree, nobody reads that log, and the invariant stays broken) and
+ * option 3 (make the extension part of the name for the non-first file — a
+ * naming rule invented for an error state, grown into the contract).
+ *
+ * The narrowing is cheap for the reason the grade records: no measured
+ * production or example tree carries two files with one stem, so no existing
+ * tree goes red. It is a narrowing with almost no migration account.
+ *
+ * ## Why a brand and a predicate rather than bare `instanceof`
+ *
+ * `MetadataManager`'s plural reads catch per loader on purpose (#5108/#14423):
+ * a storage outage must degrade to a short-but-served list rather than take the
+ * whole enumeration down. This refusal is the opposite kind of fact — an
+ * author's tree is malformed and no retry fixes it — so those seams have to
+ * re-raise THIS error while still absorbing every other one. A predicate over
+ * a `Symbol.for` brand is the discrimination that survives duplicate copies of
+ * this module in a consumer's dependency graph, where `instanceof` does not.
+ * Same shape, and for the same reason, as `@objectstack/core`'s
+ * `isAuthzStoreUnavailableError`.
+ */
+/** ADR-0112 wire code for the refusal. */
+declare const AMBIGUOUS_METADATA_STEM_CODE: "AMBIGUOUS_METADATA_STEM";
+/**
+ * HTTP status a transport should answer.
+ *
+ * 500, deliberately: the REQUEST is well formed and no caller can fix it by
+ * sending something else — the deployment's own metadata source tree is
+ * ambiguous. Not 503 (nothing is transient here; a retry answers identically
+ * until a file is deleted or renamed) and not 4xx (the caller did nothing
+ * wrong).
+ */
+declare const AMBIGUOUS_METADATA_STEM_STATUS: 500;
+declare const AMBIGUOUS_METADATA_STEM_BRAND: unique symbol;
+/**
+ * Thrown when one metadata name is derived from more than one file among a
+ * loader's REGISTERED extensions.
+ *
+ * The message names every colliding path and the metadata type, because those
+ * are exactly the two things an author needs and neither is recoverable from
+ * the name alone: a bare "duplicate `twin`" sends them looking through a tree
+ * for something they already believe they deleted.
+ */
+declare class AmbiguousMetadataStemError extends Error {
+    /** Brand — see the module doc on why this is not `instanceof`. */
+    readonly [AMBIGUOUS_METADATA_STEM_BRAND]: true;
+    /** ADR-0112 wire code. */
+    readonly code: "AMBIGUOUS_METADATA_STEM";
+    /** HTTP status a transport should answer. */
+    readonly status: 500;
+    /** The metadata type whose directory holds the collision (e.g. `object`). */
+    readonly type: string;
+    /** The one name both files derive to. */
+    readonly stem: string;
+    /** Every colliding file, absolute, sorted — never just the winner. */
+    readonly paths: readonly string[];
+    constructor(type: string, stem: string, paths: readonly string[]);
+}
+/**
+ * True when `err` is the ambiguous-stem refusal above.
+ *
+ * The predicate every catch-and-degrade seam uses to re-raise THIS one without
+ * loosening its handling of anything else — a storage outage still degrades, an
+ * author's malformed tree does not.
+ */
+declare function isAmbiguousMetadataStemError(err: unknown): err is AmbiguousMetadataStemError;
+
 /**
  * Metadata History Utilities
  *
@@ -1935,4 +2402,4 @@ declare class TypeScriptSerializer implements MetadataSerializer {
     getFormat(): MetadataFormat;
 }
 
-export { DatabaseLoader, type DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff };
+export { AMBIGUOUS_METADATA_STEM_CODE, AMBIGUOUS_METADATA_STEM_STATUS, AmbiguousMetadataStemError, DatabaseLoader, type DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, type MetadataKeyedItem, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff, isAmbiguousMetadataStemError };