@objectstack/objectql 9.2.0 → 9.3.0

package/dist/index.mjs

@@ -886,6 +886,22 @@ function applySystemFields(schema, opts) {
     fields: { ...additions, ...schema.fields ?? {} }
   };
 }
+var SYS_METADATA_OWNER = "sys_metadata";
+function isRealPackage(pkg) {
+  return typeof pkg === "string" && pkg.length > 0 && pkg !== SYS_METADATA_OWNER;
+}
+var MetadataCollisionError = class extends Error {
+  constructor(type, name, existingPackageId, incomingPackageId) {
+    super(
+      `Cross-package metadata collision: ${type}/${name} is registered by package "${existingPackageId}" and package "${incomingPackageId}". Bare-named ${type} metadata has no package coordinate in the registry, so the second registration would silently shadow the first (last-write-wins at read time). Rename one of them (a namespace prefix such as "<namespace>_${name}" is recommended), or, if this is a deliberate migration, set OS_METADATA_COLLISION=warn to downgrade to a warning. See ADR-0048.`
+    );
+    this.name = "MetadataCollisionError";
+    this.type = type;
+    this.name_ = name;
+    this.existingPackageId = existingPackageId;
+    this.incomingPackageId = incomingPackageId;
+  }
+};
 var SchemaRegistry = class {
   constructor(options = {}) {
     // ==========================================
@@ -929,6 +945,7 @@ var SchemaRegistry = class {
     } else {
       this.multiTenant = String(readEnvWithDeprecation("OS_MULTI_ORG_ENABLED", "OS_MULTI_TENANT") ?? "false").toLowerCase() !== "false";
     }
+    this.collisionPolicy = options.collisionPolicy ?? ((process.env.OS_METADATA_COLLISION ?? "").toLowerCase() === "warn" ? "warn" : "error");
   }
   get logLevel() {
     return this._logLevel;
@@ -1236,6 +1253,17 @@ var SchemaRegistry = class {
     if (collection.has(storageKey)) {
       this.log(`[Registry] Overwriting ${type}: ${storageKey}`);
     }
+    if (isRealPackage(packageId)) {
+      const conflictOwner = this.findOtherPackageOwner(collection, baseName, packageId);
+      if (conflictOwner) {
+        const err = new MetadataCollisionError(type, baseName, conflictOwner, packageId);
+        if (this.collisionPolicy === "warn") {
+          console.warn(`[Registry] ${err.message}`);
+        } else {
+          throw err;
+        }
+      }
+    }
     if (packageId && collection.has(baseName)) {
       const dbOnly = collection.get(baseName);
       if (dbOnly && !dbOnly._packageId) {
@@ -1247,6 +1275,22 @@ var SchemaRegistry = class {
     collection.set(storageKey, item);
     this.log(`[Registry] Registered ${type}: ${storageKey}`);
   }
+  /**
+   * Find a code package OTHER than `incoming` that already owns `baseName` in
+   * `collection` (ADR-0048 cross-package collision detection). Scans the live
+   * collection — like {@link getItem} / {@link unregisterItem} — so it always
+   * reflects current state with no parallel index to drift across
+   * reset/unregister. Returns the conflicting owner's package id, or undefined
+   * when the name is free or only held by the same package / a runtime overlay.
+   */
+  findOtherPackageOwner(collection, baseName, incoming) {
+    for (const [key, item] of collection) {
+      if (key !== baseName && !key.endsWith(`:${baseName}`)) continue;
+      const owner = item?._packageId;
+      if (isRealPackage(owner) && owner !== incoming) return owner;
+    }
+    return void 0;
+  }
   /**
    * Validate Metadata against Spec Zod Schemas
    */
@@ -1306,6 +1350,70 @@ var SchemaRegistry = class {
     }
     return void 0;
   }
+  /**
+   * Artifact-only lookup (ADR-0010 §3.3). Unlike {@link getItem} — which
+   * returns the plain-key entry first, so a runtime/DB-rehydrated row
+   * registered under the bare name SHADOWS the packaged artifact — this
+   * scans the composite (`<packageId>:<name>`) entries first and only
+   * returns an item whose `_packageId` marks a genuine code package
+   * (truthy and not the `'sys_metadata'` rehydration sentinel).
+   *
+   * This is what the protocol's lock/provenance resolution must use:
+   * the artifact's `_lock` envelope always wins over an overlay, and an
+   * overlay row hydrated into the plain key must never be able to mask
+   * it (that masking is exactly the "registry pollution" bug where a
+   * locked app's `_lock` read back as undefined after a PUT+GET).
+   */
+  getArtifactItem(type, name) {
+    if (type === "object" || type === "objects") {
+      const obj = this.getObject(name);
+      return obj && obj._packageId && obj._packageId !== "sys_metadata" ? obj : void 0;
+    }
+    const collection = this.metadata.get(type);
+    if (!collection) return void 0;
+    for (const [key, item] of collection) {
+      if (key !== name && key.endsWith(`:${name}`)) {
+        const it = item;
+        if (it && it._packageId && it._packageId !== "sys_metadata") return item;
+      }
+    }
+    const direct = collection.get(name);
+    if (direct && direct._packageId && direct._packageId !== "sys_metadata") {
+      return direct;
+    }
+    return void 0;
+  }
+  /**
+   * Remove a plain-key runtime shadow so the packaged artifact registered
+   * under a composite key becomes the visible value again. Used by the
+   * metadata reset path (`deleteMetaItem`): deleting the `sys_metadata`
+   * overlay row must also heal the in-memory registry, otherwise the
+   * stale overlay copy keeps shadowing the artifact until restart.
+   *
+   * Deliberately conservative: the plain-key entry is only deleted when a
+   * packaged artifact still exists under a composite key, so the name
+   * stays resolvable afterwards. A runtime-only item (no artifact
+   * backing) is left untouched. Note the plain entry's own `_packageId`
+   * is NOT consulted — the hydration path grafts the artifact envelope
+   * onto the shadow (ADR-0010 §3.3), so a stamped `_packageId` does not
+   * mean the plain entry IS the artifact registration; artifact loaders
+   * always register under a composite key.
+   */
+  removeRuntimeShadow(type, name) {
+    const collection = this.metadata.get(type);
+    if (!collection || !collection.has(name)) return false;
+    for (const [key, item] of collection) {
+      if (key !== name && key.endsWith(`:${name}`)) {
+        const it = item;
+        if (it && it._packageId && it._packageId !== "sys_metadata") {
+          collection.delete(name);
+          this.log(`[Registry] Removed runtime shadow ${type}: ${name} (artifact ${it._packageId} restored)`);
+          return true;
+        }
+      }
+    }
+    return false;
+  }
   /**
    * Universal List Method
    */
@@ -2335,6 +2443,48 @@ function decorateMetadataItems(type, items) {
   if (!Array.isArray(items)) return items;
   return items.map((item) => decorateMetadataItem(type, item));
 }
+function fieldMap(objectDef) {
+  const map = /* @__PURE__ */ new Map();
+  const fields = objectDef?.fields;
+  if (Array.isArray(fields)) {
+    for (const f of fields) if (f?.name) map.set(f.name, f);
+  } else if (fields && typeof fields === "object") {
+    for (const [name, f] of Object.entries(fields)) map.set(name, f ?? {});
+  }
+  return map;
+}
+function computeViewReferenceDiagnostics(view, objectDef) {
+  const fields = fieldMap(objectDef);
+  const errors = [];
+  const requireField = (name, path) => {
+    if (typeof name !== "string" || !name) return;
+    if (!fields.has(name)) {
+      errors.push({
+        path,
+        message: `Field "${name}" does not exist on the source object`,
+        code: "reference_not_found"
+      });
+    }
+  };
+  const userFilters = view?.userFilters;
+  userFilters?.fields?.forEach((f, i) => requireField(f?.field, `userFilters.fields.${i}.field`));
+  userFilters?.tabs?.forEach((t, i) => t?.filter?.forEach((r, j) => requireField(r?.field, `userFilters.tabs.${i}.filter.${j}.field`)));
+  view?.tabs?.forEach((t, i) => t?.filter?.forEach((r, j) => requireField(r?.field, `tabs.${i}.filter.${j}.field`)));
+  view?.filterableFields?.forEach((f, i) => requireField(f, `filterableFields.${i}`));
+  const kanban = view?.kanban;
+  if (kanban?.groupByField) {
+    requireField(kanban.groupByField, "kanban.groupByField");
+    const def = fields.get(kanban.groupByField);
+    if (def && def.type && !["select", "multi-select", "boolean", "lookup", "master_detail"].includes(def.type)) {
+      errors.push({
+        path: "kanban.groupByField",
+        message: `Field "${kanban.groupByField}" (type "${def.type}") cannot group a kanban \u2014 use a select-like field`,
+        code: "invalid_binding"
+      });
+    }
+  }
+  return errors.length ? { valid: false, errors } : { valid: true };
+}
 
 // src/protocol.ts
 var TYPE_TO_FORM = METADATA_FORM_REGISTRY;
@@ -3157,8 +3307,13 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
             }
             byName.set(data.name, data);
           }
-          if (this.environmentId === void 0) {
-            this.engine.registry.registerItem(request.type, data, "name");
+          if (this.environmentId === void 0 && data && typeof data === "object") {
+            const artifact = this.lookupArtifactItem(request.type, data.name);
+            this.engine.registry.registerItem(
+              request.type,
+              mergeArtifactProtection(data, artifact),
+              "name"
+            );
           }
         }
         items = Array.from(byName.values());
@@ -3364,10 +3519,34 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       item = this.engine.registry.applyNavContributions(item);
     }
     const artifactItem = this.lookupArtifactItem(request.type, request.name);
-    const decorated = decorateMetadataItem(
+    let decorated = decorateMetadataItem(
       request.type,
       mergeArtifactProtection(item, artifactItem)
     );
+    if ((request.type === "view" || request.type === "views") && decorated && typeof decorated === "object") {
+      try {
+        const viewDoc = decorated;
+        const sourceObject = viewDoc?.object ?? viewDoc?.data?.object ?? viewDoc?.objectName ?? viewDoc?.list?.data?.object;
+        const objectDef = typeof sourceObject === "string" ? this.engine.registry.getObject(sourceObject) : void 0;
+        if (objectDef) {
+          const refs = computeViewReferenceDiagnostics(viewDoc, objectDef);
+          if (!refs.valid) {
+            const prior = viewDoc._diagnostics;
+            decorated = {
+              ...viewDoc,
+              _diagnostics: {
+                valid: false,
+                errors: [
+                  ...prior && prior.valid === false && Array.isArray(prior.errors) ? prior.errors : [],
+                  ...refs.errors ?? []
+                ]
+              }
+            };
+          }
+        }
+      } catch {
+      }
+    }
     const artifactBacked = this.isArtifactBacked(request.type, request.name);
     const lockState = resolveLockState(decorated, artifactBacked);
     return {
@@ -3417,7 +3596,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     } catch {
     }
     if (code === null) {
-      let regItem = this.engine.registry.getItem(request.type, request.name);
+      let regItem = this.lookupArtifactItem(request.type, request.name) ?? this.engine.registry.getItem(request.type, request.name);
       if (regItem === void 0) {
         const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
         if (alt) regItem = this.engine.registry.getItem(alt, request.name);
@@ -4463,14 +4642,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * "authoring a DB-only item" (requires only `allowRuntimeCreate`).
    */
   isArtifactBacked(type, name) {
-    const registry = this.engine?.registry;
-    if (!registry || typeof registry.getItem !== "function") {
-      return false;
-    }
-    const singular = PLURAL_TO_SINGULAR3[type] ?? type;
-    const item = registry.getItem(singular, name) ?? registry.getItem(type, name);
-    if (!item || !item._packageId) return false;
-    return item._packageId !== "sys_metadata";
+    return this.lookupArtifactItem(type, name) !== void 0;
   }
   // ───────────────────────────────────────────────────────────────────
   // ADR-0010 — metadata protection (Phase 1: L3 item-level lock)
@@ -4482,9 +4654,17 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    */
   lookupArtifactItem(type, name) {
     const registry = this.engine?.registry;
-    if (!registry || typeof registry.getItem !== "function") return void 0;
+    if (!registry) return void 0;
     const singular = PLURAL_TO_SINGULAR3[type] ?? type;
-    return registry.getItem(singular, name) ?? registry.getItem(type, name);
+    if (typeof registry.getArtifactItem === "function") {
+      return registry.getArtifactItem(singular, name) ?? registry.getArtifactItem(type, name);
+    }
+    if (typeof registry.getItem !== "function") return void 0;
+    const item = registry.getItem(singular, name) ?? registry.getItem(type, name);
+    if (!item || !item._packageId || item._packageId === "sys_metadata") {
+      return void 0;
+    }
+    return item;
   }
   /**
    * Resolve the effective `_lock` for an item by consulting the
@@ -4498,13 +4678,8 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * scope and the caller is expected to also gate on `environmentId`.
    */
   async getEffectiveLock(type, name, organizationId) {
-    const registry = this.engine?.registry;
-    const singular = PLURAL_TO_SINGULAR3[type] ?? type;
-    let artifactItem;
-    if (registry && typeof registry.getItem === "function") {
-      artifactItem = registry.getItem(singular, name) ?? registry.getItem(type, name);
-    }
-    if (artifactItem && artifactItem._packageId && artifactItem._packageId !== "sys_metadata") {
+    const artifactItem = this.lookupArtifactItem(type, name);
+    if (artifactItem) {
       const p = extractProtection(artifactItem);
       if (p.lock !== "none") {
         return { lock: p.lock, lockReason: p.lockReason, lockSource: "artifact" };
@@ -4645,6 +4820,49 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       );
     }
   }
+  /**
+   * Heal the in-memory registry after a metadata reset (overlay-row
+   * delete) on control-plane kernels. Two layers:
+   *
+   *  1. Drop the plain-key runtime shadow so the packaged artifact
+   *     (registered under `<packageId>:<name>`) becomes the visible
+   *     value again. The shadow is written by the overlay-hydration
+   *     paths (`getMetaItems` / `loadMetaFromDb`) and — pre-fix —
+   *     survived the reset until restart, leaving stale overlay
+   *     content (and a stripped `_lock` envelope) in every
+   *     registry-direct read (ADR-0010 §3.3).
+   *  2. When no composite-key artifact exists, fall back to the
+   *     MetadataService baseline (FilesystemLoader-sourced types) and
+   *     re-register it, preserving the historical refresh behaviour
+   *     for items the SchemaRegistry never held as artifacts.
+   *
+   * Best-effort: a failure must never block the delete that already
+   * succeeded; the next full reload fixes the registry anyway.
+   */
+  async restoreArtifactRegistryView(type, name) {
+    try {
+      const registry = this.engine.registry;
+      let healed = false;
+      if (typeof registry.removeRuntimeShadow === "function") {
+        const singular = PLURAL_TO_SINGULAR3[type] ?? type;
+        healed = registry.removeRuntimeShadow(singular, name);
+        if (type !== singular) {
+          healed = registry.removeRuntimeShadow(type, name) || healed;
+        }
+      }
+      if (healed) return;
+      if (this.environmentId !== void 0) return;
+      const services = this.getServicesRegistry?.();
+      const metadataService = services?.get("metadata");
+      if (metadataService && typeof metadataService.get === "function") {
+        const artifactItem = await metadataService.get(type, name);
+        if (artifactItem !== void 0) {
+          this.engine.registry.registerItem(type, artifactItem, "name");
+        }
+      }
+    } catch {
+    }
+  }
   /**
    * Ensure a just-PUBLISHED object's physical table exists so it is usable
    * for data CRUD immediately — without a server restart. Registering the
@@ -5466,6 +5684,9 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         const targetState = request.state === "draft" ? "draft" : "active";
         const current = await repo.get(ref, { state: targetState });
         if (!current) {
+          if (targetState === "active") {
+            await this.restoreArtifactRegistryView(request.type, request.name);
+          }
           return {
             success: true,
             reset: false,
@@ -5480,18 +5701,8 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           intent: this.isArtifactBacked(singularTypeForRepo, request.name) ? "override-artifact" : "runtime-only",
           state: targetState
         });
-        if (this.environmentId === void 0) {
-          try {
-            const services = this.getServicesRegistry?.();
-            const metadataService = services?.get("metadata");
-            if (metadataService && typeof metadataService.get === "function") {
-              const artifactItem = await metadataService.get(request.type, request.name);
-              if (artifactItem !== void 0) {
-                this.engine.registry.registerItem(request.type, artifactItem, "name");
-              }
-            }
-          } catch {
-          }
+        if (targetState === "active") {
+          await this.restoreArtifactRegistryView(request.type, request.name);
         }
         if (this.shouldDropStorage(request.type, request.name, request.dropStorage, targetState)) {
           await this.dropObjectStorage(singularTypeForRepo, request.name);
@@ -5550,18 +5761,8 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           await this.dropObjectStorage(PLURAL_TO_SINGULAR3[request.type] ?? request.type, request.name);
         }
       }
-      if (this.environmentId === void 0) {
-        try {
-          const services = this.getServicesRegistry?.();
-          const metadataService = services?.get("metadata");
-          if (metadataService && typeof metadataService.get === "function") {
-            const artifactItem = await metadataService.get(request.type, request.name);
-            if (artifactItem !== void 0) {
-              this.engine.registry.registerItem(request.type, artifactItem, "name");
-            }
-          }
-        } catch {
-        }
+      if (request.state !== "draft") {
+        await this.restoreArtifactRegistryView(request.type, request.name);
       }
       return {
         success: true,
@@ -5599,7 +5800,12 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           if (normalizedType === "object") {
             this.engine.registry.registerObject(data, record.packageId || "sys_metadata");
           } else {
-            this.engine.registry.registerItem(normalizedType, data, "name");
+            const artifact = this.lookupArtifactItem(normalizedType, data?.name);
+            this.engine.registry.registerItem(
+              normalizedType,
+              mergeArtifactProtection(data, artifact),
+              "name"
+            );
           }
           loaded++;
         } catch (e) {
@@ -7566,7 +7772,9 @@ var _ObjectQL = class _ObjectQL {
       "mappings",
       "analyticsCubes",
       // Integration Protocol
-      "connectors"
+      "connectors",
+      // System Protocol — package documentation (ADR-0046); inert data
+      "docs"
     ];
     for (const key of metadataArrayKeys) {
       const items = manifest[key];
@@ -7702,7 +7910,8 @@ var _ObjectQL = class _ObjectQL {
       "hooks",
       "mappings",
       "analyticsCubes",
-      "connectors"
+      "connectors",
+      "docs"
     ];
     for (const key of metadataArrayKeys) {
       const items = plugin[key];
@@ -9231,10 +9440,11 @@ var MetadataFacade = class {
    */
   async register(type, name, data) {
     const definition = typeof data === "object" && data !== null ? { ...data, name: data.name ?? name } : data;
+    const packageId = definition?._packageId;
     if (type === "object") {
-      this.registry.registerItem(type, definition, "name");
+      this.registry.registerItem(type, definition, "name", packageId);
     } else {
-      this.registry.registerItem(type, definition, definition.id ? "id" : "name");
+      this.registry.registerItem(type, definition, definition.id ? "id" : "name", packageId);
     }
   }
   /**
@@ -9908,7 +10118,7 @@ var ObjectQLPlugin = class {
                 return;
               }
               if (this.ql?.registry?.registerItem) {
-                this.ql.registry.registerItem(type, item, keyField);
+                this.ql.registry.registerItem(type, item, keyField, item._packageId);
               }
             });
             if (type === "hook" && this.ql && typeof this.ql.bindHooks === "function") {