@objectstack/metadata 17.0.0-rc.4 → 17.0.0-rc.6

package/dist/node.cjs

@@ -555,6 +555,7 @@ var LRUCache = class {
 };
 
 // src/utils/schema-sync-errors.ts
+var import_types = require("@objectstack/types");
 var ALREADY_EXISTS = {
   codes: /* @__PURE__ */ new Set([
     // PostgreSQL SQLSTATE (class 42 — syntax error or access rule violation)
@@ -598,14 +599,67 @@ var MISSING_TABLE = {
    *   - PostgreSQL:      `relation "sys_metadata_history" does not exist`
    *   - MySQL/MariaDB:   `Table 'app.sys_metadata_history' doesn't exist`
    */
-  message: /no such table|relation ["'`][^"'`]+["'`] does not exist|table ["'`][^"'`]+["'`] doesn'?t exist|unknown table/i
+  message: /no such table|relation ["'`][^"'`]+["'`] does not exist|table ["'`][^"'`]+["'`] doesn'?t exist|unknown table/i,
+  excludes: {
+    /**
+     * Exactly the three SQLSTATEs the docblock above already names as
+     * must-stay-loud neighbours of `does not exist`. They are listed here
+     * rather than merely trusted to miss the message test, because two of
+     * them (42703 columns, 42704 constraints/triggers) have a phrasing that
+     * *does* hit it, and because a code is a fact where prose is a guess.
+     *
+     * Postgres-shaped on purpose: measured, neither MySQL
+     * (`Unknown column 'label' in 'field list'`) nor SQLite
+     * (`no such column: bogus`, `table t has no column named label`)
+     * phrases a sub-object failure so that a missing-table phrase falls out
+     * of it, so there is nothing there to exclude. Adding their codes would
+     * be surface with no defect behind it.
+     */
+    codes: /* @__PURE__ */ new Set([
+      "42703",
+      // undefined_column
+      "42704",
+      // undefined_object — constraint, trigger, role, type, …
+      "3D000"
+      // invalid_catalog_name — `database "x" does not exist`
+    ]),
+    /**
+     * `«sub-object» "x" of relation "y" …` — Postgres' phrasing for a
+     * failure about something *inside* a relation, which therefore says the
+     * relation itself is present. The two in-repo siblings that carry this
+     * phrase are `mapDataError` (`packages/rest`, #5352) and
+     * `service-analytics`'s missing-column subtraction (#6035/PR #6346).
+     *
+     * [#6615] All three now read one home — `@objectstack/types` — instead
+     * of three hand-kept copies, so the phrase can no longer be taught to
+     * the repo a fourth time or drift in one package only. The **width**
+     * difference that used to justify the copy is preserved and is the
+     * reason the home exports two functions rather than one: those two
+     * *extract* the column name to phrase a better error, so a miss costs a
+     * vaguer message; this one *excludes*, so a miss restores the
+     * corruption. {@link isRelationSubObjectPhrase} is therefore the wider
+     * question — it drops their `column`/`[a-z0-9_]+`/`does not exist`
+     * anchors: any sub-object, any quoted identifier, any verdict.
+     * Over-matching here only ever converts a benign verdict into a loud
+     * one, which is the direction this whole module already errs in.
+     */
+    matchesMessage: import_types.isRelationSubObjectPhrase
+  }
 };
 var MAX_CAUSE_DEPTH = 4;
 function matchesDriverError(error, signature, depth) {
   if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH) return false;
-  if (typeof error === "string") return signature.message.test(error);
+  if (typeof error === "string") {
+    if (signature.excludes?.matchesMessage(error)) return false;
+    return signature.message.test(error);
+  }
   if (typeof error !== "object") return false;
   const err = error;
+  const excludes = signature.excludes;
+  if (excludes) {
+    if (typeof err.code === "string" && excludes.codes.has(err.code)) return false;
+    if (typeof err.message === "string" && excludes.matchesMessage(err.message)) return false;
+  }
   if (typeof err.code === "string" && signature.codes.has(err.code)) return true;
   if (typeof err.errno === "number" && signature.errnos.has(err.errno)) return true;
   if (typeof err.message === "string" && signature.message.test(err.message)) return true;
@@ -618,48 +672,6 @@ function isMissingTableError(error, depth = 0) {
   return matchesDriverError(error, MISSING_TABLE, depth);
 }
 
-// src/migrations/add-sys-metadata-overlay-index.ts
-var INDEX_NAME = "idx_sys_metadata_overlay_active";
-var TABLE = "sys_metadata";
-var COLUMNS = "(type, name, organization_id, environment_id, scope)";
-var WHERE = "state = 'active'";
-async function addSysMetadataOverlayIndex(driver) {
-  const driverAny = driver;
-  const exec = async (sql) => {
-    if (typeof driverAny.raw === "function") {
-      await driverAny.raw(sql);
-    } else if (typeof driverAny.execute === "function") {
-      await driverAny.execute(sql);
-    } else {
-      throw new Error("driver has neither raw nor execute");
-    }
-  };
-  const partialSql = `CREATE UNIQUE INDEX IF NOT EXISTS ${INDEX_NAME} ON ${TABLE} ${COLUMNS} WHERE ${WHERE}`;
-  const fallbackSql = `CREATE INDEX IF NOT EXISTS ${INDEX_NAME} ON ${TABLE} ${COLUMNS}`;
-  try {
-    await exec(partialSql);
-    return { index: INDEX_NAME, status: "created" };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (/partial|where clause|syntax/i.test(msg)) {
-      try {
-        await exec(fallbackSql);
-        return { index: INDEX_NAME, status: "fallback_non_unique" };
-      } catch (fallbackErr) {
-        return {
-          index: INDEX_NAME,
-          status: "error",
-          error: fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)
-        };
-      }
-    }
-    if (/already exists/i.test(msg)) {
-      return { index: INDEX_NAME, status: "already_exists" };
-    }
-    return { index: INDEX_NAME, status: "error", error: msg };
-  }
-}
-
 // src/migrations/migrate-project-id-to-environment-id.ts
 var AFFECTED_TABLES = [
   "sys_metadata",
@@ -809,23 +821,40 @@ var DatabaseLoader = class {
   // ==========================================
   // Internal CRUD helpers (driver vs engine)
   // ==========================================
+  // NOTE (#6231, closed out by #7178): BOTH branches below now take `query`
+  // unchanged and uncast. `DriverQuery` is `Omit<QueryAST, 'object'>`, so the
+  // object name travels as argument one only — that was always enough for the
+  // driver branch. The ENGINE branch used to carry `as any`, for one reason:
+  // `EngineQueryOptionsSchema.search` admitted only the structured
+  // `FullTextSearchSchema`, while `QueryAST.search` (hence `DriverQuery`) also
+  // admits the bare query string that ADR-0061 D1 calls the canonical Tier-1
+  // spelling and that the engine actually serves, so `DriverQuery` was not
+  // assignable to `EngineQueryOptionsParsed`. #7178 aligned the two schemas;
+  // the casts are now genuinely vestigial and are gone, which restores real
+  // `where`/`orderBy`/`fields` checking on the metadata main read path — this
+  // schema is not `.strict()`, so an unknown key here is SILENTLY DROPPED
+  // (`check:query-options-erasure`'s own rationale) and the erased type was
+  // the only thing standing between a typo and that silence.
+  //
+  // If a future edit makes one of these stop compiling, the honest fix is to
+  // reconcile the two schemas again — not to reinstate the cast.
   async _find(table, query) {
     if (this.engine) {
       return this.engine.find(table, query);
     }
-    return this.driver.find(table, { object: table, ...query });
+    return this.driver.find(table, query);
   }
   async _findOne(table, query) {
     if (this.engine) {
       return this.engine.findOne(table, query);
     }
-    return this.driver.findOne(table, { object: table, ...query });
+    return this.driver.findOne(table, query);
   }
   async _count(table, query) {
     if (this.engine) {
       return this.engine.count(table, query);
     }
-    return this.driver.count(table, { object: table, ...query });
+    return this.driver.count(table, query);
   }
   async _create(table, data) {
     if (this.engine) {
@@ -907,9 +936,12 @@ var DatabaseLoader = class {
         }
         if (driver) {
           await migrateProjectIdToEnvironmentId(driver).catch(() => void 0);
-          await addSysMetadataOverlayIndex(driver);
         }
-      } catch {
+      } catch (error) {
+        console.warn(
+          `[Metadata] Could not resolve a raw-SQL driver from the engine for \`${this.tableName}\` \u2014 the project_id\u2192environment_id forward migration was SKIPPED. Legacy rows (if any) keep the pre-v5.0 column and read back as unset. Metadata reads and writes are otherwise unaffected. Re-run it explicitly with \`migrateProjectIdToEnvironmentId(driver)\` from \`@objectstack/metadata/migrations\` once the datasource is reachable.`,
+          error
+        );
       }
       return;
     }
@@ -941,10 +973,6 @@ var DatabaseLoader = class {
       await migrateProjectIdToEnvironmentId(this.driver);
     } catch {
     }
-    try {
-      await addSysMetadataOverlayIndex(this.driver);
-    } catch {
-    }
   }
   /**
    * Ensure the history table exists.
@@ -1552,6 +1580,60 @@ function generateId() {
 
 // src/endpoint-matcher.ts
 var import_api = require("@objectstack/spec/api");
+
+// src/stored-envelope.ts
+var STORED_ENVELOPE_KEYS = Object.freeze([
+  "package",
+  "packageId",
+  "publishedAt",
+  "publishedBy",
+  "publishedDefinition",
+  "state",
+  "version"
+]);
+var STORED_BODY_KEY = "metadata";
+var ENVELOPE_KEYS = /* @__PURE__ */ new Set([...STORED_ENVELOPE_KEYS, STORED_BODY_KEY]);
+var EMPTY_ENVELOPE = Object.freeze({});
+function peelStoredEnvelope(item) {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) {
+    return { envelope: EMPTY_ENVELOPE, body: item, wrapped: false };
+  }
+  const row = item;
+  const wrappedBody = row[STORED_BODY_KEY];
+  if (wrappedBody !== void 0 && wrappedBody !== null) {
+    const envelope2 = {};
+    for (const key of Object.keys(row)) {
+      if (key === STORED_BODY_KEY) continue;
+      envelope2[key] = row[key];
+    }
+    return { envelope: Object.freeze(envelope2), body: wrappedBody, wrapped: true };
+  }
+  let envelope;
+  for (const key of Object.keys(row)) {
+    if (!ENVELOPE_KEYS.has(key)) continue;
+    envelope ?? (envelope = {});
+    envelope[key] = row[key];
+  }
+  if (!envelope) return { envelope: EMPTY_ENVELOPE, body: row, wrapped: false };
+  const body = {};
+  for (const key of Object.keys(row)) {
+    if (ENVELOPE_KEYS.has(key)) continue;
+    body[key] = row[key];
+  }
+  return { envelope: Object.freeze(envelope), body, wrapped: false };
+}
+function storedItemName(peeled) {
+  const fromEnvelope = peeled.envelope.name;
+  if (typeof fromEnvelope === "string") return fromEnvelope;
+  const body = peeled.body;
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    const fromBody = body.name;
+    if (typeof fromBody === "string") return fromBody;
+  }
+  return void 0;
+}
+
+// src/endpoint-matcher.ts
 function normalizeEndpointMethod(method) {
   return String(method ?? "").toUpperCase();
 }
@@ -1561,9 +1643,10 @@ function endpointIndexKey(method, path3) {
 function buildEndpointIndex(items, logger) {
   const index = /* @__PURE__ */ new Map();
   for (const item of items) {
-    const parsed = import_api.ApiEndpointSchema.safeParse(item);
+    const peeled = peelStoredEnvelope(item);
+    const parsed = import_api.ApiEndpointSchema.safeParse(peeled.body);
     if (!parsed.success) {
-      const declaredName = item && typeof item === "object" && typeof item.name === "string" ? item.name : "<unnamed>";
+      const declaredName = storedItemName(peeled) ?? "<unnamed>";
       logger.error(
         `[EndpointMatcher] stored api item '${declaredName}' does not satisfy ApiEndpointSchema \u2014 it is EXCLUDED from endpoint matching and its declared route will answer 404. Fix the declaration (or remove it); the endpoint index never serves a half-valid shape.`,
         void 0,
@@ -2062,16 +2145,30 @@ var _MetadataManager = class _MetadataManager {
    * 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`.
    */
   async get(type, name) {
     const typeStore = this.registry.get(type);
@@ -2747,10 +2844,16 @@ var _MetadataManager = class _MetadataManager {
    * ## 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).
@@ -2768,8 +2871,8 @@ var _MetadataManager = class _MetadataManager {
     const endpoints = [];
     const gatedItems = [];
     for (const item of apiItems) {
-      const document = item.data?.metadata ?? item.data;
-      const parsed = import_api3.ApiEndpointSchema.safeParse(document);
+      const { body } = peelStoredEnvelope(item.data);
+      const parsed = import_api3.ApiEndpointSchema.safeParse(body);
       if (!parsed.success) {
         for (const issue of parsed.error.issues) {
           errors.push({
@@ -4353,8 +4456,16 @@ var ARTIFACT_FIELD_TO_TYPE = {
   connectors: "connector",
   emailTemplates: "email_template",
   docs: "doc",
-  books: "book",
-  data: "dataset"
+  books: "book"
+  // `data:` (the SEED collection) is deliberately absent — #6242 row 4(a).
+  // It used to map to `'dataset'`, the ADR-0021 analytics kind: the exact name
+  // collision `metadata-plugin.zod.ts` warns about in prose. The entry never
+  // registered anything (SeedSchema declares no `name`, and the loop below
+  // skips nameless items) — a dead pointer aimed at the wrong kind, which
+  // would have begun mis-registering the day either side moved. Removed rather
+  // than repointed at `'seed'`: seeds are APPLIED by SeedLoaderService off the
+  // bundle, never registered as metadata items, so a `seed` mapping would be
+  // new behaviour rather than a corrected name.
 };
 var MetadataPlugin = class {
   constructor(options = {}) {