@objectstack/metadata 17.0.0-rc.5 → 17.0.0

package/dist/index.d.cts

@@ -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 { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
+import { MetadataTypeRegistryEntryParsed, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
 import { z } from 'zod';
@@ -191,6 +191,23 @@ interface MetadataLoader {
  * Watch callback function (legacy)
  */
 type WatchCallback = (event: MetadataWatchEvent) => void | Promise<void>;
+/**
+ * [#6504] What one `list()` read actually produced: the best-effort set, plus
+ * whether assembling it lost a loader.
+ *
+ * The return of {@link MetadataManager.readListUncached}, the value shared
+ * through `inflightListReads`, and — minus the cache bookkeeping — what
+ * {@link MetadataManager.listDiagnosed} hands to a caller. One shape for all
+ * three on purpose: the verdict used to be dropped at each hop outward
+ * (`readListUncached` computed it, the in-flight promise kept only `items`,
+ * `list()` returned only that), and a single carried record is what makes
+ * losing it again take an edit rather than an omission.
+ */
+interface ListReadResult {
+    items: unknown[];
+    degraded: boolean;
+    errors: string[];
+}
 interface MetadataManagerOptions extends MetadataManagerConfig {
     loaders?: MetadataLoader[];
     /** Optional IDataDriver instance. When provided alongside config.datasource, auto-configures DatabaseLoader. */
@@ -270,6 +287,15 @@ declare class MetadataManager implements IMetadataService {
      * only, so a fresh read that already replaced it keeps its slot. Nothing
      * accumulates — a wave of callers arriving after settle finds the cache the
      * settle just wrote, and once that lapses it starts one new read.
+     *
+     * [#6504] The shared value is the whole {@link ListReadResult}, not just
+     * `items`. "Sharers share the outcome" above is stated about the answer *and*
+     * its degraded verdict, and while the promise carried only `items` that was
+     * true of `list()` alone: a {@link listDiagnosed} caller joining an in-flight
+     * read had no way to reach the verdict that read had already computed, and
+     * would have had to either re-walk the loaders (defeating this map) or invent
+     * a second, unmemoized answer. `list()` narrows to `.items` at its own return
+     * instead, so every sharer still receives the same array instance.
      */
     private readonly inflightListReads;
     private readonly loaderReadFailureReported;
@@ -287,7 +313,7 @@ declare class MetadataManager implements IMetadataService {
     /**
      * Set the type registry for metadata type discovery.
      */
-    setTypeRegistry(entries: MetadataTypeRegistryEntry[]): void;
+    setTypeRegistry(entries: MetadataTypeRegistryEntryParsed[]): void;
     /**
      * Configure and register a DatabaseLoader for database-backed metadata persistence.
      * Can be called at any time to enable database storage (e.g. after kernel resolves the driver).
@@ -389,16 +415,30 @@ declare class MetadataManager implements IMetadataService {
      * has with {@link loadDiagnosed}, so every existing caller keeps its exact
      * behaviour and only callers that ASK for the verdict pay for it.
      *
-     * [#5840] Deliberately NOT expressed as `(await getDiagnosed(…)).data`,
-     * although that is what it computes. The obvious delegation adds one
-     * `await` hop, and a registry hit here is observed one microtask sooner than
-     * it would be through a second async frame — which `register()`'s watchers
-     * depend on, because `notifyWatchers` does not await its handlers and
-     * ObjectQL's bridge re-reads through `get()` on the event rather than
-     * trusting the payload (`register-notifies-watchers.test.ts` pins it, and
-     * went red on the delegating version). The duplication is three lines and is
-     * pinned from the other side: `get()` and `getDiagnosed().data` are asserted
-     * to agree on every case in `metadata-manager-get-diagnosed.test.ts`.
+     * Not expressed as `(await getDiagnosed(…)).data`, although that is what it
+     * computes — and the reason has CHANGED, so do not read the duplication as a
+     * standing constraint.
+     *
+     * [#5840] recorded the delegation as unsafe: it adds one `await` hop, and
+     * `register-notifies-watchers.test.ts` went red on the delegating version, so
+     * three lines were duplicated to hold the frame count fixed. [#6043] measured
+     * that test and found it was pinning this method's microtask depth rather than
+     * the ordering guarantee it named — `notifyWatchers` never awaits its handlers,
+     * so a subscriber's `await get(…)` had simply been settling inside the
+     * microtasks `await register(…)` yields. That case now asserts the ordering
+     * synchronously against the registry and does not observe this method's frame
+     * count at all; the whole `@objectstack/metadata` suite was re-measured on the
+     * delegating version and stayed green.
+     *
+     * What survives is a plain, local reason: the registry hit is the hot path and
+     * answering it without a second async frame is worth three lines. Nothing
+     * external depends on the hop count any more. Consolidating the two into one
+     * delegation is therefore a viable, deliberately un-taken change (#6043 was
+     * test-scoped) — if you take it, note that `get()`'s callers outside this
+     * package were never surveyed for timing sensitivity, only this package's
+     * tests. Either way the two stay pinned to each other from the other side:
+     * `get()` and `getDiagnosed().data` are asserted to agree on every case in
+     * `metadata-manager-get-diagnosed.test.ts`.
      */
     get(type: string, name: string): Promise<unknown | undefined>;
     /**
@@ -443,6 +483,46 @@ declare class MetadataManager implements IMetadataService {
      * `listCache`.
      */
     list(type: string): Promise<unknown[]>;
+    /**
+     * `list`, plus whether the answer can be trusted as complete.
+     *
+     * [#6504] The plural counterpart of {@link getDiagnosed}, and the same defect
+     * one read over: `readListUncached` has computed this verdict since #5184 and
+     * `list()` spent it entirely on a cache TTL, so a consumer receiving a short
+     * set could not ask whether it was short because that is all anyone declared
+     * or because a loader was down. {@link reportLoaderReadFailure}'s own message
+     * says what that costs — "every list served from now on is a PARTIAL set
+     * presented as a complete one, and the server keeps reporting healthy" — and
+     * until this member existed that sentence was addressed to a log reader only,
+     * because no caller had a way to ask.
+     *
+     * Sharper than the singular case rather than merely analogous: `list` is the
+     * read whose answer carries a **count**, and a consumer restating
+     * `items.length` as "this environment contains N items" makes a positive,
+     * numeric claim about what an author declared out of a read that partly did
+     * not happen.
+     *
+     * Reads through exactly the same cache and single-flight machinery `list()`
+     * does — same entry, same TTLs, same in-flight join — so asking for the
+     * verdict costs no extra loader walk, and `list()` and
+     * `listDiagnosed().items` cannot drift: they are the same read, narrowed at
+     * different points. `degraded` is true when at least one loader threw while
+     * this set was assembled; unlike {@link getDiagnosed} it does NOT additionally
+     * require that nothing answered, because a plural read that lost one loader is
+     * partial even when the others answered plenty — which is the whole fact.
+     */
+    listDiagnosed(type: string): Promise<ListReadResult>;
+    /**
+     * The cached / single-flight read behind {@link list} and
+     * {@link listDiagnosed}.
+     *
+     * [#6504] Extracted so the two members are one read seen at two widths rather
+     * than two implementations that have to be kept in agreement — the shape
+     * `get`/`getDiagnosed` pay for with a duplicated body and a test pinning them
+     * to each other. Everything below is unchanged in behaviour from when it was
+     * inlined in `list()`; only the verdict now survives the return.
+     */
+    private readList;
     /**
      * Assemble the `list()` answer for `type` from the in-memory registry plus
      * every loader, reporting (but not rethrowing) loaders that could not be
@@ -502,6 +582,11 @@ declare class MetadataManager implements IMetadataService {
      * one thing this cache used to throw away. A result assembled while a loader
      * was unreadable is stored, but stored *as* what it is, so it expires on the
      * degraded TTL and any reader can tell it apart from a complete answer.
+     *
+     * [#6504] Takes the whole read result rather than its parts for the same
+     * reason: a signature that spreads the verdict across positional arguments is
+     * one a later caller can quietly fill with `false`, which is how the verdict
+     * was lost on the way out in the first place.
      */
     private cacheListResult;
     /**
@@ -787,10 +872,16 @@ declare class MetadataManager implements IMetadataService {
      * ## What it judges, and on what
      *
      * The registry stores either a raw spec document or a publish envelope
-     * (`{ name, packageId, state, metadata: {…spec} }`); the endpoint is read
-     * out with the SAME rule this method's caller uses for
-     * `publishedDefinition` (`data.metadata ?? data`), so publish gates exactly
-     * the document publish is about to snapshot. An item that does not satisfy
+     * (`{ name, packageId, state, metadata: {…spec} }`), and in BOTH shapes the
+     * row carries the metadata layer's bookkeeping. [#5309] The envelope is
+     * peeled off first (`peelStoredEnvelope`) and the gate judges the authored
+     * BODY: the wrapped half of that peel is the `data.metadata ?? data` rule
+     * this method used to spell inline — the same document `publishedDefinition`
+     * snapshots — and the flat half additionally removes `packageId` / `state` /
+     * `version` / `published*`, which are storage identity, never endpoint
+     * vocabulary. (What publish SNAPSHOTS is unchanged: `publishedDefinition`
+     * still stores `data.metadata ?? data` verbatim, envelope included, because
+     * `revertPackage` restores from it.) An item whose body does not satisfy
      * `ApiEndpointSchema` fails here too — not extra strictness but a
      * precondition: an unparsed shape cannot be gated, and it could never be
      * served either (the matcher's own loud skip refuses it at load).
@@ -1786,7 +1877,7 @@ declare class YAMLSerializer implements MetadataSerializer {
 declare class MigrationExecutor {
     private driver;
     constructor(driver: ISchemaDriver);
-    executeChangeSet(changeSet: System.ChangeSet): Promise<void>;
+    executeChangeSet(changeSet: System.ChangeSetParsed): Promise<void>;
     private executeOperation;
 }
 

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 { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
+import { MetadataTypeRegistryEntryParsed, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
 import { Logger, Plugin, PluginContext } from '@objectstack/core';
 import { z } from 'zod';
@@ -191,6 +191,23 @@ interface MetadataLoader {
  * Watch callback function (legacy)
  */
 type WatchCallback = (event: MetadataWatchEvent) => void | Promise<void>;
+/**
+ * [#6504] What one `list()` read actually produced: the best-effort set, plus
+ * whether assembling it lost a loader.
+ *
+ * The return of {@link MetadataManager.readListUncached}, the value shared
+ * through `inflightListReads`, and — minus the cache bookkeeping — what
+ * {@link MetadataManager.listDiagnosed} hands to a caller. One shape for all
+ * three on purpose: the verdict used to be dropped at each hop outward
+ * (`readListUncached` computed it, the in-flight promise kept only `items`,
+ * `list()` returned only that), and a single carried record is what makes
+ * losing it again take an edit rather than an omission.
+ */
+interface ListReadResult {
+    items: unknown[];
+    degraded: boolean;
+    errors: string[];
+}
 interface MetadataManagerOptions extends MetadataManagerConfig {
     loaders?: MetadataLoader[];
     /** Optional IDataDriver instance. When provided alongside config.datasource, auto-configures DatabaseLoader. */
@@ -270,6 +287,15 @@ declare class MetadataManager implements IMetadataService {
      * only, so a fresh read that already replaced it keeps its slot. Nothing
      * accumulates — a wave of callers arriving after settle finds the cache the
      * settle just wrote, and once that lapses it starts one new read.
+     *
+     * [#6504] The shared value is the whole {@link ListReadResult}, not just
+     * `items`. "Sharers share the outcome" above is stated about the answer *and*
+     * its degraded verdict, and while the promise carried only `items` that was
+     * true of `list()` alone: a {@link listDiagnosed} caller joining an in-flight
+     * read had no way to reach the verdict that read had already computed, and
+     * would have had to either re-walk the loaders (defeating this map) or invent
+     * a second, unmemoized answer. `list()` narrows to `.items` at its own return
+     * instead, so every sharer still receives the same array instance.
      */
     private readonly inflightListReads;
     private readonly loaderReadFailureReported;
@@ -287,7 +313,7 @@ declare class MetadataManager implements IMetadataService {
     /**
      * Set the type registry for metadata type discovery.
      */
-    setTypeRegistry(entries: MetadataTypeRegistryEntry[]): void;
+    setTypeRegistry(entries: MetadataTypeRegistryEntryParsed[]): void;
     /**
      * Configure and register a DatabaseLoader for database-backed metadata persistence.
      * Can be called at any time to enable database storage (e.g. after kernel resolves the driver).
@@ -389,16 +415,30 @@ declare class MetadataManager implements IMetadataService {
      * has with {@link loadDiagnosed}, so every existing caller keeps its exact
      * behaviour and only callers that ASK for the verdict pay for it.
      *
-     * [#5840] Deliberately NOT expressed as `(await getDiagnosed(…)).data`,
-     * although that is what it computes. The obvious delegation adds one
-     * `await` hop, and a registry hit here is observed one microtask sooner than
-     * it would be through a second async frame — which `register()`'s watchers
-     * depend on, because `notifyWatchers` does not await its handlers and
-     * ObjectQL's bridge re-reads through `get()` on the event rather than
-     * trusting the payload (`register-notifies-watchers.test.ts` pins it, and
-     * went red on the delegating version). The duplication is three lines and is
-     * pinned from the other side: `get()` and `getDiagnosed().data` are asserted
-     * to agree on every case in `metadata-manager-get-diagnosed.test.ts`.
+     * Not expressed as `(await getDiagnosed(…)).data`, although that is what it
+     * computes — and the reason has CHANGED, so do not read the duplication as a
+     * standing constraint.
+     *
+     * [#5840] recorded the delegation as unsafe: it adds one `await` hop, and
+     * `register-notifies-watchers.test.ts` went red on the delegating version, so
+     * three lines were duplicated to hold the frame count fixed. [#6043] measured
+     * that test and found it was pinning this method's microtask depth rather than
+     * the ordering guarantee it named — `notifyWatchers` never awaits its handlers,
+     * so a subscriber's `await get(…)` had simply been settling inside the
+     * microtasks `await register(…)` yields. That case now asserts the ordering
+     * synchronously against the registry and does not observe this method's frame
+     * count at all; the whole `@objectstack/metadata` suite was re-measured on the
+     * delegating version and stayed green.
+     *
+     * What survives is a plain, local reason: the registry hit is the hot path and
+     * answering it without a second async frame is worth three lines. Nothing
+     * external depends on the hop count any more. Consolidating the two into one
+     * delegation is therefore a viable, deliberately un-taken change (#6043 was
+     * test-scoped) — if you take it, note that `get()`'s callers outside this
+     * package were never surveyed for timing sensitivity, only this package's
+     * tests. Either way the two stay pinned to each other from the other side:
+     * `get()` and `getDiagnosed().data` are asserted to agree on every case in
+     * `metadata-manager-get-diagnosed.test.ts`.
      */
     get(type: string, name: string): Promise<unknown | undefined>;
     /**
@@ -443,6 +483,46 @@ declare class MetadataManager implements IMetadataService {
      * `listCache`.
      */
     list(type: string): Promise<unknown[]>;
+    /**
+     * `list`, plus whether the answer can be trusted as complete.
+     *
+     * [#6504] The plural counterpart of {@link getDiagnosed}, and the same defect
+     * one read over: `readListUncached` has computed this verdict since #5184 and
+     * `list()` spent it entirely on a cache TTL, so a consumer receiving a short
+     * set could not ask whether it was short because that is all anyone declared
+     * or because a loader was down. {@link reportLoaderReadFailure}'s own message
+     * says what that costs — "every list served from now on is a PARTIAL set
+     * presented as a complete one, and the server keeps reporting healthy" — and
+     * until this member existed that sentence was addressed to a log reader only,
+     * because no caller had a way to ask.
+     *
+     * Sharper than the singular case rather than merely analogous: `list` is the
+     * read whose answer carries a **count**, and a consumer restating
+     * `items.length` as "this environment contains N items" makes a positive,
+     * numeric claim about what an author declared out of a read that partly did
+     * not happen.
+     *
+     * Reads through exactly the same cache and single-flight machinery `list()`
+     * does — same entry, same TTLs, same in-flight join — so asking for the
+     * verdict costs no extra loader walk, and `list()` and
+     * `listDiagnosed().items` cannot drift: they are the same read, narrowed at
+     * different points. `degraded` is true when at least one loader threw while
+     * this set was assembled; unlike {@link getDiagnosed} it does NOT additionally
+     * require that nothing answered, because a plural read that lost one loader is
+     * partial even when the others answered plenty — which is the whole fact.
+     */
+    listDiagnosed(type: string): Promise<ListReadResult>;
+    /**
+     * The cached / single-flight read behind {@link list} and
+     * {@link listDiagnosed}.
+     *
+     * [#6504] Extracted so the two members are one read seen at two widths rather
+     * than two implementations that have to be kept in agreement — the shape
+     * `get`/`getDiagnosed` pay for with a duplicated body and a test pinning them
+     * to each other. Everything below is unchanged in behaviour from when it was
+     * inlined in `list()`; only the verdict now survives the return.
+     */
+    private readList;
     /**
      * Assemble the `list()` answer for `type` from the in-memory registry plus
      * every loader, reporting (but not rethrowing) loaders that could not be
@@ -502,6 +582,11 @@ declare class MetadataManager implements IMetadataService {
      * one thing this cache used to throw away. A result assembled while a loader
      * was unreadable is stored, but stored *as* what it is, so it expires on the
      * degraded TTL and any reader can tell it apart from a complete answer.
+     *
+     * [#6504] Takes the whole read result rather than its parts for the same
+     * reason: a signature that spreads the verdict across positional arguments is
+     * one a later caller can quietly fill with `false`, which is how the verdict
+     * was lost on the way out in the first place.
      */
     private cacheListResult;
     /**
@@ -787,10 +872,16 @@ declare class MetadataManager implements IMetadataService {
      * ## What it judges, and on what
      *
      * The registry stores either a raw spec document or a publish envelope
-     * (`{ name, packageId, state, metadata: {…spec} }`); the endpoint is read
-     * out with the SAME rule this method's caller uses for
-     * `publishedDefinition` (`data.metadata ?? data`), so publish gates exactly
-     * the document publish is about to snapshot. An item that does not satisfy
+     * (`{ name, packageId, state, metadata: {…spec} }`), and in BOTH shapes the
+     * row carries the metadata layer's bookkeeping. [#5309] The envelope is
+     * peeled off first (`peelStoredEnvelope`) and the gate judges the authored
+     * BODY: the wrapped half of that peel is the `data.metadata ?? data` rule
+     * this method used to spell inline — the same document `publishedDefinition`
+     * snapshots — and the flat half additionally removes `packageId` / `state` /
+     * `version` / `published*`, which are storage identity, never endpoint
+     * vocabulary. (What publish SNAPSHOTS is unchanged: `publishedDefinition`
+     * still stores `data.metadata ?? data` verbatim, envelope included, because
+     * `revertPackage` restores from it.) An item whose body does not satisfy
      * `ApiEndpointSchema` fails here too — not extra strictness but a
      * precondition: an unparsed shape cannot be gated, and it could never be
      * served either (the matcher's own loud skip refuses it at load).
@@ -1786,7 +1877,7 @@ declare class YAMLSerializer implements MetadataSerializer {
 declare class MigrationExecutor {
     private driver;
     constructor(driver: ISchemaDriver);
-    executeChangeSet(changeSet: System.ChangeSet): Promise<void>;
+    executeChangeSet(changeSet: System.ChangeSetParsed): Promise<void>;
     private executeOperation;
 }