fix(metadata): key loader-held items by the row key, not by body.name

.changeset/loader-item-row-key-identity.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": minor
+---
+
+fix(metadata): key loader-held items by the row key they were stored under, so a body with no top-level `name` is no longer dropped from `list()` (#14205)
+
+`MetadataManager.readListUncached()` — and its no-catch sibling
+`listForIndex()`, which builds the endpoint index — merged each loader's answer
+into the result set keyed by `body.name`, and admitted an item ONLY when the
+stored body carried a string `name`.
+
+A metadata body is not required to name itself. `register(type, name, data)`
+takes the key as its ARGUMENT, and `assertMetadataRegisterContract` says so in
+as many words: "A document with NO `name` of its own is fine — the argument is
+the key". An aggregated `defineView` container is exactly that shape — no own
+`name` by design, its identity being the target object, carried in the row's
+`name` COLUMN — and `DatabaseLoader.rowToData()` returns the stored body
+without folding the column into it.
+
+So a container written by `register('view', OBJECT, container)` lived in the
+registry for the life of the process and was written to `sys_metadata`, and
+then **disappeared at the next restart**: cold registry, only the loader
+answering, and `list('view')` refused the row. `listDiagnosed()` reported that
+short answer as complete (`degraded: false`) because no loader had thrown. Not
+scoped to views — any loader-held body with no top-level `name` was invisible.
+
+**The repair.** A loader-held item's identity is the key its store holds it
+under, so the manager now asks the loader for that key rather than guessing it
+from the body: `MetadataLoader` gains an OPTIONAL `loadManyKeyed()` returning
+`(name, body)` pairs, implemented by `DatabaseLoader` (from the row's `name`
+column) and `MemoryLoader` (from its storage map key). The key travels BESIDE
+the body and is never folded into it, so nothing synthesises a `name` into a
+body that deliberately has none and the register contract's refusal of a
+disagreeing `data.name` keeps meaning 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 entry; what is new is only the items the old
+gate refused. `loadManyKeyed()` is optional, and a loader without it (a
+`RemoteLoader`, whose wire format carries bodies only) falls back to the
+previous `body.name` keying unchanged — so no implementor of the published
+`MetadataLoader` interface needs to change.
+
+`MetadataManager.loadMany()` is deliberately untouched: its `body.name` test is
+a de-duplication guard, not an admission gate — a nameless item already fell
+past it and was returned — so it never carried this defect.

packages/metadata/src/index.ts

@@ -14,7 +14,7 @@ export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
-export { type MetadataLoader } from './loaders/loader-interface.js';
+export { type MetadataLoader, type MetadataKeyedItem } from './loaders/loader-interface.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
 export { RemoteLoader } from './loaders/remote-loader.js';
 export { DatabaseLoader, type DatabaseLoaderOptions } from './loaders/database-loader.js';

packages/metadata/src/loaders/database-loader.ts

@@ -23,7 +23,7 @@ import { SysMetadataObject, SysMetadataHistoryObject } from '@objectstack/metada
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { IDataDriver, IDataEngine, DriverQuery } from '@objectstack/spec/contracts';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 import { calculateChecksum } from '../utils/metadata-history-utils.js';
 import { LRUCache } from '../utils/lru-cache.js';
 // [#13279] Both predicates moved to `@objectstack/types` — see its
@@ -870,25 +870,43 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
- async loadMany<T = any>(
- type: string,
- _options?: MetadataLoadOptions
- ): Promise<T[]> {
+ /**
+ * 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 async readTypeRows(
+ type: string
+ ): Promise<Array<{ name: string | null; data: Record<string, unknown> }>> {
  await this.ensureSchema();
 
  if (this.loadManyCache) {
  const cached = this.loadManyCache.get(type);
- if (cached !== undefined) return cached as T[];
+ if (cached !== undefined) {
+ return cached as Array<{ name: string | null; data: Record<string, unknown> }>;
+ }
  }
 
  try {
  const rows = await this._find(this.tableName, {
  where: this.baseFilter(type),
  });
 
- const result = rows
- .map(row => this.rowToData(row))
- .filter((data): data is Record<string, unknown> => data !== null) as T[];
+ const result: Array<{ name: string | null; data: Record<string, unknown> }> = [];
+ for (const row of rows) {
+ const data = this.rowToData(row);
+ if (data === null) continue;
+ const name = row.name;
+ result.push({ name: typeof name === 'string' && name !== '' ? name : null, data });
+ }
 
  this.loadManyCache?.set(type, result);
  return result;
@@ -899,6 +917,37 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
+ async loadMany<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<T[]> {
+ return (await this.readTypeRows(type)).map(entry => entry.data) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const entries = await this.readTypeRows(type);
+ const keyed: MetadataKeyedItem<T>[] = [];
+ for (const entry of entries) {
+ if (entry.name === null) continue;
+ keyed.push({ name: entry.name, data: entry.data as T });
+ }
+ return keyed;
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  await this.ensureSchema();
 

packages/metadata/src/loaders/loader-interface.ts

@@ -15,6 +15,30 @@ import type {
  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
+/**
+ * [#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.
+ */
+export 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.
@@ -49,6 +73,38 @@ export interface MetadataLoader {
  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

packages/metadata/src/loaders/memory-loader.ts

@@ -15,7 +15,7 @@ import type {
  MetadataSaveOptions,
  MetadataSaveResult,
 } from '@objectstack/spec/system';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 
 export class MemoryLoader implements MetadataLoader {
  readonly contract: MetadataLoaderContract = {
@@ -61,6 +61,24 @@ export class MemoryLoader implements MetadataLoader {
  return Array.from(typeStore.values()) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const typeStore = this.storage.get(type);
+ if (!typeStore) return [];
+ return Array.from(typeStore, ([name, data]) => ({ name, data: data as T }));
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  return this.storage.get(type)?.has(name) ?? false;
  }

packages/metadata/src/metadata-manager-degraded-list-cache.test.ts

@@ -249,30 +249,52 @@ describe('#5184 — the issue repro: a healed store is not shadowed by the degra
  });
 });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
 describe('#5184 — the healthy TTL is untouched', () => {
  it('a complete read is still served from cache for the full 30s', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(names(await manager.list('permission'))).toEqual(['stored']);
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past the degraded TTL, nowhere near the healthy one.
  vi.advanceTimersByTime(ttls().degraded * 3);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Just short of 30s — still cached.
  vi.advanceTimersByTime(ttls().healthy - ttls().degraded * 3 - 1);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past 30s — re-read, exactly as before.
  vi.advanceTimersByTime(2);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(2);
+ expect(walks.count).toBe(2);
  });
 });
 
@@ -286,7 +308,7 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
  it('an empty complete read is cached too — there is no non-empty condition', async () => {
  const memory = new MemoryLoader();
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(await manager.list('permission')).toEqual([]);
  const entry = peekEntry(manager, 'permission');
@@ -296,6 +318,6 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
 
  // And it is served from cache, not re-read.
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  });
 });

packages/metadata/src/metadata-manager-list-diagnosed.test.ts

@@ -270,19 +270,41 @@ describe('#6504 — list() and listDiagnosed() are one read seen at two widths',
  expect((await working.listDiagnosed('permission')).items).toBe(workingItems);
  });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
  it('asking for the verdict costs no extra loader walk — one cache entry serves both', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Served from the entry the `list()` above filled — `listDiagnosed` is
  // the same read, not a second one.
  const diagnosed = await manager.listDiagnosed('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  expect(names(diagnosed.items)).toEqual(['stored']);
  expect(diagnosed.degraded).toBe(false);
  });

.changeset/loader-item-row-key-identity.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": minor
+---
+
+fix(metadata): key loader-held items by the row key they were stored under, so a body with no top-level `name` is no longer dropped from `list()` (#14205)
+
+`MetadataManager.readListUncached()` — and its no-catch sibling
+`listForIndex()`, which builds the endpoint index — merged each loader's answer
+into the result set keyed by `body.name`, and admitted an item ONLY when the
+stored body carried a string `name`.
+
+A metadata body is not required to name itself. `register(type, name, data)`
+takes the key as its ARGUMENT, and `assertMetadataRegisterContract` says so in
+as many words: "A document with NO `name` of its own is fine — the argument is
+the key". An aggregated `defineView` container is exactly that shape — no own
+`name` by design, its identity being the target object, carried in the row's
+`name` COLUMN — and `DatabaseLoader.rowToData()` returns the stored body
+without folding the column into it.
+
+So a container written by `register('view', OBJECT, container)` lived in the
+registry for the life of the process and was written to `sys_metadata`, and
+then **disappeared at the next restart**: cold registry, only the loader
+answering, and `list('view')` refused the row. `listDiagnosed()` reported that
+short answer as complete (`degraded: false`) because no loader had thrown. Not
+scoped to views — any loader-held body with no top-level `name` was invisible.
+
+**The repair.** A loader-held item's identity is the key its store holds it
+under, so the manager now asks the loader for that key rather than guessing it
+from the body: `MetadataLoader` gains an OPTIONAL `loadManyKeyed()` returning
+`(name, body)` pairs, implemented by `DatabaseLoader` (from the row's `name`
+column) and `MemoryLoader` (from its storage map key). The key travels BESIDE
+the body and is never folded into it, so nothing synthesises a `name` into a
+body that deliberately has none and the register contract's refusal of a
+disagreeing `data.name` keeps meaning 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 entry; what is new is only the items the old
+gate refused. `loadManyKeyed()` is optional, and a loader without it (a
+`RemoteLoader`, whose wire format carries bodies only) falls back to the
+previous `body.name` keying unchanged — so no implementor of the published
+`MetadataLoader` interface needs to change.
+
+`MetadataManager.loadMany()` is deliberately untouched: its `body.name` test is
+a de-duplication guard, not an admission gate — a nameless item already fell
+past it and was returned — so it never carried this defect.

packages/metadata/src/index.ts

@@ -14,7 +14,7 @@ export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
-export { type MetadataLoader } from './loaders/loader-interface.js';
+export { type MetadataLoader, type MetadataKeyedItem } from './loaders/loader-interface.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
 export { RemoteLoader } from './loaders/remote-loader.js';
 export { DatabaseLoader, type DatabaseLoaderOptions } from './loaders/database-loader.js';

packages/metadata/src/loaders/database-loader.ts

@@ -23,7 +23,7 @@ import { SysMetadataObject, SysMetadataHistoryObject } from '@objectstack/metada
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { IDataDriver, IDataEngine, DriverQuery } from '@objectstack/spec/contracts';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 import { calculateChecksum } from '../utils/metadata-history-utils.js';
 import { LRUCache } from '../utils/lru-cache.js';
 // [#13279] Both predicates moved to `@objectstack/types` — see its
@@ -870,25 +870,43 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
- async loadMany<T = any>(
- type: string,
- _options?: MetadataLoadOptions
- ): Promise<T[]> {
+ /**
+ * 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 async readTypeRows(
+ type: string
+ ): Promise<Array<{ name: string | null; data: Record<string, unknown> }>> {
  await this.ensureSchema();
 
  if (this.loadManyCache) {
  const cached = this.loadManyCache.get(type);
- if (cached !== undefined) return cached as T[];
+ if (cached !== undefined) {
+ return cached as Array<{ name: string | null; data: Record<string, unknown> }>;
+ }
  }
 
  try {
  const rows = await this._find(this.tableName, {
  where: this.baseFilter(type),
  });
 
- const result = rows
- .map(row => this.rowToData(row))
- .filter((data): data is Record<string, unknown> => data !== null) as T[];
+ const result: Array<{ name: string | null; data: Record<string, unknown> }> = [];
+ for (const row of rows) {
+ const data = this.rowToData(row);
+ if (data === null) continue;
+ const name = row.name;
+ result.push({ name: typeof name === 'string' && name !== '' ? name : null, data });
+ }
 
  this.loadManyCache?.set(type, result);
  return result;
@@ -899,6 +917,37 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
+ async loadMany<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<T[]> {
+ return (await this.readTypeRows(type)).map(entry => entry.data) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const entries = await this.readTypeRows(type);
+ const keyed: MetadataKeyedItem<T>[] = [];
+ for (const entry of entries) {
+ if (entry.name === null) continue;
+ keyed.push({ name: entry.name, data: entry.data as T });
+ }
+ return keyed;
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  await this.ensureSchema();
 

packages/metadata/src/loaders/loader-interface.ts

@@ -15,6 +15,30 @@ import type {
  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
+/**
+ * [#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.
+ */
+export 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.
@@ -49,6 +73,38 @@ export interface MetadataLoader {
  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

packages/metadata/src/loaders/memory-loader.ts

@@ -15,7 +15,7 @@ import type {
  MetadataSaveOptions,
  MetadataSaveResult,
 } from '@objectstack/spec/system';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 
 export class MemoryLoader implements MetadataLoader {
  readonly contract: MetadataLoaderContract = {
@@ -61,6 +61,24 @@ export class MemoryLoader implements MetadataLoader {
  return Array.from(typeStore.values()) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const typeStore = this.storage.get(type);
+ if (!typeStore) return [];
+ return Array.from(typeStore, ([name, data]) => ({ name, data: data as T }));
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  return this.storage.get(type)?.has(name) ?? false;
  }

packages/metadata/src/metadata-manager-degraded-list-cache.test.ts

@@ -249,30 +249,52 @@ describe('#5184 — the issue repro: a healed store is not shadowed by the degra
  });
 });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
 describe('#5184 — the healthy TTL is untouched', () => {
  it('a complete read is still served from cache for the full 30s', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(names(await manager.list('permission'))).toEqual(['stored']);
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past the degraded TTL, nowhere near the healthy one.
  vi.advanceTimersByTime(ttls().degraded * 3);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Just short of 30s — still cached.
  vi.advanceTimersByTime(ttls().healthy - ttls().degraded * 3 - 1);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past 30s — re-read, exactly as before.
  vi.advanceTimersByTime(2);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(2);
+ expect(walks.count).toBe(2);
  });
 });
 
@@ -286,7 +308,7 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
  it('an empty complete read is cached too — there is no non-empty condition', async () => {
  const memory = new MemoryLoader();
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(await manager.list('permission')).toEqual([]);
  const entry = peekEntry(manager, 'permission');
@@ -296,6 +318,6 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
 
  // And it is served from cache, not re-read.
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  });
 });

packages/metadata/src/metadata-manager-list-diagnosed.test.ts

@@ -270,19 +270,41 @@ describe('#6504 — list() and listDiagnosed() are one read seen at two widths',
  expect((await working.listDiagnosed('permission')).items).toBe(workingItems);
  });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
  it('asking for the verdict costs no extra loader walk — one cache entry serves both', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Served from the entry the `list()` above filled — `listDiagnosed` is
  // the same read, not a second one.
  const diagnosed = await manager.listDiagnosed('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  expect(names(diagnosed.items)).toEqual(['stored']);
  expect(diagnosed.degraded).toBe(false);
  });

.changeset/loader-item-row-key-identity.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": minor
+---
+
+fix(metadata): key loader-held items by the row key they were stored under, so a body with no top-level `name` is no longer dropped from `list()` (#14205)
+
+`MetadataManager.readListUncached()` — and its no-catch sibling
+`listForIndex()`, which builds the endpoint index — merged each loader's answer
+into the result set keyed by `body.name`, and admitted an item ONLY when the
+stored body carried a string `name`.
+
+A metadata body is not required to name itself. `register(type, name, data)`
+takes the key as its ARGUMENT, and `assertMetadataRegisterContract` says so in
+as many words: "A document with NO `name` of its own is fine — the argument is
+the key". An aggregated `defineView` container is exactly that shape — no own
+`name` by design, its identity being the target object, carried in the row's
+`name` COLUMN — and `DatabaseLoader.rowToData()` returns the stored body
+without folding the column into it.
+
+So a container written by `register('view', OBJECT, container)` lived in the
+registry for the life of the process and was written to `sys_metadata`, and
+then **disappeared at the next restart**: cold registry, only the loader
+answering, and `list('view')` refused the row. `listDiagnosed()` reported that
+short answer as complete (`degraded: false`) because no loader had thrown. Not
+scoped to views — any loader-held body with no top-level `name` was invisible.
+
+**The repair.** A loader-held item's identity is the key its store holds it
+under, so the manager now asks the loader for that key rather than guessing it
+from the body: `MetadataLoader` gains an OPTIONAL `loadManyKeyed()` returning
+`(name, body)` pairs, implemented by `DatabaseLoader` (from the row's `name`
+column) and `MemoryLoader` (from its storage map key). The key travels BESIDE
+the body and is never folded into it, so nothing synthesises a `name` into a
+body that deliberately has none and the register contract's refusal of a
+disagreeing `data.name` keeps meaning 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 entry; what is new is only the items the old
+gate refused. `loadManyKeyed()` is optional, and a loader without it (a
+`RemoteLoader`, whose wire format carries bodies only) falls back to the
+previous `body.name` keying unchanged — so no implementor of the published
+`MetadataLoader` interface needs to change.
+
+`MetadataManager.loadMany()` is deliberately untouched: its `body.name` test is
+a de-duplication guard, not an admission gate — a nameless item already fell
+past it and was returned — so it never carried this defect.

packages/metadata/src/index.ts

@@ -14,7 +14,7 @@ export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
-export { type MetadataLoader } from './loaders/loader-interface.js';
+export { type MetadataLoader, type MetadataKeyedItem } from './loaders/loader-interface.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
 export { RemoteLoader } from './loaders/remote-loader.js';
 export { DatabaseLoader, type DatabaseLoaderOptions } from './loaders/database-loader.js';

packages/metadata/src/loaders/database-loader.ts

@@ -23,7 +23,7 @@ import { SysMetadataObject, SysMetadataHistoryObject } from '@objectstack/metada
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { IDataDriver, IDataEngine, DriverQuery } from '@objectstack/spec/contracts';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 import { calculateChecksum } from '../utils/metadata-history-utils.js';
 import { LRUCache } from '../utils/lru-cache.js';
 // [#13279] Both predicates moved to `@objectstack/types` — see its
@@ -870,25 +870,43 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
- async loadMany<T = any>(
- type: string,
- _options?: MetadataLoadOptions
- ): Promise<T[]> {
+ /**
+ * 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 async readTypeRows(
+ type: string
+ ): Promise<Array<{ name: string | null; data: Record<string, unknown> }>> {
  await this.ensureSchema();
 
  if (this.loadManyCache) {
  const cached = this.loadManyCache.get(type);
- if (cached !== undefined) return cached as T[];
+ if (cached !== undefined) {
+ return cached as Array<{ name: string | null; data: Record<string, unknown> }>;
+ }
  }
 
  try {
  const rows = await this._find(this.tableName, {
  where: this.baseFilter(type),
  });
 
- const result = rows
- .map(row => this.rowToData(row))
- .filter((data): data is Record<string, unknown> => data !== null) as T[];
+ const result: Array<{ name: string | null; data: Record<string, unknown> }> = [];
+ for (const row of rows) {
+ const data = this.rowToData(row);
+ if (data === null) continue;
+ const name = row.name;
+ result.push({ name: typeof name === 'string' && name !== '' ? name : null, data });
+ }
 
  this.loadManyCache?.set(type, result);
  return result;
@@ -899,6 +917,37 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
+ async loadMany<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<T[]> {
+ return (await this.readTypeRows(type)).map(entry => entry.data) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const entries = await this.readTypeRows(type);
+ const keyed: MetadataKeyedItem<T>[] = [];
+ for (const entry of entries) {
+ if (entry.name === null) continue;
+ keyed.push({ name: entry.name, data: entry.data as T });
+ }
+ return keyed;
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  await this.ensureSchema();
 

packages/metadata/src/loaders/loader-interface.ts

@@ -15,6 +15,30 @@ import type {
  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
+/**
+ * [#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.
+ */
+export 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.
@@ -49,6 +73,38 @@ export interface MetadataLoader {
  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

packages/metadata/src/loaders/memory-loader.ts

@@ -15,7 +15,7 @@ import type {
  MetadataSaveOptions,
  MetadataSaveResult,
 } from '@objectstack/spec/system';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 
 export class MemoryLoader implements MetadataLoader {
  readonly contract: MetadataLoaderContract = {
@@ -61,6 +61,24 @@ export class MemoryLoader implements MetadataLoader {
  return Array.from(typeStore.values()) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const typeStore = this.storage.get(type);
+ if (!typeStore) return [];
+ return Array.from(typeStore, ([name, data]) => ({ name, data: data as T }));
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  return this.storage.get(type)?.has(name) ?? false;
  }

packages/metadata/src/metadata-manager-degraded-list-cache.test.ts

@@ -249,30 +249,52 @@ describe('#5184 — the issue repro: a healed store is not shadowed by the degra
  });
 });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
 describe('#5184 — the healthy TTL is untouched', () => {
  it('a complete read is still served from cache for the full 30s', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(names(await manager.list('permission'))).toEqual(['stored']);
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past the degraded TTL, nowhere near the healthy one.
  vi.advanceTimersByTime(ttls().degraded * 3);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Just short of 30s — still cached.
  vi.advanceTimersByTime(ttls().healthy - ttls().degraded * 3 - 1);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past 30s — re-read, exactly as before.
  vi.advanceTimersByTime(2);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(2);
+ expect(walks.count).toBe(2);
  });
 });
 
@@ -286,7 +308,7 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
  it('an empty complete read is cached too — there is no non-empty condition', async () => {
  const memory = new MemoryLoader();
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(await manager.list('permission')).toEqual([]);
  const entry = peekEntry(manager, 'permission');
@@ -296,6 +318,6 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
 
  // And it is served from cache, not re-read.
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  });
 });

packages/metadata/src/metadata-manager-list-diagnosed.test.ts

@@ -270,19 +270,41 @@ describe('#6504 — list() and listDiagnosed() are one read seen at two widths',
  expect((await working.listDiagnosed('permission')).items).toBe(workingItems);
  });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
  it('asking for the verdict costs no extra loader walk — one cache entry serves both', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Served from the entry the `list()` above filled — `listDiagnosed` is
  // the same read, not a second one.
  const diagnosed = await manager.listDiagnosed('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  expect(names(diagnosed.items)).toEqual(['stored']);
  expect(diagnosed.degraded).toBe(false);
  });

.changeset/loader-item-row-key-identity.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": minor
+---
+
+fix(metadata): key loader-held items by the row key they were stored under, so a body with no top-level `name` is no longer dropped from `list()` (#14205)
+
+`MetadataManager.readListUncached()` — and its no-catch sibling
+`listForIndex()`, which builds the endpoint index — merged each loader's answer
+into the result set keyed by `body.name`, and admitted an item ONLY when the
+stored body carried a string `name`.
+
+A metadata body is not required to name itself. `register(type, name, data)`
+takes the key as its ARGUMENT, and `assertMetadataRegisterContract` says so in
+as many words: "A document with NO `name` of its own is fine — the argument is
+the key". An aggregated `defineView` container is exactly that shape — no own
+`name` by design, its identity being the target object, carried in the row's
+`name` COLUMN — and `DatabaseLoader.rowToData()` returns the stored body
+without folding the column into it.
+
+So a container written by `register('view', OBJECT, container)` lived in the
+registry for the life of the process and was written to `sys_metadata`, and
+then **disappeared at the next restart**: cold registry, only the loader
+answering, and `list('view')` refused the row. `listDiagnosed()` reported that
+short answer as complete (`degraded: false`) because no loader had thrown. Not
+scoped to views — any loader-held body with no top-level `name` was invisible.
+
+**The repair.** A loader-held item's identity is the key its store holds it
+under, so the manager now asks the loader for that key rather than guessing it
+from the body: `MetadataLoader` gains an OPTIONAL `loadManyKeyed()` returning
+`(name, body)` pairs, implemented by `DatabaseLoader` (from the row's `name`
+column) and `MemoryLoader` (from its storage map key). The key travels BESIDE
+the body and is never folded into it, so nothing synthesises a `name` into a
+body that deliberately has none and the register contract's refusal of a
+disagreeing `data.name` keeps meaning 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 entry; what is new is only the items the old
+gate refused. `loadManyKeyed()` is optional, and a loader without it (a
+`RemoteLoader`, whose wire format carries bodies only) falls back to the
+previous `body.name` keying unchanged — so no implementor of the published
+`MetadataLoader` interface needs to change.
+
+`MetadataManager.loadMany()` is deliberately untouched: its `body.name` test is
+a de-duplication guard, not an admission gate — a nameless item already fell
+past it and was returned — so it never carried this defect.

packages/metadata/src/index.ts

@@ -14,7 +14,7 @@ export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
-export { type MetadataLoader } from './loaders/loader-interface.js';
+export { type MetadataLoader, type MetadataKeyedItem } from './loaders/loader-interface.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
 export { RemoteLoader } from './loaders/remote-loader.js';
 export { DatabaseLoader, type DatabaseLoaderOptions } from './loaders/database-loader.js';

packages/metadata/src/loaders/database-loader.ts

@@ -23,7 +23,7 @@ import { SysMetadataObject, SysMetadataHistoryObject } from '@objectstack/metada
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { IDataDriver, IDataEngine, DriverQuery } from '@objectstack/spec/contracts';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 import { calculateChecksum } from '../utils/metadata-history-utils.js';
 import { LRUCache } from '../utils/lru-cache.js';
 // [#13279] Both predicates moved to `@objectstack/types` — see its
@@ -870,25 +870,43 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
- async loadMany<T = any>(
- type: string,
- _options?: MetadataLoadOptions
- ): Promise<T[]> {
+ /**
+ * 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 async readTypeRows(
+ type: string
+ ): Promise<Array<{ name: string | null; data: Record<string, unknown> }>> {
  await this.ensureSchema();
 
  if (this.loadManyCache) {
  const cached = this.loadManyCache.get(type);
- if (cached !== undefined) return cached as T[];
+ if (cached !== undefined) {
+ return cached as Array<{ name: string | null; data: Record<string, unknown> }>;
+ }
  }
 
  try {
  const rows = await this._find(this.tableName, {
  where: this.baseFilter(type),
  });
 
- const result = rows
- .map(row => this.rowToData(row))
- .filter((data): data is Record<string, unknown> => data !== null) as T[];
+ const result: Array<{ name: string | null; data: Record<string, unknown> }> = [];
+ for (const row of rows) {
+ const data = this.rowToData(row);
+ if (data === null) continue;
+ const name = row.name;
+ result.push({ name: typeof name === 'string' && name !== '' ? name : null, data });
+ }
 
  this.loadManyCache?.set(type, result);
  return result;
@@ -899,6 +917,37 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
+ async loadMany<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<T[]> {
+ return (await this.readTypeRows(type)).map(entry => entry.data) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const entries = await this.readTypeRows(type);
+ const keyed: MetadataKeyedItem<T>[] = [];
+ for (const entry of entries) {
+ if (entry.name === null) continue;
+ keyed.push({ name: entry.name, data: entry.data as T });
+ }
+ return keyed;
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  await this.ensureSchema();
 

packages/metadata/src/loaders/loader-interface.ts

@@ -15,6 +15,30 @@ import type {
  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
+/**
+ * [#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.
+ */
+export 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.
@@ -49,6 +73,38 @@ export interface MetadataLoader {
  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

packages/metadata/src/loaders/memory-loader.ts

@@ -15,7 +15,7 @@ import type {
  MetadataSaveOptions,
  MetadataSaveResult,
 } from '@objectstack/spec/system';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 
 export class MemoryLoader implements MetadataLoader {
  readonly contract: MetadataLoaderContract = {
@@ -61,6 +61,24 @@ export class MemoryLoader implements MetadataLoader {
  return Array.from(typeStore.values()) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const typeStore = this.storage.get(type);
+ if (!typeStore) return [];
+ return Array.from(typeStore, ([name, data]) => ({ name, data: data as T }));
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  return this.storage.get(type)?.has(name) ?? false;
  }

packages/metadata/src/metadata-manager-degraded-list-cache.test.ts

@@ -249,30 +249,52 @@ describe('#5184 — the issue repro: a healed store is not shadowed by the degra
  });
 });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
 describe('#5184 — the healthy TTL is untouched', () => {
  it('a complete read is still served from cache for the full 30s', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(names(await manager.list('permission'))).toEqual(['stored']);
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past the degraded TTL, nowhere near the healthy one.
  vi.advanceTimersByTime(ttls().degraded * 3);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Just short of 30s — still cached.
  vi.advanceTimersByTime(ttls().healthy - ttls().degraded * 3 - 1);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past 30s — re-read, exactly as before.
  vi.advanceTimersByTime(2);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(2);
+ expect(walks.count).toBe(2);
  });
 });
 
@@ -286,7 +308,7 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
  it('an empty complete read is cached too — there is no non-empty condition', async () => {
  const memory = new MemoryLoader();
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(await manager.list('permission')).toEqual([]);
  const entry = peekEntry(manager, 'permission');
@@ -296,6 +318,6 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
 
  // And it is served from cache, not re-read.
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  });
 });

packages/metadata/src/metadata-manager-list-diagnosed.test.ts

@@ -270,19 +270,41 @@ describe('#6504 — list() and listDiagnosed() are one read seen at two widths',
  expect((await working.listDiagnosed('permission')).items).toBe(workingItems);
  });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
  it('asking for the verdict costs no extra loader walk — one cache entry serves both', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Served from the entry the `list()` above filled — `listDiagnosed` is
  // the same read, not a second one.
  const diagnosed = await manager.listDiagnosed('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  expect(names(diagnosed.items)).toEqual(['stored']);
  expect(diagnosed.degraded).toBe(false);
  });

.changeset/loader-item-row-key-identity.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": minor
+---
+
+fix(metadata): key loader-held items by the row key they were stored under, so a body with no top-level `name` is no longer dropped from `list()` (#14205)
+
+`MetadataManager.readListUncached()` — and its no-catch sibling
+`listForIndex()`, which builds the endpoint index — merged each loader's answer
+into the result set keyed by `body.name`, and admitted an item ONLY when the
+stored body carried a string `name`.
+
+A metadata body is not required to name itself. `register(type, name, data)`
+takes the key as its ARGUMENT, and `assertMetadataRegisterContract` says so in
+as many words: "A document with NO `name` of its own is fine — the argument is
+the key". An aggregated `defineView` container is exactly that shape — no own
+`name` by design, its identity being the target object, carried in the row's
+`name` COLUMN — and `DatabaseLoader.rowToData()` returns the stored body
+without folding the column into it.
+
+So a container written by `register('view', OBJECT, container)` lived in the
+registry for the life of the process and was written to `sys_metadata`, and
+then **disappeared at the next restart**: cold registry, only the loader
+answering, and `list('view')` refused the row. `listDiagnosed()` reported that
+short answer as complete (`degraded: false`) because no loader had thrown. Not
+scoped to views — any loader-held body with no top-level `name` was invisible.
+
+**The repair.** A loader-held item's identity is the key its store holds it
+under, so the manager now asks the loader for that key rather than guessing it
+from the body: `MetadataLoader` gains an OPTIONAL `loadManyKeyed()` returning
+`(name, body)` pairs, implemented by `DatabaseLoader` (from the row's `name`
+column) and `MemoryLoader` (from its storage map key). The key travels BESIDE
+the body and is never folded into it, so nothing synthesises a `name` into a
+body that deliberately has none and the register contract's refusal of a
+disagreeing `data.name` keeps meaning 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 entry; what is new is only the items the old
+gate refused. `loadManyKeyed()` is optional, and a loader without it (a
+`RemoteLoader`, whose wire format carries bodies only) falls back to the
+previous `body.name` keying unchanged — so no implementor of the published
+`MetadataLoader` interface needs to change.
+
+`MetadataManager.loadMany()` is deliberately untouched: its `body.name` test is
+a de-duplication guard, not an admission gate — a nameless item already fell
+past it and was returned — so it never carried this defect.

packages/metadata/src/index.ts

@@ -14,7 +14,7 @@ export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
-export { type MetadataLoader } from './loaders/loader-interface.js';
+export { type MetadataLoader, type MetadataKeyedItem } from './loaders/loader-interface.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
 export { RemoteLoader } from './loaders/remote-loader.js';
 export { DatabaseLoader, type DatabaseLoaderOptions } from './loaders/database-loader.js';

packages/metadata/src/loaders/database-loader.ts

@@ -23,7 +23,7 @@ import { SysMetadataObject, SysMetadataHistoryObject } from '@objectstack/metada
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { IDataDriver, IDataEngine, DriverQuery } from '@objectstack/spec/contracts';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 import { calculateChecksum } from '../utils/metadata-history-utils.js';
 import { LRUCache } from '../utils/lru-cache.js';
 // [#13279] Both predicates moved to `@objectstack/types` — see its
@@ -870,25 +870,43 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
- async loadMany<T = any>(
- type: string,
- _options?: MetadataLoadOptions
- ): Promise<T[]> {
+ /**
+ * 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 async readTypeRows(
+ type: string
+ ): Promise<Array<{ name: string | null; data: Record<string, unknown> }>> {
  await this.ensureSchema();
 
  if (this.loadManyCache) {
  const cached = this.loadManyCache.get(type);
- if (cached !== undefined) return cached as T[];
+ if (cached !== undefined) {
+ return cached as Array<{ name: string | null; data: Record<string, unknown> }>;
+ }
  }
 
  try {
  const rows = await this._find(this.tableName, {
  where: this.baseFilter(type),
  });
 
- const result = rows
- .map(row => this.rowToData(row))
- .filter((data): data is Record<string, unknown> => data !== null) as T[];
+ const result: Array<{ name: string | null; data: Record<string, unknown> }> = [];
+ for (const row of rows) {
+ const data = this.rowToData(row);
+ if (data === null) continue;
+ const name = row.name;
+ result.push({ name: typeof name === 'string' && name !== '' ? name : null, data });
+ }
 
  this.loadManyCache?.set(type, result);
  return result;
@@ -899,6 +917,37 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
+ async loadMany<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<T[]> {
+ return (await this.readTypeRows(type)).map(entry => entry.data) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const entries = await this.readTypeRows(type);
+ const keyed: MetadataKeyedItem<T>[] = [];
+ for (const entry of entries) {
+ if (entry.name === null) continue;
+ keyed.push({ name: entry.name, data: entry.data as T });
+ }
+ return keyed;
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  await this.ensureSchema();
 

packages/metadata/src/loaders/loader-interface.ts

@@ -15,6 +15,30 @@ import type {
  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
+/**
+ * [#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.
+ */
+export 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.
@@ -49,6 +73,38 @@ export interface MetadataLoader {
  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

packages/metadata/src/loaders/memory-loader.ts

@@ -15,7 +15,7 @@ import type {
  MetadataSaveOptions,
  MetadataSaveResult,
 } from '@objectstack/spec/system';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 
 export class MemoryLoader implements MetadataLoader {
  readonly contract: MetadataLoaderContract = {
@@ -61,6 +61,24 @@ export class MemoryLoader implements MetadataLoader {
  return Array.from(typeStore.values()) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const typeStore = this.storage.get(type);
+ if (!typeStore) return [];
+ return Array.from(typeStore, ([name, data]) => ({ name, data: data as T }));
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  return this.storage.get(type)?.has(name) ?? false;
  }

packages/metadata/src/metadata-manager-degraded-list-cache.test.ts

@@ -249,30 +249,52 @@ describe('#5184 — the issue repro: a healed store is not shadowed by the degra
  });
 });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
 describe('#5184 — the healthy TTL is untouched', () => {
  it('a complete read is still served from cache for the full 30s', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(names(await manager.list('permission'))).toEqual(['stored']);
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past the degraded TTL, nowhere near the healthy one.
  vi.advanceTimersByTime(ttls().degraded * 3);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Just short of 30s — still cached.
  vi.advanceTimersByTime(ttls().healthy - ttls().degraded * 3 - 1);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past 30s — re-read, exactly as before.
  vi.advanceTimersByTime(2);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(2);
+ expect(walks.count).toBe(2);
  });
 });
 
@@ -286,7 +308,7 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
  it('an empty complete read is cached too — there is no non-empty condition', async () => {
  const memory = new MemoryLoader();
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(await manager.list('permission')).toEqual([]);
  const entry = peekEntry(manager, 'permission');
@@ -296,6 +318,6 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
 
  // And it is served from cache, not re-read.
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  });
 });

packages/metadata/src/metadata-manager-list-diagnosed.test.ts

@@ -270,19 +270,41 @@ describe('#6504 — list() and listDiagnosed() are one read seen at two widths',
  expect((await working.listDiagnosed('permission')).items).toBe(workingItems);
  });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
  it('asking for the verdict costs no extra loader walk — one cache entry serves both', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Served from the entry the `list()` above filled — `listDiagnosed` is
  // the same read, not a second one.
  const diagnosed = await manager.listDiagnosed('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  expect(names(diagnosed.items)).toEqual(['stored']);
  expect(diagnosed.degraded).toBe(false);
  });

.changeset/loader-item-row-key-identity.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": minor
+---
+
+fix(metadata): key loader-held items by the row key they were stored under, so a body with no top-level `name` is no longer dropped from `list()` (#14205)
+
+`MetadataManager.readListUncached()` — and its no-catch sibling
+`listForIndex()`, which builds the endpoint index — merged each loader's answer
+into the result set keyed by `body.name`, and admitted an item ONLY when the
+stored body carried a string `name`.
+
+A metadata body is not required to name itself. `register(type, name, data)`
+takes the key as its ARGUMENT, and `assertMetadataRegisterContract` says so in
+as many words: "A document with NO `name` of its own is fine — the argument is
+the key". An aggregated `defineView` container is exactly that shape — no own
+`name` by design, its identity being the target object, carried in the row's
+`name` COLUMN — and `DatabaseLoader.rowToData()` returns the stored body
+without folding the column into it.
+
+So a container written by `register('view', OBJECT, container)` lived in the
+registry for the life of the process and was written to `sys_metadata`, and
+then **disappeared at the next restart**: cold registry, only the loader
+answering, and `list('view')` refused the row. `listDiagnosed()` reported that
+short answer as complete (`degraded: false`) because no loader had thrown. Not
+scoped to views — any loader-held body with no top-level `name` was invisible.
+
+**The repair.** A loader-held item's identity is the key its store holds it
+under, so the manager now asks the loader for that key rather than guessing it
+from the body: `MetadataLoader` gains an OPTIONAL `loadManyKeyed()` returning
+`(name, body)` pairs, implemented by `DatabaseLoader` (from the row's `name`
+column) and `MemoryLoader` (from its storage map key). The key travels BESIDE
+the body and is never folded into it, so nothing synthesises a `name` into a
+body that deliberately has none and the register contract's refusal of a
+disagreeing `data.name` keeps meaning 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 entry; what is new is only the items the old
+gate refused. `loadManyKeyed()` is optional, and a loader without it (a
+`RemoteLoader`, whose wire format carries bodies only) falls back to the
+previous `body.name` keying unchanged — so no implementor of the published
+`MetadataLoader` interface needs to change.
+
+`MetadataManager.loadMany()` is deliberately untouched: its `body.name` test is
+a de-duplication guard, not an admission gate — a nameless item already fell
+past it and was returned — so it never carried this defect.

packages/metadata/src/index.ts

@@ -14,7 +14,7 @@ export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
-export { type MetadataLoader } from './loaders/loader-interface.js';
+export { type MetadataLoader, type MetadataKeyedItem } from './loaders/loader-interface.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
 export { RemoteLoader } from './loaders/remote-loader.js';
 export { DatabaseLoader, type DatabaseLoaderOptions } from './loaders/database-loader.js';

packages/metadata/src/loaders/database-loader.ts

@@ -23,7 +23,7 @@ import { SysMetadataObject, SysMetadataHistoryObject } from '@objectstack/metada
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { IDataDriver, IDataEngine, DriverQuery } from '@objectstack/spec/contracts';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 import { calculateChecksum } from '../utils/metadata-history-utils.js';
 import { LRUCache } from '../utils/lru-cache.js';
 // [#13279] Both predicates moved to `@objectstack/types` — see its
@@ -870,25 +870,43 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
- async loadMany<T = any>(
- type: string,
- _options?: MetadataLoadOptions
- ): Promise<T[]> {
+ /**
+ * 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 async readTypeRows(
+ type: string
+ ): Promise<Array<{ name: string | null; data: Record<string, unknown> }>> {
  await this.ensureSchema();
 
  if (this.loadManyCache) {
  const cached = this.loadManyCache.get(type);
- if (cached !== undefined) return cached as T[];
+ if (cached !== undefined) {
+ return cached as Array<{ name: string | null; data: Record<string, unknown> }>;
+ }
  }
 
  try {
  const rows = await this._find(this.tableName, {
  where: this.baseFilter(type),
  });
 
- const result = rows
- .map(row => this.rowToData(row))
- .filter((data): data is Record<string, unknown> => data !== null) as T[];
+ const result: Array<{ name: string | null; data: Record<string, unknown> }> = [];
+ for (const row of rows) {
+ const data = this.rowToData(row);
+ if (data === null) continue;
+ const name = row.name;
+ result.push({ name: typeof name === 'string' && name !== '' ? name : null, data });
+ }
 
  this.loadManyCache?.set(type, result);
  return result;
@@ -899,6 +917,37 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
+ async loadMany<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<T[]> {
+ return (await this.readTypeRows(type)).map(entry => entry.data) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const entries = await this.readTypeRows(type);
+ const keyed: MetadataKeyedItem<T>[] = [];
+ for (const entry of entries) {
+ if (entry.name === null) continue;
+ keyed.push({ name: entry.name, data: entry.data as T });
+ }
+ return keyed;
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  await this.ensureSchema();
 

packages/metadata/src/loaders/loader-interface.ts

@@ -15,6 +15,30 @@ import type {
  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
+/**
+ * [#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.
+ */
+export 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.
@@ -49,6 +73,38 @@ export interface MetadataLoader {
  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

packages/metadata/src/loaders/memory-loader.ts

@@ -15,7 +15,7 @@ import type {
  MetadataSaveOptions,
  MetadataSaveResult,
 } from '@objectstack/spec/system';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 
 export class MemoryLoader implements MetadataLoader {
  readonly contract: MetadataLoaderContract = {
@@ -61,6 +61,24 @@ export class MemoryLoader implements MetadataLoader {
  return Array.from(typeStore.values()) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const typeStore = this.storage.get(type);
+ if (!typeStore) return [];
+ return Array.from(typeStore, ([name, data]) => ({ name, data: data as T }));
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  return this.storage.get(type)?.has(name) ?? false;
  }

packages/metadata/src/metadata-manager-degraded-list-cache.test.ts

@@ -249,30 +249,52 @@ describe('#5184 — the issue repro: a healed store is not shadowed by the degra
  });
 });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
 describe('#5184 — the healthy TTL is untouched', () => {
  it('a complete read is still served from cache for the full 30s', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(names(await manager.list('permission'))).toEqual(['stored']);
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past the degraded TTL, nowhere near the healthy one.
  vi.advanceTimersByTime(ttls().degraded * 3);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Just short of 30s — still cached.
  vi.advanceTimersByTime(ttls().healthy - ttls().degraded * 3 - 1);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past 30s — re-read, exactly as before.
  vi.advanceTimersByTime(2);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(2);
+ expect(walks.count).toBe(2);
  });
 });
 
@@ -286,7 +308,7 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
  it('an empty complete read is cached too — there is no non-empty condition', async () => {
  const memory = new MemoryLoader();
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(await manager.list('permission')).toEqual([]);
  const entry = peekEntry(manager, 'permission');
@@ -296,6 +318,6 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
 
  // And it is served from cache, not re-read.
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  });
 });

packages/metadata/src/metadata-manager-list-diagnosed.test.ts

@@ -270,19 +270,41 @@ describe('#6504 — list() and listDiagnosed() are one read seen at two widths',
  expect((await working.listDiagnosed('permission')).items).toBe(workingItems);
  });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
  it('asking for the verdict costs no extra loader walk — one cache entry serves both', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Served from the entry the `list()` above filled — `listDiagnosed` is
  // the same read, not a second one.
  const diagnosed = await manager.listDiagnosed('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  expect(names(diagnosed.items)).toEqual(['stored']);
  expect(diagnosed.degraded).toBe(false);
  });

.changeset/loader-item-row-key-identity.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": minor
+---
+
+fix(metadata): key loader-held items by the row key they were stored under, so a body with no top-level `name` is no longer dropped from `list()` (#14205)
+
+`MetadataManager.readListUncached()` — and its no-catch sibling
+`listForIndex()`, which builds the endpoint index — merged each loader's answer
+into the result set keyed by `body.name`, and admitted an item ONLY when the
+stored body carried a string `name`.
+
+A metadata body is not required to name itself. `register(type, name, data)`
+takes the key as its ARGUMENT, and `assertMetadataRegisterContract` says so in
+as many words: "A document with NO `name` of its own is fine — the argument is
+the key". An aggregated `defineView` container is exactly that shape — no own
+`name` by design, its identity being the target object, carried in the row's
+`name` COLUMN — and `DatabaseLoader.rowToData()` returns the stored body
+without folding the column into it.
+
+So a container written by `register('view', OBJECT, container)` lived in the
+registry for the life of the process and was written to `sys_metadata`, and
+then **disappeared at the next restart**: cold registry, only the loader
+answering, and `list('view')` refused the row. `listDiagnosed()` reported that
+short answer as complete (`degraded: false`) because no loader had thrown. Not
+scoped to views — any loader-held body with no top-level `name` was invisible.
+
+**The repair.** A loader-held item's identity is the key its store holds it
+under, so the manager now asks the loader for that key rather than guessing it
+from the body: `MetadataLoader` gains an OPTIONAL `loadManyKeyed()` returning
+`(name, body)` pairs, implemented by `DatabaseLoader` (from the row's `name`
+column) and `MemoryLoader` (from its storage map key). The key travels BESIDE
+the body and is never folded into it, so nothing synthesises a `name` into a
+body that deliberately has none and the register contract's refusal of a
+disagreeing `data.name` keeps meaning 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 entry; what is new is only the items the old
+gate refused. `loadManyKeyed()` is optional, and a loader without it (a
+`RemoteLoader`, whose wire format carries bodies only) falls back to the
+previous `body.name` keying unchanged — so no implementor of the published
+`MetadataLoader` interface needs to change.
+
+`MetadataManager.loadMany()` is deliberately untouched: its `body.name` test is
+a de-duplication guard, not an admission gate — a nameless item already fell
+past it and was returned — so it never carried this defect.

packages/metadata/src/index.ts

@@ -14,7 +14,7 @@ export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
-export { type MetadataLoader } from './loaders/loader-interface.js';
+export { type MetadataLoader, type MetadataKeyedItem } from './loaders/loader-interface.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
 export { RemoteLoader } from './loaders/remote-loader.js';
 export { DatabaseLoader, type DatabaseLoaderOptions } from './loaders/database-loader.js';

packages/metadata/src/loaders/database-loader.ts

@@ -23,7 +23,7 @@ import { SysMetadataObject, SysMetadataHistoryObject } from '@objectstack/metada
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { IDataDriver, IDataEngine, DriverQuery } from '@objectstack/spec/contracts';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 import { calculateChecksum } from '../utils/metadata-history-utils.js';
 import { LRUCache } from '../utils/lru-cache.js';
 // [#13279] Both predicates moved to `@objectstack/types` — see its
@@ -870,25 +870,43 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
- async loadMany<T = any>(
- type: string,
- _options?: MetadataLoadOptions
- ): Promise<T[]> {
+ /**
+ * 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 async readTypeRows(
+ type: string
+ ): Promise<Array<{ name: string | null; data: Record<string, unknown> }>> {
  await this.ensureSchema();
 
  if (this.loadManyCache) {
  const cached = this.loadManyCache.get(type);
- if (cached !== undefined) return cached as T[];
+ if (cached !== undefined) {
+ return cached as Array<{ name: string | null; data: Record<string, unknown> }>;
+ }
  }
 
  try {
  const rows = await this._find(this.tableName, {
  where: this.baseFilter(type),
  });
 
- const result = rows
- .map(row => this.rowToData(row))
- .filter((data): data is Record<string, unknown> => data !== null) as T[];
+ const result: Array<{ name: string | null; data: Record<string, unknown> }> = [];
+ for (const row of rows) {
+ const data = this.rowToData(row);
+ if (data === null) continue;
+ const name = row.name;
+ result.push({ name: typeof name === 'string' && name !== '' ? name : null, data });
+ }
 
  this.loadManyCache?.set(type, result);
  return result;
@@ -899,6 +917,37 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
+ async loadMany<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<T[]> {
+ return (await this.readTypeRows(type)).map(entry => entry.data) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const entries = await this.readTypeRows(type);
+ const keyed: MetadataKeyedItem<T>[] = [];
+ for (const entry of entries) {
+ if (entry.name === null) continue;
+ keyed.push({ name: entry.name, data: entry.data as T });
+ }
+ return keyed;
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  await this.ensureSchema();
 

packages/metadata/src/loaders/loader-interface.ts

@@ -15,6 +15,30 @@ import type {
  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
+/**
+ * [#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.
+ */
+export 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.
@@ -49,6 +73,38 @@ export interface MetadataLoader {
  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

packages/metadata/src/loaders/memory-loader.ts

@@ -15,7 +15,7 @@ import type {
  MetadataSaveOptions,
  MetadataSaveResult,
 } from '@objectstack/spec/system';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 
 export class MemoryLoader implements MetadataLoader {
  readonly contract: MetadataLoaderContract = {
@@ -61,6 +61,24 @@ export class MemoryLoader implements MetadataLoader {
  return Array.from(typeStore.values()) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const typeStore = this.storage.get(type);
+ if (!typeStore) return [];
+ return Array.from(typeStore, ([name, data]) => ({ name, data: data as T }));
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  return this.storage.get(type)?.has(name) ?? false;
  }

packages/metadata/src/metadata-manager-degraded-list-cache.test.ts

@@ -249,30 +249,52 @@ describe('#5184 — the issue repro: a healed store is not shadowed by the degra
  });
 });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
 describe('#5184 — the healthy TTL is untouched', () => {
  it('a complete read is still served from cache for the full 30s', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(names(await manager.list('permission'))).toEqual(['stored']);
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past the degraded TTL, nowhere near the healthy one.
  vi.advanceTimersByTime(ttls().degraded * 3);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Just short of 30s — still cached.
  vi.advanceTimersByTime(ttls().healthy - ttls().degraded * 3 - 1);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past 30s — re-read, exactly as before.
  vi.advanceTimersByTime(2);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(2);
+ expect(walks.count).toBe(2);
  });
 });
 
@@ -286,7 +308,7 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
  it('an empty complete read is cached too — there is no non-empty condition', async () => {
  const memory = new MemoryLoader();
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(await manager.list('permission')).toEqual([]);
  const entry = peekEntry(manager, 'permission');
@@ -296,6 +318,6 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
 
  // And it is served from cache, not re-read.
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  });
 });

packages/metadata/src/metadata-manager-list-diagnosed.test.ts

@@ -270,19 +270,41 @@ describe('#6504 — list() and listDiagnosed() are one read seen at two widths',
  expect((await working.listDiagnosed('permission')).items).toBe(workingItems);
  });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
  it('asking for the verdict costs no extra loader walk — one cache entry serves both', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Served from the entry the `list()` above filled — `listDiagnosed` is
  // the same read, not a second one.
  const diagnosed = await manager.listDiagnosed('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  expect(names(diagnosed.items)).toEqual(['stored']);
  expect(diagnosed.degraded).toBe(false);
  });

.changeset/loader-item-row-key-identity.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": minor
+---
+
+fix(metadata): key loader-held items by the row key they were stored under, so a body with no top-level `name` is no longer dropped from `list()` (#14205)
+
+`MetadataManager.readListUncached()` — and its no-catch sibling
+`listForIndex()`, which builds the endpoint index — merged each loader's answer
+into the result set keyed by `body.name`, and admitted an item ONLY when the
+stored body carried a string `name`.
+
+A metadata body is not required to name itself. `register(type, name, data)`
+takes the key as its ARGUMENT, and `assertMetadataRegisterContract` says so in
+as many words: "A document with NO `name` of its own is fine — the argument is
+the key". An aggregated `defineView` container is exactly that shape — no own
+`name` by design, its identity being the target object, carried in the row's
+`name` COLUMN — and `DatabaseLoader.rowToData()` returns the stored body
+without folding the column into it.
+
+So a container written by `register('view', OBJECT, container)` lived in the
+registry for the life of the process and was written to `sys_metadata`, and
+then **disappeared at the next restart**: cold registry, only the loader
+answering, and `list('view')` refused the row. `listDiagnosed()` reported that
+short answer as complete (`degraded: false`) because no loader had thrown. Not
+scoped to views — any loader-held body with no top-level `name` was invisible.
+
+**The repair.** A loader-held item's identity is the key its store holds it
+under, so the manager now asks the loader for that key rather than guessing it
+from the body: `MetadataLoader` gains an OPTIONAL `loadManyKeyed()` returning
+`(name, body)` pairs, implemented by `DatabaseLoader` (from the row's `name`
+column) and `MemoryLoader` (from its storage map key). The key travels BESIDE
+the body and is never folded into it, so nothing synthesises a `name` into a
+body that deliberately has none and the register contract's refusal of a
+disagreeing `data.name` keeps meaning 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 entry; what is new is only the items the old
+gate refused. `loadManyKeyed()` is optional, and a loader without it (a
+`RemoteLoader`, whose wire format carries bodies only) falls back to the
+previous `body.name` keying unchanged — so no implementor of the published
+`MetadataLoader` interface needs to change.
+
+`MetadataManager.loadMany()` is deliberately untouched: its `body.name` test is
+a de-duplication guard, not an admission gate — a nameless item already fell
+past it and was returned — so it never carried this defect.

packages/metadata/src/index.ts

@@ -14,7 +14,7 @@ export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
-export { type MetadataLoader } from './loaders/loader-interface.js';
+export { type MetadataLoader, type MetadataKeyedItem } from './loaders/loader-interface.js';
 export { MemoryLoader } from './loaders/memory-loader.js';
 export { RemoteLoader } from './loaders/remote-loader.js';
 export { DatabaseLoader, type DatabaseLoaderOptions } from './loaders/database-loader.js';

packages/metadata/src/loaders/database-loader.ts

@@ -23,7 +23,7 @@ import { SysMetadataObject, SysMetadataHistoryObject } from '@objectstack/metada
 import { applyConversionsToStoredItem } from '@objectstack/spec';
 import { PLURAL_TO_SINGULAR } from '@objectstack/spec/shared';
 import type { IDataDriver, IDataEngine, DriverQuery } from '@objectstack/spec/contracts';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 import { calculateChecksum } from '../utils/metadata-history-utils.js';
 import { LRUCache } from '../utils/lru-cache.js';
 // [#13279] Both predicates moved to `@objectstack/types` — see its
@@ -870,25 +870,43 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
- async loadMany<T = any>(
- type: string,
- _options?: MetadataLoadOptions
- ): Promise<T[]> {
+ /**
+ * 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 async readTypeRows(
+ type: string
+ ): Promise<Array<{ name: string | null; data: Record<string, unknown> }>> {
  await this.ensureSchema();
 
  if (this.loadManyCache) {
  const cached = this.loadManyCache.get(type);
- if (cached !== undefined) return cached as T[];
+ if (cached !== undefined) {
+ return cached as Array<{ name: string | null; data: Record<string, unknown> }>;
+ }
  }
 
  try {
  const rows = await this._find(this.tableName, {
  where: this.baseFilter(type),
  });
 
- const result = rows
- .map(row => this.rowToData(row))
- .filter((data): data is Record<string, unknown> => data !== null) as T[];
+ const result: Array<{ name: string | null; data: Record<string, unknown> }> = [];
+ for (const row of rows) {
+ const data = this.rowToData(row);
+ if (data === null) continue;
+ const name = row.name;
+ result.push({ name: typeof name === 'string' && name !== '' ? name : null, data });
+ }
 
  this.loadManyCache?.set(type, result);
  return result;
@@ -899,6 +917,37 @@ export class DatabaseLoader implements MetadataLoader {
  }
  }
 
+ async loadMany<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<T[]> {
+ return (await this.readTypeRows(type)).map(entry => entry.data) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const entries = await this.readTypeRows(type);
+ const keyed: MetadataKeyedItem<T>[] = [];
+ for (const entry of entries) {
+ if (entry.name === null) continue;
+ keyed.push({ name: entry.name, data: entry.data as T });
+ }
+ return keyed;
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  await this.ensureSchema();
 

packages/metadata/src/loaders/loader-interface.ts

@@ -15,6 +15,30 @@ import type {
  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
+/**
+ * [#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.
+ */
+export 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.
@@ -49,6 +73,38 @@ export interface MetadataLoader {
  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

packages/metadata/src/loaders/memory-loader.ts

@@ -15,7 +15,7 @@ import type {
  MetadataSaveOptions,
  MetadataSaveResult,
 } from '@objectstack/spec/system';
-import type { MetadataLoader } from './loader-interface.js';
+import type { MetadataLoader, MetadataKeyedItem } from './loader-interface.js';
 
 export class MemoryLoader implements MetadataLoader {
  readonly contract: MetadataLoaderContract = {
@@ -61,6 +61,24 @@ export class MemoryLoader implements MetadataLoader {
  return Array.from(typeStore.values()) as 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.
+ */
+ async loadManyKeyed<T = any>(
+ type: string,
+ _options?: MetadataLoadOptions
+ ): Promise<MetadataKeyedItem<T>[]> {
+ const typeStore = this.storage.get(type);
+ if (!typeStore) return [];
+ return Array.from(typeStore, ([name, data]) => ({ name, data: data as T }));
+ }
+
  async exists(type: string, name: string): Promise<boolean> {
  return this.storage.get(type)?.has(name) ?? false;
  }

packages/metadata/src/metadata-manager-degraded-list-cache.test.ts

@@ -249,30 +249,52 @@ describe('#5184 — the issue repro: a healed store is not shadowed by the degra
  });
 });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
 describe('#5184 — the healthy TTL is untouched', () => {
  it('a complete read is still served from cache for the full 30s', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(names(await manager.list('permission'))).toEqual(['stored']);
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past the degraded TTL, nowhere near the healthy one.
  vi.advanceTimersByTime(ttls().degraded * 3);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Just short of 30s — still cached.
  vi.advanceTimersByTime(ttls().healthy - ttls().degraded * 3 - 1);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Past 30s — re-read, exactly as before.
  vi.advanceTimersByTime(2);
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(2);
+ expect(walks.count).toBe(2);
  });
 });
 
@@ -286,7 +308,7 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
  it('an empty complete read is cached too — there is no non-empty condition', async () => {
  const memory = new MemoryLoader();
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  expect(await manager.list('permission')).toEqual([]);
  const entry = peekEntry(manager, 'permission');
@@ -296,6 +318,6 @@ describe('#5184 — 现象二: the comment now describes the code', () => {
 
  // And it is served from cache, not re-read.
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  });
 });

packages/metadata/src/metadata-manager-list-diagnosed.test.ts

@@ -270,19 +270,41 @@ describe('#6504 — list() and listDiagnosed() are one read seen at two widths',
  expect((await working.listDiagnosed('permission')).items).toBe(workingItems);
  });
 
+
+/**
+ * [#14205] Counts loader WALKS, not calls to one method name.
+ *
+ * `list()` reads a loader through `loadManyKeyed()` when the loader has one — a
+ * loader-held item's identity is the key its store holds it under, not
+ * `body.name` — and falls back to `loadMany()` when it does not. The invariant
+ * these cases pin is "the manager walked this loader once", which is the SUM of
+ * the two. Spying only `loadMany` counted 0 walks after the read moved, which
+ * reads exactly like a cache hit: green for the wrong reason in one direction,
+ * red for the wrong reason in the other.
+ */
+function loaderWalks(loader: MemoryLoader): { readonly count: number } {
+ const many = vi.spyOn(loader, 'loadMany');
+ const keyed = vi.spyOn(loader, 'loadManyKeyed');
+ return {
+ get count() {
+ return many.mock.calls.length + keyed.mock.calls.length;
+ },
+ };
+}
+
  it('asking for the verdict costs no extra loader walk — one cache entry serves both', async () => {
  const memory = new MemoryLoader();
  await memory.save('permission', 'stored', { name: 'stored' });
  const manager = new MetadataManager({ formats: ['json'], loaders: [memory] });
- const loadMany = vi.spyOn(memory, 'loadMany');
+ const walks = loaderWalks(memory);
 
  await manager.list('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
 
  // Served from the entry the `list()` above filled — `listDiagnosed` is
  // the same read, not a second one.
  const diagnosed = await manager.listDiagnosed('permission');
- expect(loadMany).toHaveBeenCalledTimes(1);
+ expect(walks.count).toBe(1);
  expect(names(diagnosed.items)).toEqual(['stored']);
  expect(diagnosed.degraded).toBe(false);
  });