@objectstack/metadata 17.3.0 → 17.4.0

package/dist/index.d.cts

@@ -9,6 +9,7 @@ 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
@@ -868,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[]>;
     /**
@@ -1181,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
      */
@@ -1662,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>;
 }
@@ -1740,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.
@@ -2034,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
  *
@@ -2178,61 +2402,4 @@ declare class TypeScriptSerializer implements MetadataSerializer {
     getFormat(): MetadataFormat;
 }
 
-/**
- * [#13913] Registry-free expansion of an aggregated `defineView` container
- * that reached `MetadataManager`'s OWN backing store.
- *
- * ---------------------------------------------------------------------------
- * Why this lives in `packages/metadata` and does NOT import the protocol's copy
- * ---------------------------------------------------------------------------
- * `packages/metadata-protocol` grew `expandRuntimeViewContainer` (#13407) for
- * `getMetaItems`' own inline expansion, and the obvious move would be to share
- * it. **The dependency edge forbids it**: `@objectstack/metadata-protocol`
- * declares `@objectstack/metadata` as a dependency, so an import in this
- * direction inverts an existing edge and closes a cycle. Promoting the
- * protocol's private method to a public export would not help either — it
- * would widen that package's surface *and* still be unreachable from here.
- *
- * The reusable substance is therefore taken from where it already is: the
- * canonical expansion primitives (`isAggregatedViewContainer`,
- * `expandViewContainer`) live in `@objectstack/spec`, one level BELOW both
- * packages, and this package already imports them (`plugin.ts`). Nothing is
- * duplicated except the ~6-line object-derivation chain — which is exactly the
- * part that has silently drifted three ways (the ObjectQL boot loop keys off
- * the registration name, `plugin.ts` walks two levels, and `protocol.ts` walks
- * four since #13407). {@link deriveViewContainerObject} is the one spelling of
- * it for this package, so the drift has a single place to be repaired rather
- * than a third private copy to fall behind.
- *
- * ---------------------------------------------------------------------------
- * Registry-free, on purpose
- * ---------------------------------------------------------------------------
- * Nothing here REGISTERS. `protocol.ts`'s own header records why its
- * registry-MUTATING path (`hydrateExpandedViewItems`) could not simply be
- * widened — it is gated off for every org-scoped row (ADR-0005: the registry
- * is shared by every org a kernel serves) — and why #13407's actual repair was
- * a separate, registry-free, per-request expansion. The same reasoning applies
- * one exit over: `MetadataManager`'s registry is process-wide too, so the
- * repair for {@link MetadataManager.getViewsByObject} is a pure function over
- * what that one read already holds.
- */
-
-/**
- * Which object an aggregated view container binds to.
- *
- * The container's OWN top-level `object` field — `ViewSchema.object`,
- * documented there as "how a stack-level `views: [...]` entry says which object
- * its views belong to; read by `getViewsByObject()` / `GET /meta/view?object=`"
- * — is the authorial, explicit signal and is consulted FIRST (#13407). The
- * three-deep fallback below it is kept unchanged for every container written
- * before that field was read here: `list.data.object`, then `form.data.object`,
- * then the row's own `name` — which is the bound object only by convention, and
- * is why a container that set the top-level field but not `list.data.object`
- * used to bind under the wrong key or not at all.
- *
- * Returns `undefined` when no binding can be derived; every caller treats that
- * as "no expansion" rather than an error.
- */
-declare function deriveViewContainerObject(container: unknown): string | undefined;
-
-export { 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, deriveViewContainerObject, 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 };

package/dist/index.d.ts

@@ -9,6 +9,7 @@ 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.js';
 
 /**
  * Metadata Serializer Interface
@@ -868,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[]>;
     /**
@@ -1181,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
      */
@@ -1662,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>;
 }
@@ -1740,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.
@@ -2034,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
  *
@@ -2178,61 +2402,4 @@ declare class TypeScriptSerializer implements MetadataSerializer {
     getFormat(): MetadataFormat;
 }
 
-/**
- * [#13913] Registry-free expansion of an aggregated `defineView` container
- * that reached `MetadataManager`'s OWN backing store.
- *
- * ---------------------------------------------------------------------------
- * Why this lives in `packages/metadata` and does NOT import the protocol's copy
- * ---------------------------------------------------------------------------
- * `packages/metadata-protocol` grew `expandRuntimeViewContainer` (#13407) for
- * `getMetaItems`' own inline expansion, and the obvious move would be to share
- * it. **The dependency edge forbids it**: `@objectstack/metadata-protocol`
- * declares `@objectstack/metadata` as a dependency, so an import in this
- * direction inverts an existing edge and closes a cycle. Promoting the
- * protocol's private method to a public export would not help either — it
- * would widen that package's surface *and* still be unreachable from here.
- *
- * The reusable substance is therefore taken from where it already is: the
- * canonical expansion primitives (`isAggregatedViewContainer`,
- * `expandViewContainer`) live in `@objectstack/spec`, one level BELOW both
- * packages, and this package already imports them (`plugin.ts`). Nothing is
- * duplicated except the ~6-line object-derivation chain — which is exactly the
- * part that has silently drifted three ways (the ObjectQL boot loop keys off
- * the registration name, `plugin.ts` walks two levels, and `protocol.ts` walks
- * four since #13407). {@link deriveViewContainerObject} is the one spelling of
- * it for this package, so the drift has a single place to be repaired rather
- * than a third private copy to fall behind.
- *
- * ---------------------------------------------------------------------------
- * Registry-free, on purpose
- * ---------------------------------------------------------------------------
- * Nothing here REGISTERS. `protocol.ts`'s own header records why its
- * registry-MUTATING path (`hydrateExpandedViewItems`) could not simply be
- * widened — it is gated off for every org-scoped row (ADR-0005: the registry
- * is shared by every org a kernel serves) — and why #13407's actual repair was
- * a separate, registry-free, per-request expansion. The same reasoning applies
- * one exit over: `MetadataManager`'s registry is process-wide too, so the
- * repair for {@link MetadataManager.getViewsByObject} is a pure function over
- * what that one read already holds.
- */
-
-/**
- * Which object an aggregated view container binds to.
- *
- * The container's OWN top-level `object` field — `ViewSchema.object`,
- * documented there as "how a stack-level `views: [...]` entry says which object
- * its views belong to; read by `getViewsByObject()` / `GET /meta/view?object=`"
- * — is the authorial, explicit signal and is consulted FIRST (#13407). The
- * three-deep fallback below it is kept unchanged for every container written
- * before that field was read here: `list.data.object`, then `form.data.object`,
- * then the row's own `name` — which is the bound object only by convention, and
- * is why a container that set the top-level field but not `list.data.object`
- * used to bind under the wrong key or not at all.
- *
- * Returns `undefined` when no binding can be derived; every caller treats that
- * as "no expansion" rather than an error.
- */
-declare function deriveViewContainerObject(container: unknown): string | undefined;
-
-export { 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, deriveViewContainerObject, 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 };