@objectstack/metadata 17.1.0 → 17.3.0

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLo
 export { MetadataCollectionInfo, MetadataDiffResult, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
 import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWriteOptions, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ApiEndpointMatch, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
 export { IMetadataService, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
-import { MetadataTypeRegistryEntryParsed, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
+import { MetadataTypeRegistryEntryParsed, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
 import { z } from 'zod';
@@ -72,6 +72,29 @@ interface MetadataSerializer {
  * Defines the contract for loading metadata from various sources
  */
 
+/**
+ * [#14205] One loaded item paired with the KEY its store holds it under.
+ *
+ * The pair exists because a metadata body is not required to name itself. Most
+ * do — and for those the key and `data.name` agree, because
+ * `assertMetadataRegisterContract` refuses a `register(type, name, data)` whose
+ * `data.name` disagrees with the `name` argument. But an aggregated `defineView`
+ * container has no own `name` BY DESIGN (its identity is the target object), and
+ * `register()` explicitly allows that: "A document with NO `name` of its own is
+ * fine — the argument is the key".
+ *
+ * So the key is a fact about the STORE, not about the body, and it is the only
+ * identity a nameless item has. Carrying it BESIDE `data` rather than folding it
+ * into `data` is the whole point: the body stays byte-identical to what was
+ * stored, so no consumer sees a synthesised `name` and the register contract's
+ * `data.name` check keeps meaning what it means.
+ */
+interface MetadataKeyedItem<T = any> {
+    /** The key this item is stored under — `register()`'s `name` argument. */
+    readonly name: string;
+    /** The stored body, exactly as {@link MetadataLoader.loadMany} would return it. */
+    readonly data: T;
+}
 /**
  * Abstract interface for metadata loaders
  * Implementations can load from filesystem, HTTP, S3, databases, etc.
@@ -96,6 +119,34 @@ interface MetadataLoader {
      * @returns Array of loaded items
      */
     loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * Load multiple items of a type, each paired with the KEY this loader holds
+     * it under.
+     *
+     * [#14205] Optional, and the reason it is a second method rather than a
+     * widened `loadMany()`: `MetadataLoader` is exported from this package's
+     * public entry, with implementors outside it (`packages/objectql`'s
+     * conformance fixtures among them). Changing `loadMany()`'s return type would
+     * break every one of them; an optional member breaks none, and a loader that
+     * cannot produce keys — `RemoteLoader`, whose wire format carries bodies only
+     * — simply does not declare it.
+     *
+     * `MetadataManager` prefers this method wherever it merges a loader's answer
+     * into a keyed set (`list()`, and the endpoint index), and falls back to
+     * `loadMany()` keyed by `data.name` when it is absent. That fallback is
+     * exactly the pre-#14205 behaviour, so it drops items whose body has no
+     * top-level `name`: implement this method on any loader that can be asked to
+     * hold one.
+     *
+     * `data` MUST be the same body `loadMany()` would return for the item —
+     * unmodified, in particular with no `name` folded in. `name` is the store's
+     * key, carried beside the body, never written into it.
+     *
+     * @param type The metadata type
+     * @param options Load options with patterns
+     * @returns Array of (key, body) pairs
+     */
+    loadManyKeyed?<T = any>(type: string, options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
     /**
      * Check if item exists
      * @param type The metadata type
@@ -224,7 +275,6 @@ declare class MetadataManager implements IMetadataService {
     protected watchCallbacks: Map<string, Set<WatchCallback>>;
     protected config: MetadataManagerOptions;
     private registry;
-    private overlays;
     private typeRegistry;
     private dependencies;
     private listCache;
@@ -534,6 +584,50 @@ declare class MetadataManager implements IMetadataService {
      * result may be memoized depends on what happened to the read's registration
      * while it ran, which only `list()` can see.
      */
+    /**
+     * Merge one loader's answer for `type` into `items`, under the identity that
+     * loader holds each item by.
+     *
+     * ## [#14205] The identity of a loader-held item is its ROW KEY
+     *
+     * Both plural readers used to key a loader's items by `body.name`, and admit
+     * an item only when the body carried a string one:
+     *
+     * ```ts
+     * if (itemAny && typeof itemAny.name === 'string' && !items.has(itemAny.name))
+     * ```
+     *
+     * A body is not required to name itself. `register(type, name, data)` takes
+     * the key as its ARGUMENT, and `assertMetadataRegisterContract` says in as
+     * many words that "A document with NO `name` of its own is fine — the argument
+     * is the key". An aggregated `defineView` container is exactly that: no own
+     * `name` by design, identity carried in the row's `name` column.
+     *
+     * So the old gate dropped every such item the moment the registry went cold
+     * and only the loader could answer — a persisted view container vanished from
+     * `list('view')` after a restart, and `listDiagnosed()` called the short
+     * answer complete because no loader had thrown. Same gate, same effect, in
+     * `listForIndex()`: a nameless `api` row fell out of the endpoint index, where
+     * a miss reads as "nothing declares this route".
+     *
+     * The repair is to ask the loader for the key instead of guessing it from the
+     * body ({@link MetadataLoader.loadManyKeyed}), and to keep the key BESIDE the
+     * body: nothing is written into a body that deliberately has none, so the
+     * register contract's refusal of a disagreeing `data.name` still means what it
+     * says.
+     *
+     * Nothing consumers see today changes shape. For any item that went through
+     * `register()`, a `data.name` that exists is required to EQUAL the key, so the
+     * keyed merge produces the identical map entry; what is new is only the
+     * entries the old gate refused. The `loadMany()` fallback below is the
+     * pre-#14205 behaviour verbatim, for loaders that cannot produce keys
+     * (`RemoteLoader`'s wire format carries bodies only).
+     *
+     * Read failures are NOT caught here: `readListUncached` warns-and-continues,
+     * `listForIndex` deliberately throws, and that difference is each caller's to
+     * keep.
+     */
+    private admitLoaderItems;
     private readListUncached;
     /**
      * Report — at `error`, once per outage episode — that a loader could not be
@@ -803,6 +897,35 @@ declare class MetadataManager implements IMetadataService {
      * Runtime-authored `shared` / `personal` views (`sys_view_definition`) are
      * merged in by the REST layer; this method returns the `package` layer that
      * was registered from source.
+     *
+     * ## [#13913] Aggregated containers are expanded inline, per read
+     *
+     * `this.list('view')` is `MetadataManager`'s OWN loader-based store — the
+     * in-memory registry plus every registered loader — and is a completely
+     * different store from the `sys_metadata` rows `getMetaItems` reads. #13407
+     * taught `getMetaItems` to expand a runtime-authored aggregated container
+     * inline; this exit never called it and had no equivalent step, so a
+     * container that `GET /meta/view?object=` now serves still answered **empty**
+     * here.
+     *
+     * Merely getting the container into the store would not have helped: the
+     * filter also requires `viewKind`, and a container has none. Loosening that
+     * requirement is NOT the repair — it would answer with the container itself
+     * as a view, the behaviour #7163 ruled wrong — so what is added below is the
+     * container's **expansion**, whose items each carry the `viewKind` + `object`
+     * pair this filter has always tested. The filter itself is untouched: it
+     * reads the top-level `object`, exactly as `ViewSchema.object` declares.
+     *
+     * Registry-free and per-read, mirroring #13407's choice at the other exit and
+     * for the same reason — the registry is process-wide, so a read must not
+     * graft rows into it (see `view-container-expansion.ts`'s header, which also
+     * records why the protocol's copy of this logic cannot be imported).
+     *
+     * Already-present items win: an expansion contributes only names the store
+     * does not already hold, so a container whose expanded ViewItems were
+     * registered by a source registrar (the ObjectQL boot loop, the artifact/HMR
+     * loader) still answers with those registered, fully-enriched items and this
+     * step adds nothing.
      */
     getViewsByObject(object: string): Promise<unknown[]>;
     /**
@@ -931,29 +1054,6 @@ declare class MetadataManager implements IMetadataService {
         type: string;
         name: string;
     }>, options?: MetadataWriteOptions): Promise<MetadataBulkResult>;
-    private overlayKey;
-    /**
-     * Get the active overlay for a metadata item
-     */
-    getOverlay(type: string, name: string, scope?: 'platform' | 'user'): Promise<MetadataOverlay | undefined>;
-    /**
-     * Save/update an overlay for a metadata item
-     */
-    saveOverlay(overlay: MetadataOverlay): Promise<void>;
-    /**
-     * Remove an overlay, reverting to the base definition
-     */
-    removeOverlay(type: string, name: string, scope?: 'platform' | 'user'): Promise<void>;
-    /**
-     * Get the effective (merged) metadata after applying all overlays.
-     * Resolution order: system ← merge(platform) ← merge(user)
-     */
-    getEffective(type: string, name: string, context?: {
-        userId?: string;
-        tenantId?: string;
-        roles?: string[];
-        permissions?: string[];
-    }): Promise<unknown | undefined>;
     /**
      * Watch for metadata changes (IMetadataService contract).
      * Returns a handle for unsubscribing.
@@ -1294,7 +1394,7 @@ interface MetadataPluginOptions {
 }
 declare class MetadataPlugin implements Plugin {
     name: string;
-    type: string;
+    type: "standard";
     version: string;
     /**
      * Services init() UNCONDITIONALLY registers (ADR-0116, #4131) — lets the
@@ -1315,6 +1415,13 @@ declare class MetadataPlugin implements Plugin {
     private repository?;
     /** Chokidar watcher on the artifact file (local-file mode) — ADR-0008 PR-8. */
     private artifactWatcher?;
+    /**
+     * The context handed to `init()`, retained so `destroy()` can log.
+     * [#10772] `Plugin.destroy()` takes NO argument — it is the kernel's only
+     * teardown hook — so the context the old `stop(ctx)` alias received has to
+     * be captured at init time instead of arriving at teardown time.
+     */
+    private initCtx?;
     /**
      * The most recently parsed artifact metadata (the plural-field record:
      * `objects`, `views`, `data`, …). Carried on the `metadata:reloaded`
@@ -1323,14 +1430,117 @@ declare class MetadataPlugin implements Plugin {
      * `name` and are skipped by `_parseAndRegisterArtifact`'s register loop.
      */
     private lastParsedMetadata?;
+    /**
+     * Once-per-process dedupe for the summaries the versioned artifact window
+     * emits. The artifact watcher replays `_parseAndRegisterArtifact` on every
+     * file change, so without this a dev loop over a legacy artifact would
+     * re-announce the same finding on every reload — the same shape
+     * `Protocol.storedConversionWarned` guards on the stored-row pass, which
+     * this surfacing is modeled on.
+     *
+     * Two key families share the set, because they share the replay:
+     * `<conversionId>|<label>` for a forward-conversion summary (#12772), and
+     * `unbound-form-predicate-root|<label>` for the unbound-root notice
+     * (#12915) — one line per artifact there, not one per conversion, since
+     * the notice already aggregates every finding it made.
+     */
+    private artifactConversionWarned;
     constructor(options?: MetadataPluginOptions);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
-    stop: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Teardown — the kernel's ONLY teardown hook.
+     *
+     * [#10772] This body used to be spelled `stop(ctx)`. `Plugin`
+     * (`@objectstack/core`'s `types.ts`) declares `init()`, `start?(ctx)` and
+     * `destroy?()` and no `stop()`, and `ObjectKernel.performShutdown()` /
+     * `LiteKernel.destroy()` walk the plugins in reverse calling
+     * `plugin.destroy()` — so the artifact watcher, the manager and the
+     * repository were all still held after `await kernel.shutdown()` had
+     * RESOLVED. The `start`/`stop` pair read symmetric to a reviewer because
+     * `start()` really is on the interface; only one half was ever called.
+     *
+     * Idempotent: every handle is cleared as it is released, so a second
+     * teardown is a no-op rather than a second close.
+     */
+    destroy: () => Promise<void>;
+    /**
+     * Retained alias for {@link destroy}. Kept because it is public API of an
+     * exported class: an embedder may have learned to call it directly
+     * precisely BECAUSE the kernel never did, and deleting it would break them.
+     * Still an arrow property, so a detached `const { stop } = plugin` call
+     * keeps working too. The parameter is now optional and ignored —
+     * `destroy()` takes no context, so teardown logs through the context
+     * captured in `init()`.
+     */
+    stop: (_ctx?: PluginContext) => Promise<void>;
     /**
      * Fetch JSON content from a URL with configurable timeout.
      */
     private _fetchJson;
+    /**
+     * Versioned ADR-0087 forward conversion at the artifact-ingestion door
+     * (#12772) — runs BEFORE the strict schema parse below, because the parse
+     * is the refusal point.
+     *
+     * A compiled artifact is data at rest with a version stamp: built by
+     * released tooling, then unchanged while the platform moves on. When a
+     * spec release retires an authorable key inside a protocol line (spec
+     * 17.1 → 17.2 retired the `allowRestore`/`allowPurge` permission bits),
+     * every already-built artifact carrying the key becomes unbootable at the
+     * tombstone — with no operator remedy, since `os migrate meta` targets
+     * sources, not built artifacts. The stored-row read path already replays
+     * the conversion chain for exactly this reason
+     * (`applyConversionsToStoredItem`, ADR-0087 addendum); this is the same
+     * policy at the artifact door, **keyed off the artifact's own declared
+     * `engines.protocol` floor**: an artifact authored below the running spec
+     * version converts forward, an artifact authored at the current (or a
+     * newer) surface converts nothing and answers to the strict parse,
+     * tombstones included. The version key is what keeps this a conversion
+     * rather than an amnesty — the retired keys return with the M2 lifecycle
+     * batch (#1883), and artifacts authored against that surface must never
+     * have them stripped by history.
+     *
+     * Notices surface the way the stored-row pass's do — operator-visible and
+     * deduped — as one summary line per conversion per artifact rather than
+     * one per rewritten path (a real 17.1 artifact carried 150 strips of the
+     * same two keys; 150 identical warn lines would bury the boot log).
+     */
+    private _convertArtifactForward;
+    /**
+     * Operator-facing boot notice for form-view predicates that fault OPEN on
+     * this runtime (#12915 scope C — maintainer ruling 2026-08-28, 「同意C」).
+     *
+     * A form-view predicate binds `record` / `previous` / `parent` (runtime
+     * record forms) or `data` (metadata-editing forms) — and a FIELD-level one
+     * also binds `current_user` and its ADR-0068 aliases (objectui#6010),
+     * which a SECTION-level one does not. The contract states beside that
+     * vocabulary that a bare identifier is UNBOUND and the predicate faults,
+     * and `visibleWhen`'s fault fallback is `true`. On a real
+     * 17.1-built artifact that combination dead-ends record creation in the
+     * console: the conditionally hidden field renders, and its unconditional
+     * `required: true` — authored to be gated by the visibility that no longer
+     * applies — blocks every submit, while the same payload POSTs 201 through
+     * REST. Nothing refused, nothing logged, and only the operator can fix it
+     * (by rebuilding the artifact), so this is the channel the ruling picked:
+     * service startup, server-side, never a console surface — the person at
+     * the form cannot act on "your artifact is stale".
+     *
+     * **Detection only.** No refusal, no rewrite, no behaviour change: the
+     * predicate keeps faulting open exactly as before. Rewriting a bare root to
+     * `record.` is the ADR-0087 conversion (#12915 scope A), deferred by the
+     * same ruling with an explicit start line.
+     *
+     * **Same versioned window as the conversion replay above** — and read off
+     * that pass's own verdict rather than recomputed, so the two can never
+     * disagree about which artifacts are "old". An artifact declaring the
+     * current (or a newer) floor answers to the strict parse and gets nothing
+     * from here even when it does carry bare roots; that boundary is what keeps
+     * a notice about legacy artifacts out of contract territory. An undeclared
+     * range is treated as old data at rest, matching the grandfathering posture
+     * the window already takes (`converted-undeclared`).
+     */
+    private _warnUnboundFormPredicateRoots;
     /**
      * Parse raw artifact JSON (envelope or bare definition) and register all
      * metadata items into the MetadataManager.
@@ -1344,6 +1554,35 @@ declare class MetadataPlugin implements Plugin {
      * landing.
      */
     private _parseAndRegisterArtifact;
+    /**
+     * Register ONE artifact body's collections into the MetadataManager.
+     *
+     * A "body" is either the whole artifact (the single-package branch, where
+     * the artifact and its one package are the same object) or one entry of
+     * `packages[]` (ADR-0130 D4), which is an assembled
+     * `{ ...manifest, ...collections }` payload carrying the same collection
+     * keys the top level does. The loop is identical for both — that is the
+     * point: there is one ingestion of a collection here, not one per shape.
+     *
+     * @param provenance - The `(packageId, packageVersion)` every item found in
+     *   this body is stamped with (ADR-0010 §3.7, via `applyProtection`). It is
+     *   the body's OWN identity, never the enclosing artifact's, which is what
+     *   makes a multi-package artifact's items agree with the registry and with
+     *   `GET /api/v1/packages` about who owns them.
+     * @param slots.claim - Called with every `(type, name)` this pass
+     *   registered. Passed when reading package bodies; the residual sweep uses
+     *   what it recorded.
+     * @param slots.skip - Consulted before registering each `(type, name)`.
+     *   Passed ONLY by the residual sweep, so a package body's copy is never
+     *   overwritten by the flattened top-level copy of the same definition —
+     *   the overwrite that re-attributed the item to the artifact's manifest.
+     *   ⛔ It is never passed while reading the bodies themselves: two items of
+     *   one name inside one body still register as they always have (last
+     *   wins), because suppressing that would be a behaviour change on the
+     *   single-package branch D7 pins.
+     * @returns How many items this body registered.
+     */
+    private _registerArtifactBodyCollections;
     /**
      * Reload the artifact from disk into the MetadataManager, then announce a
      * generic `metadata:reloaded` hook. Used by BOTH reload paths (the HMR POST
@@ -1386,6 +1625,16 @@ declare class MemoryLoader implements MetadataLoader {
     private storage;
     load(type: string, name: string, _options?: MetadataLoadOptions): Promise<MetadataLoadResult>;
     loadMany<T = any>(type: string, _options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * [#14205] The keyed half of {@link loadMany}. The storage map is already
+     * `Type -> Name -> Data`, so the key this loader holds an item under is the
+     * map key — `loadMany()` was simply discarding it, which dropped every
+     * nameless body out of `MetadataManager.list()` and out of the endpoint index.
+     *
+     * The body is handed back by reference, unchanged: the key travels beside it,
+     * never folded into it.
+     */
+    loadManyKeyed<T = any>(type: string, _options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
     exists(type: string, name: string): Promise<boolean>;
     stat(type: string, name: string): Promise<MetadataStats | null>;
     list(type: string): Promise<string[]>;
@@ -1718,7 +1967,33 @@ declare class DatabaseLoader implements MetadataLoader {
      */
     private rethrowUnlessTableUnprovisioned;
     load(type: string, name: string, _options?: MetadataLoadOptions): Promise<MetadataLoadResult>;
+    /**
+     * The one type-wide read both plural readers share: every row of `type`, each
+     * body paired with the `name` COLUMN it was stored under.
+     *
+     * [#14205] `name` is `null` only for a row whose key column does not hold a
+     * string. Such a row is still a body {@link loadMany} must return — dropping
+     * it would change what consumers see today — but it has no usable identity,
+     * so {@link loadManyKeyed} filters it out rather than invent one.
+     *
+     * One query and one cache entry serve both methods: `loadMany()` used to own
+     * them, and splitting them would have made every keyed `list()` read miss the
+     * cache and re-hit the database.
+     */
+    private readTypeRows;
     loadMany<T = any>(type: string, _options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * [#14205] The keyed half of {@link loadMany} — see
+     * {@link MetadataKeyedItem} for why the row key travels beside the body
+     * instead of inside it.
+     *
+     * `DatabaseLoader` is where the defect was measured: an aggregated view
+     * container is written by `register('view', OBJECT, container)` and stored
+     * verbatim, so its `sys_metadata` row carries the identity in the `name`
+     * COLUMN and the body has none. {@link rowToData} returns that body without
+     * folding the column in — deliberately, and unchanged here.
+     */
+    loadManyKeyed<T = any>(type: string, _options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
     exists(type: string, name: string): Promise<boolean>;
     stat(type: string, name: string): Promise<MetadataStats | null>;
     list(type: string): Promise<string[]>;
@@ -1903,4 +2178,61 @@ declare class TypeScriptSerializer implements MetadataSerializer {
     getFormat(): MetadataFormat;
 }
 
-export { DatabaseLoader, type DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff };
+/**
+ * [#13913] Registry-free expansion of an aggregated `defineView` container
+ * that reached `MetadataManager`'s OWN backing store.
+ *
+ * ---------------------------------------------------------------------------
+ * Why this lives in `packages/metadata` and does NOT import the protocol's copy
+ * ---------------------------------------------------------------------------
+ * `packages/metadata-protocol` grew `expandRuntimeViewContainer` (#13407) for
+ * `getMetaItems`' own inline expansion, and the obvious move would be to share
+ * it. **The dependency edge forbids it**: `@objectstack/metadata-protocol`
+ * declares `@objectstack/metadata` as a dependency, so an import in this
+ * direction inverts an existing edge and closes a cycle. Promoting the
+ * protocol's private method to a public export would not help either — it
+ * would widen that package's surface *and* still be unreachable from here.
+ *
+ * The reusable substance is therefore taken from where it already is: the
+ * canonical expansion primitives (`isAggregatedViewContainer`,
+ * `expandViewContainer`) live in `@objectstack/spec`, one level BELOW both
+ * packages, and this package already imports them (`plugin.ts`). Nothing is
+ * duplicated except the ~6-line object-derivation chain — which is exactly the
+ * part that has silently drifted three ways (the ObjectQL boot loop keys off
+ * the registration name, `plugin.ts` walks two levels, and `protocol.ts` walks
+ * four since #13407). {@link deriveViewContainerObject} is the one spelling of
+ * it for this package, so the drift has a single place to be repaired rather
+ * than a third private copy to fall behind.
+ *
+ * ---------------------------------------------------------------------------
+ * Registry-free, on purpose
+ * ---------------------------------------------------------------------------
+ * Nothing here REGISTERS. `protocol.ts`'s own header records why its
+ * registry-MUTATING path (`hydrateExpandedViewItems`) could not simply be
+ * widened — it is gated off for every org-scoped row (ADR-0005: the registry
+ * is shared by every org a kernel serves) — and why #13407's actual repair was
+ * a separate, registry-free, per-request expansion. The same reasoning applies
+ * one exit over: `MetadataManager`'s registry is process-wide too, so the
+ * repair for {@link MetadataManager.getViewsByObject} is a pure function over
+ * what that one read already holds.
+ */
+
+/**
+ * Which object an aggregated view container binds to.
+ *
+ * The container's OWN top-level `object` field — `ViewSchema.object`,
+ * documented there as "how a stack-level `views: [...]` entry says which object
+ * its views belong to; read by `getViewsByObject()` / `GET /meta/view?object=`"
+ * — is the authorial, explicit signal and is consulted FIRST (#13407). The
+ * three-deep fallback below it is kept unchanged for every container written
+ * before that field was read here: `list.data.object`, then `form.data.object`,
+ * then the row's own `name` — which is the bound object only by convention, and
+ * is why a container that set the top-level field but not `list.data.object`
+ * used to bind under the wrong key or not at all.
+ *
+ * Returns `undefined` when no binding can be derived; every caller treats that
+ * as "no expansion" rather than an error.
+ */
+declare function deriveViewContainerObject(container: unknown): string | undefined;
+
+export { DatabaseLoader, type DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, type MetadataKeyedItem, type MetadataLoader, MetadataManager, type MetadataManagerOptions, MetadataPlugin, type MetadataSerializer, index as Migration, RemoteLoader, type SerializeOptions, TypeScriptSerializer, type WatchCallback, YAMLSerializer, calculateChecksum, deriveViewContainerObject, generateDiffSummary, generateSimpleDiff };