@objectstack/metadata 17.0.0-rc.6 → 17.0.0

package/dist/index.d.cts

@@ -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;
@@ -457,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
@@ -516,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;
     /**

package/dist/index.d.ts

@@ -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;
@@ -457,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
@@ -516,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;
     /**

package/dist/index.js

@@ -177,7 +177,11 @@ import {
   ApiEndpointSchema as ApiEndpointSchema2,
   validateApiEndpointDeclarations
 } from "@objectstack/spec/api";
-import { createLogger } from "@objectstack/core";
+import {
+  assertMetadataRegisterContract,
+  canonicalMetadataServiceType,
+  createLogger
+} from "@objectstack/core";
 
 // src/serializers/json-serializer.ts
 var JSONSerializer = class {
@@ -1750,16 +1754,40 @@ var _MetadataManager = class _MetadataManager {
     // above. The concurrent half is delivered by `inflightListReads` below, which
     // is why the two fields are one policy and are documented together.
     //
-    // [#5184] That hazard is NOT historical — it was re-verified on the current
-    // driver stack before this policy was chosen. `DatabaseLoader._find()` still
-    // issues `engine.find('sys_metadata', …)` without threading the caller's
-    // transaction, and `driver-sql` still treats SQLite as a single-connection
-    // pool (`activeTransactions`, `assertBareKnexSafe` — the latter a dev/test
-    // guard that is a no-op in production, so production still waits the timeout
-    // out). `plugin-audit`'s `captureBefore` threads the transaction by hand for
-    // exactly this reason. Hence the policy below keeps caching degraded reads
-    // rather than skipping them: "don't cache a degraded read" would trade one
-    // 30s silent window for a fresh 60s stall per call.
+    // [#5184; re-measured under #7708 on 2026-08-11] That hazard is NOT
+    // historical — and the re-measurement NARROWED it rather than retiring it.
+    // Measured on the current stack: real `ObjectQL` + real `SqlDriver`
+    // (better-sqlite3), a real `DatabaseLoader.list()` with the loader's own
+    // cache off, `knex.client.pool.max === 1` confirmed for the SQLite dialect
+    // and `acquireConnectionTimeout` left at the knex default of 60s.
+    //
+    //   • Transaction opened DIRECTLY on the driver (`driver.beginTransaction()`)
+    //     → the read STALLS for the full timeout and then throws knex's "Timeout
+    //     acquiring a connection" (measured: 60_085ms). `DatabaseLoader._find()`
+    //     forwards no options, so nothing threads the caller's transaction, and
+    //     `driver-sql` still models SQLite as a single-connection pool
+    //     (`activeTransactions`, `assertBareKnexSafe` — the latter a dev/test
+    //     guard that is a no-op in production, so production still waits the
+    //     timeout out). `list()` catches that throw and degrades, which is
+    //     precisely the entry whose TTL this policy is choosing.
+    //   • Transaction opened through `engine.transaction()` / `ScopedContext`
+    //     → returns immediately (measured: 12ms, with `activeTransactions === 1`
+    //     and the driver observably receiving the handle on the call). Those
+    //     publish the transaction into the engine's ambient `txStore` (ADR-0034)
+    //     and `buildDriverOptions` threads it onto the read for the loader.
+    //
+    // So the stall shape is live but CONDITIONAL: it needs an open transaction
+    // that the engine's ambient store cannot see. `SqlDriver.ensureSequencesTable()`
+    // is the live witness that this is worth designing against — it takes
+    // `parentTrx` and runs its DDL on the caller's transaction for exactly this
+    // reason, with `assertBareKnexSafe` as the tripwire for callers that forget;
+    // `sql-driver-sqlite-tx-guard.test.ts` pins both halves. (Until #7708 the
+    // witness cited here was `plugin-audit`'s `captureBefore`, retired by #6656.
+    // It was REPLACED rather than dropped: the example died, the hazard did not.)
+    //
+    // Hence the policy below keeps caching degraded reads rather than skipping
+    // them: "don't cache a degraded read" would trade one 30s silent window for
+    // a fresh 60s stall per call on every caller in the first bullet.
     //
     // [#5184] WHAT IS ACTUALLY CACHED, AND FOR HOW LONG — this paragraph is the
     // contract, and it describes `cacheListResult()` / `readCachedList()` below.
@@ -1846,6 +1874,15 @@ var _MetadataManager = class _MetadataManager {
      * 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.
      */
     this.inflightListReads = /* @__PURE__ */ new Map();
     // [#5108] Loader names whose read failure has already been reported at
@@ -2042,6 +2079,8 @@ var _MetadataManager = class _MetadataManager {
    * {@link MetadataWriteOptions.notify} before doing so.
    */
   async register(type, name, data, options) {
+    assertMetadataRegisterContract(type, name, data);
+    type = canonicalMetadataServiceType(type);
     if (this.config.persistence?.writable === false) {
       const msg = `MetadataManager is read-only (persistence.writable=false); refusing to register ${type}/${name}`;
       if (this.config.validation?.throwOnError) {
@@ -2094,6 +2133,7 @@ var _MetadataManager = class _MetadataManager {
    * consumers will read the pre-write definition until restart.
    */
   registerInMemory(type, name, data) {
+    type = canonicalMetadataServiceType(type);
     if (!this.registry.has(type)) {
       this.registry.set(type, /* @__PURE__ */ new Map());
     }
@@ -2136,6 +2176,7 @@ var _MetadataManager = class _MetadataManager {
    * `metadata-manager-get-diagnosed.test.ts`.
    */
   async get(type, name) {
+    type = canonicalMetadataServiceType(type);
     const typeStore = this.registry.get(type);
     if (typeStore?.has(name)) {
       return typeStore.get(name);
@@ -2167,6 +2208,7 @@ var _MetadataManager = class _MetadataManager {
    * cannot prove the item is absent, so we decline to claim it is.
    */
   async getDiagnosed(type, name) {
+    type = canonicalMetadataServiceType(type);
     const typeStore = this.registry.get(type);
     if (typeStore?.has(name)) {
       return { data: typeStore.get(name), degraded: false, errors: [] };
@@ -2188,19 +2230,64 @@ var _MetadataManager = class _MetadataManager {
    * `listCache`.
    */
   async list(type) {
+    return (await this.readList(canonicalMetadataServiceType(type))).items;
+  }
+  /**
+   * `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.
+   */
+  async listDiagnosed(type) {
+    const { items, degraded, errors } = await this.readList(canonicalMetadataServiceType(type));
+    return { items, degraded, errors };
+  }
+  /**
+   * 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.
+   */
+  async readList(type) {
     const cached = this.readCachedList(type);
     if (cached) {
-      return cached.items;
+      return cached;
     }
     const joined = this.inflightListReads.get(type);
     if (joined) {
       return joined;
     }
-    const shared = this.readListUncached(type).then(({ items, degraded }) => {
+    const shared = this.readListUncached(type).then((result) => {
       if (this.inflightListReads.get(type) === shared) {
-        this.cacheListResult(type, items, degraded);
+        this.cacheListResult(type, result);
       }
-      return items;
+      return result;
     });
     this.inflightListReads.set(type, shared);
     try {
@@ -2231,6 +2318,7 @@ var _MetadataManager = class _MetadataManager {
       }
     }
     let degraded = false;
+    const errors = [];
     for (const loader of this.loaders.values()) {
       try {
         const loaderItems = await loader.loadMany(type);
@@ -2243,10 +2331,11 @@ var _MetadataManager = class _MetadataManager {
         this.reportLoaderReadRecovered(loader.contract.name);
       } catch (e) {
         degraded = true;
+        errors.push(`${loader.contract.name}: ${e instanceof Error ? e.message : String(e)}`);
         this.reportLoaderReadFailure(loader.contract.name, type, e);
       }
     }
-    return { items: Array.from(items.values()), degraded };
+    return { items: Array.from(items.values()), degraded, errors };
   }
   /**
    * Report — at `error`, once per outage episode — that a loader could not be
@@ -2308,9 +2397,14 @@ var _MetadataManager = class _MetadataManager {
    * 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.
    */
-  cacheListResult(type, items, degraded) {
-    this.listCache.set(type, { ts: Date.now(), items, degraded });
+  cacheListResult(type, result) {
+    this.listCache.set(type, { ts: Date.now(), ...result });
   }
   /**
    * Read a still-fresh {@link listCache} entry, or `undefined` when there is
@@ -2463,6 +2557,7 @@ var _MetadataManager = class _MetadataManager {
    * before the await would buy nothing and would re-open step 1's window.
    */
   async unregister(type, name, options) {
+    type = canonicalMetadataServiceType(type);
     for (const loader of this.loaders.values()) {
       if (loader.contract.protocol !== "datasource:" || !loader.contract.capabilities.write) continue;
       if (typeof loader.delete !== "function") continue;
@@ -2565,6 +2660,7 @@ var _MetadataManager = class _MetadataManager {
    * Check if a metadata item exists
    */
   async exists(type, name) {
+    type = canonicalMetadataServiceType(type);
     if (this.registry.get(type)?.has(name)) {
       return true;
     }
@@ -2579,6 +2675,7 @@ var _MetadataManager = class _MetadataManager {
    * List all names of metadata items of a given type
    */
   async listNames(type) {
+    type = canonicalMetadataServiceType(type);
     const names = /* @__PURE__ */ new Set();
     const typeStore = this.registry.get(type);
     if (typeStore) {
@@ -2884,11 +2981,21 @@ var _MetadataManager = class _MetadataManager {
       }
     }
     if (packageItems.length === 0) {
-      throw new Error(`No metadata items found for package '${packageId}'`);
+      const err = new Error(
+        `No metadata items found for package '${packageId}'`
+      );
+      err.code = "RESOURCE_NOT_FOUND";
+      err.status = 404;
+      throw err;
     }
     const hasPublished = packageItems.some((item) => item.data.publishedDefinition !== void 0);
     if (!hasPublished) {
-      throw new Error(`Package '${packageId}' has never been published`);
+      const err = new Error(
+        `Package '${packageId}' has never been published`
+      );
+      err.code = "RESOURCE_CONFLICT";
+      err.status = 409;
+      throw err;
     }
     for (const item of packageItems) {
       if (item.data.publishedDefinition !== void 0) {
@@ -3141,6 +3248,7 @@ var _MetadataManager = class _MetadataManager {
    * @returns An unsubscribe function.
    */
   subscribe(type, callback) {
+    type = canonicalMetadataServiceType(type);
     this.addWatchCallback(type, callback);
     return () => this.removeWatchCallback(type, callback);
   }