@objectstack/metadata 17.3.0 → 17.4.0

package/dist/index.cjs

@@ -197,6 +197,9 @@ var init_hmr_routes = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AMBIGUOUS_METADATA_STEM_CODE: () => AMBIGUOUS_METADATA_STEM_CODE,
+  AMBIGUOUS_METADATA_STEM_STATUS: () => AMBIGUOUS_METADATA_STEM_STATUS,
+  AmbiguousMetadataStemError: () => AmbiguousMetadataStemError,
   DatabaseLoader: () => DatabaseLoader,
   HistoryCleanupManager: () => HistoryCleanupManager,
   JSONSerializer: () => JSONSerializer,
@@ -212,7 +215,8 @@ __export(index_exports, {
   calculateChecksum: () => calculateChecksum,
   deriveViewContainerObject: () => deriveViewContainerObject,
   generateDiffSummary: () => generateDiffSummary,
-  generateSimpleDiff: () => generateSimpleDiff
+  generateSimpleDiff: () => generateSimpleDiff,
+  isAmbiguousMetadataStemError: () => isAmbiguousMetadataStemError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -640,7 +644,7 @@ async function _columnExists(exec, table, column) {
 // src/loaders/database-loader.ts
 function canonicalIsoInstant(value) {
   if (value === null || value === void 0) return void 0;
-  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? void 0 : value.toISOString();
   if (typeof value === "string") return value;
   return String(value);
 }
@@ -696,7 +700,7 @@ var DatabaseLoader = class {
     if (cacheEnabled) {
       const lruOpts = {
         maxSize: cacheOpts?.maxSize ?? 500,
-        ttl: cacheOpts?.ttl ?? 6e4
+        ttl: cacheOpts?.ttlMs ?? 6e4
       };
       this.loadCache = new LRUCache(lruOpts);
       this.loadManyCache = new LRUCache(lruOpts);
@@ -1546,6 +1550,33 @@ function generateId() {
   return `meta_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
 }
 
+// src/loaders/ambiguous-metadata-stem.ts
+var AMBIGUOUS_METADATA_STEM_CODE = "AMBIGUOUS_METADATA_STEM";
+var AMBIGUOUS_METADATA_STEM_STATUS = 500;
+var AMBIGUOUS_METADATA_STEM_BRAND = /* @__PURE__ */ Symbol.for("objectstack.metadata.ambiguousStem");
+var _a, _b;
+var AmbiguousMetadataStemError = class extends (_b = Error, _a = AMBIGUOUS_METADATA_STEM_BRAND, _b) {
+  constructor(type, stem, paths) {
+    const sorted = [...paths].sort();
+    super(
+      `Ambiguous metadata name \`${stem}\` for type \`${type}\`: ${sorted.length} files resolve to the same name \u2014 ${sorted.map((p) => `\`${p}\``).join(", ")}. Only the first would ever be served (extension precedence: .json, .yaml, .yml, .ts, .js), so the others are listed and unreachable. Delete or rename all but one.`
+    );
+    /** Brand — see the module doc on why this is not `instanceof`. */
+    this[_a] = true;
+    /** ADR-0112 wire code. */
+    this.code = AMBIGUOUS_METADATA_STEM_CODE;
+    /** HTTP status a transport should answer. */
+    this.status = AMBIGUOUS_METADATA_STEM_STATUS;
+    this.name = "AmbiguousMetadataStemError";
+    this.type = type;
+    this.stem = stem;
+    this.paths = sorted;
+  }
+};
+function isAmbiguousMetadataStemError(err) {
+  return typeof err === "object" && err !== null && err[AMBIGUOUS_METADATA_STEM_BRAND] === true;
+}
+
 // src/endpoint-matcher.ts
 var import_api = require("@objectstack/spec/api");
 
@@ -1696,6 +1727,8 @@ var EndpointMatcher = class {
 // src/view-container-expansion.ts
 var import_spec2 = require("@objectstack/spec");
 var import_shared2 = require("@objectstack/spec/shared");
+
+// src/view-container.ts
 function deriveViewContainerObject(container) {
   if (!container || typeof container !== "object") return void 0;
   const c = container;
@@ -1703,6 +1736,8 @@ function deriveViewContainerObject(container) {
   const byName = typeof c.name === "string" && c.name ? c.name : void 0;
   return own ?? c?.list?.data?.object ?? c?.form?.data?.object ?? byName;
 }
+
+// src/view-container-expansion.ts
 function expandRuntimeViewContainer(data) {
   if (!(0, import_spec2.isAggregatedViewContainer)(data)) return [];
   const container = data;
@@ -2408,6 +2443,9 @@ var _MetadataManager = class _MetadataManager {
         await this.admitLoaderItems(loader, type, items);
         this.reportLoaderReadRecovered(loader.contract.name);
       } catch (e) {
+        if (isAmbiguousMetadataStemError(e)) {
+          throw e;
+        }
         degraded = true;
         errors.push(`${loader.contract.name}: ${e instanceof Error ? e.message : String(e)}`);
         this.reportLoaderReadFailure(loader.contract.name, type, e);
@@ -2745,6 +2783,30 @@ var _MetadataManager = class _MetadataManager {
   }
   /**
    * List all names of metadata items of a given type
+   *
+   * ## [#14423] One loader's fault does not take the whole enumeration down
+   *
+   * This loop used to be bare — `const result = await loader.list(type)` with
+   * no `try`, while the two sibling plural reads (`list()` via
+   * {@link admitLoaderItems}, and {@link loadMany}) have carried a per-loader
+   * `catch` since #5108. That asymmetry is the defect, independent of any one
+   * caller: the SAME storage outage was swallowed by one plural read and
+   * thrown out of the other, so which answer a caller got depended only on
+   * which method it happened to call. A caller reading both — the action
+   * governance audit is one — saw `loadMany` report a short-but-successful
+   * set and `listNames` throw, and had no way to tell that one fact was
+   * behind both.
+   *
+   * Same shape as `loadMany`'s, deliberately, down to the helpers: the outage
+   * is spoken once per loader through {@link reportLoaderReadFailure} and
+   * un-said through {@link reportLoaderReadRecovered}. ⛔ Not a third spelling
+   * for "a loader faulted" — a second vocabulary for one event is how the two
+   * reads drifted apart in the first place.
+   *
+   * The degradation is the same one `list()` documents and is graded the same
+   * way (AGENTS.md → "Degradation log levels"): the caller still gets an
+   * array, nothing 500s, and the set is quietly short — so it is reported at
+   * `error`, by the shared helper, rather than being re-graded here.
    */
   async listNames(type) {
     type = (0, import_core.canonicalMetadataServiceType)(type);
@@ -2756,8 +2818,16 @@ var _MetadataManager = class _MetadataManager {
       }
     }
     for (const loader of this.loaders.values()) {
-      const result = await loader.list(type);
-      result.forEach((item) => names.add(item));
+      try {
+        const result = await loader.list(type);
+        result.forEach((item) => names.add(item));
+        this.reportLoaderReadRecovered(loader.contract.name);
+      } catch (e) {
+        if (isAmbiguousMetadataStemError(e)) {
+          throw e;
+        }
+        this.reportLoaderReadFailure(loader.contract.name, type, e);
+      }
     }
     return Array.from(names);
   }
@@ -3617,6 +3687,99 @@ var _MetadataManager = class _MetadataManager {
     }
     return results;
   }
+  /**
+   * [#14423] {@link loadMany}, read under the identity the STORE holds each
+   * item by — the keyed plural read, beside the unkeyed one.
+   *
+   * ## Why a second method and not a widened `loadMany`
+   *
+   * `loadMany` keys nothing: it returns bodies, and every consumer that needs
+   * an identity reads `body.name` off them. #14205 already ruled what identity
+   * IS — the key the store holds the item under (`register(type, name, data)`
+   * takes it as the ARGUMENT, and a body is not required to name itself) — so
+   * `body.name` is a guess that happens to be right for most items and drops
+   * the rest ENTIRELY: an item whose body carries no `name` is served by
+   * `load(type, name)` and is not nameable from `loadMany`'s answer at all.
+   *
+   * Widening `loadMany`'s return would fix that and break every consumer of a
+   * published shape (the ones counted on this card all read `body.name` as the
+   * identity). So this is additive: `loadMany`'s return shape is untouched,
+   * and a caller that needs the key asks for the key.
+   *
+   * ## What it reads — the same population `loadMany` reads
+   *
+   * Loaders only, deliberately, so this is `loadMany` keyed and nothing more.
+   * It is NOT `list()`/{@link listNames}, which also merge the in-memory
+   * `register()` registry; a caller wanting that set has those. Reading the
+   * loaders alone is also what makes this the enumerable twin of
+   * {@link loadDiagnosed}, which walks the same loaders by name — that pairing
+   * is the point on the audit side of #14423, where an enumeration and a
+   * by-name read that disagree about a population make one subsystem accuse
+   * another of a defect neither has.
+   *
+   * ## Delegate first, fall back second — and why that order is not a style
+   *
+   * Per loader: {@link MetadataLoader.loadManyKeyed} where the loader offers
+   * one, else its `list()` + a per-name `load()`. Measured, on
+   * `DatabaseLoader`: the keyed method shares `loadMany`'s single query
+   * (`{find:1, findOne:0}` — zero extra cost), while enumerate-then-read-each
+   * on that same loader is a real N+1 (`{find:1, findOne:5}` for five items).
+   * The fallback exists for loaders that cannot produce keys at all
+   * (`RemoteLoader`'s wire format carries bodies only), and it recovers the
+   * nameless item the pre-#14205 `loadMany`-and-key-by-`body.name` fallback
+   * drops — which is why it is `list()` + `load()` and not `loadMany()`.
+   *
+   * ## Failure posture
+   *
+   * Per-loader `try`/`catch`, the same seam and the same helpers as
+   * {@link loadMany} and `list()` — one loader's outage does not take the
+   * enumeration down, and it is reported once through
+   * {@link reportLoaderReadFailure} rather than in a third vocabulary.
+   * Earlier loaders win a key collision, mirroring `list()`.
+   */
+  async loadManyKeyed(type, options) {
+    const items = /* @__PURE__ */ new Map();
+    for (const loader of this.loaders.values()) {
+      try {
+        await this.admitKeyedLoaderItems(loader, type, items, options);
+        this.reportLoaderReadRecovered(loader.contract.name);
+      } catch (e) {
+        this.reportLoaderReadFailure(loader.contract.name, type, e);
+      }
+    }
+    return Array.from(items, ([name, data]) => ({ name, data }));
+  }
+  /**
+   * Merge ONE loader's answer for `type` into `items`, keyed by that loader's
+   * own key for each item — {@link loadManyKeyed}'s per-loader body.
+   *
+   * Distinct from {@link admitLoaderItems} on exactly one axis, and that axis
+   * is the whole of #14423: the fallback for a loader with no
+   * `loadManyKeyed`. `admitLoaderItems` falls back to `loadMany` keyed by
+   * `data.name` — the pre-#14205 behaviour, verbatim, which drops a nameless
+   * body. Here the fallback is `list()` + a per-name `load()`, so a loader
+   * that cannot enumerate keys and bodies together still answers with both.
+   *
+   * Read failures are NOT caught here — the caller owns that verdict, as in
+   * {@link admitLoaderItems}.
+   */
+  async admitKeyedLoaderItems(loader, type, items, options) {
+    if (typeof loader.loadManyKeyed === "function") {
+      const keyed = await loader.loadManyKeyed(type, options);
+      for (const entry of keyed) {
+        if (!entry || typeof entry.name !== "string" || entry.name === "") continue;
+        if (items.has(entry.name)) continue;
+        items.set(entry.name, entry.data);
+      }
+      return;
+    }
+    for (const name of await loader.list(type)) {
+      if (typeof name !== "string" || name === "" || items.has(name)) continue;
+      const result = await loader.load(type, name, options);
+      if (result?.data == null) continue;
+      items.set(name, result.data);
+    }
+  }
   /**
    * Save metadata item to a loader
    */
@@ -4249,33 +4412,34 @@ var _FilesystemLoader = class _FilesystemLoader {
       const globPatterns = patterns.map(
         (pattern) => path.join(typeDir, pattern)
       );
+      const files = [];
       for (const pattern of globPatterns) {
-        const files = await (0, import_glob.glob)(pattern, {
-          ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*", "**/*[*]*"],
-          nodir: true
-        });
-        for (const file of files) {
-          if (limit && items.length >= limit) {
-            break;
-          }
-          try {
-            const content = await fs.readFile(file, "utf-8");
-            const format = this.detectFormat(file);
-            const serializer = this.getSerializer(format);
-            if (serializer) {
-              const data = serializer.deserialize(content);
-              items.push({ file, data });
-            }
-          } catch (error) {
-            this.logger?.warn("Failed to load file", {
-              file,
-              error: error instanceof Error ? error.message : String(error)
-            });
-          }
-        }
+        files.push(
+          ...await (0, import_glob.glob)(pattern, {
+            ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*", "**/*[*]*"],
+            nodir: true
+          })
+        );
+      }
+      this.resolvableNames(type, typeDir, files);
+      for (const file of files) {
         if (limit && items.length >= limit) {
           break;
         }
+        try {
+          const content = await fs.readFile(file, "utf-8");
+          const format = this.detectFormat(file);
+          const serializer = this.getSerializer(format);
+          if (serializer) {
+            const data = serializer.deserialize(content);
+            items.push({ file, data });
+          }
+        } catch (error) {
+          this.logger?.warn("Failed to load file", {
+            file,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
       }
       return items;
     } catch (error) {
@@ -4344,13 +4508,13 @@ var _FilesystemLoader = class _FilesystemLoader {
    */
   async list(type) {
     const typeDir = path.join(this.rootDir, type);
+    let files;
     try {
-      const files = await (0, import_glob.glob)("**/*", {
+      files = await (0, import_glob.glob)("**/*", {
         cwd: typeDir,
         ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*"],
         nodir: true
       });
-      return files.map((file) => this.resolvableNameForPath(typeDir, path.join(typeDir, file))).filter((name) => name !== null);
     } catch (error) {
       this.logger?.error("Failed to list", void 0, {
         type,
@@ -4358,6 +4522,7 @@ var _FilesystemLoader = class _FilesystemLoader {
       });
       return [];
     }
+    return this.resolvableNames(type, typeDir, files.map((file) => path.join(typeDir, file)));
   }
   async save(type, name, data, options) {
     const startTime = Date.now();
@@ -4482,6 +4647,49 @@ var _FilesystemLoader = class _FilesystemLoader {
     }
     return _FilesystemLoader.nameFromFilename(rel);
   }
+  /**
+   * [#14921] The names this loader reports for `files` — and the ONE place an
+   * ambiguous stem is refused.
+   *
+   * Shared by {@link list} and {@link loadManyEntries} so the two can never
+   * disagree about which trees are admissible: a stem that `list()` refuses
+   * must not still be walked and returned as two bodies by `loadMany()`, which
+   * is exactly the split this card measured.
+   *
+   * Refuses on the FIRST colliding name in sorted order, so a tree holding more
+   * than one collision always names the same one — a refusal that moves
+   * between runs reads as flakiness rather than as the fixed authoring error it
+   * is. Paths are deduplicated because two overlapping `patterns` legitimately
+   * match one file twice, and counting that as a collision would refuse a
+   * perfectly good tree.
+   *
+   * ⛔ Not a precedence resolver. Picking a winner here is what the ruling
+   * declined (option 2, keep the precedence and log): the loser would stay
+   * unreachable and the listed set would stay different from the addressable
+   * one.
+   */
+  resolvableNames(type, typeDir, files) {
+    const byName = /* @__PURE__ */ new Map();
+    for (const file of files) {
+      const name = this.resolvableNameForPath(typeDir, file);
+      if (name === null) {
+        continue;
+      }
+      let paths = byName.get(name);
+      if (!paths) {
+        paths = /* @__PURE__ */ new Set();
+        byName.set(name, paths);
+      }
+      paths.add(file);
+    }
+    for (const name of [...byName.keys()].sort()) {
+      const paths = byName.get(name);
+      if (paths.size > 1) {
+        throw new AmbiguousMetadataStemError(type, name, [...paths]);
+      }
+    }
+    return [...byName.keys()];
+  }
   /**
    * Find file for a given type and name
    */
@@ -5569,9 +5777,43 @@ var RemoteLoader = class {
       format: "json"
     };
   }
+  /**
+   * [#15037] Report only the names that ARE names.
+   *
+   * This read used to be `loadMany<{ name: string }>(type)` mapped straight to
+   * `items.map(i => i.name)`. That type argument is an ASSERTION about bodies
+   * that arrived over HTTP, and nothing checked it: a body with no top-level
+   * `name` yielded `undefined`, which went into an array this signature
+   * declares as `string[]` and reached consumers through
+   * `MetadataManager.listNames()` — a runtime violation of a declared type,
+   * not an untidy entry. A consumer that keys by it, lower-cases it, or feeds
+   * it back to a by-name `load()` gets `undefined` where the type says it
+   * cannot be.
+   *
+   * The guard is `DatabaseLoader.list()`'s, one file away: same cast-then-map
+   * spelling, one `typeof` filter behind it. Silently dropping is the landed
+   * direction, not a preference — `DatabaseLoader` drops rather than throws,
+   * and `FilesystemLoader`'s narrowing carries a maintainer ruling (via the
+   * director seat on #14486, 2026-09-02) that chose narrowing (A) over
+   * refusing loudly (B), because a name in the list that the door answers
+   * `null` for is the silent failure an author reads as their own typo. An
+   * `undefined` here is the extreme form of that name.
+   *
+   * ⛔ NOT copied from the siblings: `MemoryLoader` answers with its store
+   * keys, and #14205 ruled that identity is the key the store holds an item
+   * under rather than `body.name`. This loader reads over HTTP and holds no
+   * store key, so `body.name` is the only identity it has — the list is
+   * narrowed to agree with the door instead. `loadMany()` is deliberately
+   * untouched: it keys nothing, so a nameless body is still served there.
+   *
+   * The predicate is spelled as a type guard, and the mapped element type left
+   * `unknown`, so `tsc` PROVES the declared `string[]` instead of a cast
+   * asserting it — otherwise the compiler reads the filter as always-true and
+   * a later reader deletes it as dead.
+   */
   async list(type) {
     const items = await this.loadMany(type);
-    return items.map((i) => i.name);
+    return items.map((item) => item.name).filter((name) => typeof name === "string");
   }
   async save(type, name, data, _options) {
     const response = await fetch(`${this.baseUrl}/${type}/${name}`, {
@@ -5611,9 +5853,9 @@ var HistoryCleanupManager = class {
       return;
     }
     const intervalMs = (this.policy.cleanupIntervalHours ?? 24) * 60 * 60 * 1e3;
-    void this.runCleanup();
+    void runCleanupAndReport(this);
     this.cleanupTimer = setInterval(() => {
-      void this.runCleanup();
+      void runCleanupAndReport(this);
     }, intervalMs);
   }
   /**
@@ -5640,7 +5882,7 @@ var HistoryCleanupManager = class {
     try {
       if (this.policy.maxAgeDays) {
         const cutoffDate = /* @__PURE__ */ new Date();
-        cutoffDate.setDate(cutoffDate.getDate() - this.policy.maxAgeDays);
+        cutoffDate.setUTCDate(cutoffDate.getUTCDate() - this.policy.maxAgeDays);
         const cutoffISO = cutoffDate.toISOString();
         const filter = {
           recorded_at: { $lt: cutoffISO }
@@ -5760,7 +6002,7 @@ var HistoryCleanupManager = class {
       if (organizationId) baseWhere.organization_id = organizationId;
       if (this.policy.maxAgeDays) {
         const cutoffDate = /* @__PURE__ */ new Date();
-        cutoffDate.setDate(cutoffDate.getDate() - this.policy.maxAgeDays);
+        cutoffDate.setUTCDate(cutoffDate.getUTCDate() - this.policy.maxAgeDays);
         const cutoffISO = cutoffDate.toISOString();
         const filter = {
           recorded_at: { $lt: cutoffISO },
@@ -5807,6 +6049,23 @@ var HistoryCleanupManager = class {
     };
   }
 };
+async function runCleanupAndReport(manager) {
+  let outcome;
+  try {
+    outcome = await manager.runCleanup();
+  } catch (error) {
+    console.error(
+      "History cleanup: the run did not complete, so no history row past the retention policy was deleted and the table keeps growing while the system reports healthy. Fix: the cause below comes from the configured data driver, not from the retention policy; call `runCleanup()` directly to reproduce it. Cause:",
+      error
+    );
+    return;
+  }
+  if (outcome.errors > 0) {
+    console.error(
+      `History cleanup: ${outcome.errors} delete operation(s) failed and ${outcome.deleted} row(s) were deleted. The history rows those deletes were meant to remove are still in the table, nothing retries them, and the table grows past the retention policy while the system keeps reporting healthy. Fix: check the data driver delete path for the metadata history table. The per-failure causes are not carried out of \`runCleanup()\`, so reproduce them against the driver directly.`
+    );
+  }
+}
 
 // src/migration/index.ts
 var migration_exports = {};
@@ -5865,6 +6124,9 @@ var MigrationExecutor = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AMBIGUOUS_METADATA_STEM_CODE,
+  AMBIGUOUS_METADATA_STEM_STATUS,
+  AmbiguousMetadataStemError,
   DatabaseLoader,
   HistoryCleanupManager,
   JSONSerializer,
@@ -5880,6 +6142,7 @@ var MigrationExecutor = class {
   calculateChecksum,
   deriveViewContainerObject,
   generateDiffSummary,
-  generateSimpleDiff
+  generateSimpleDiff,
+  isAmbiguousMetadataStemError
 });
 //# sourceMappingURL=index.cjs.map