@objectstack/objectql 9.3.0 → 9.4.0

package/dist/index.mjs

@@ -310,6 +310,19 @@ var init_seed_loader = __esm({
           if (records && records.length > 0) {
             return String(records[0].id || records[0]._id);
           }
+          if (targetField !== "id") {
+            const byId = { id: value };
+            if (organizationId) byId.organization_id = organizationId;
+            const idMatch = await this.engine.find(targetObject, {
+              where: byId,
+              fields: ["id"],
+              limit: 1,
+              context: { isSystem: true }
+            });
+            if (idMatch && idMatch.length > 0) {
+              return String(idMatch[0].id || idMatch[0]._id);
+            }
+          }
         } catch {
         }
         return null;
@@ -886,18 +899,16 @@ 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;
+function isShareableNamespace(ns) {
+  return RESERVED_NAMESPACES.has(ns) || ns === "sys";
 }
-var MetadataCollisionError = class extends Error {
-  constructor(type, name, existingPackageId, incomingPackageId) {
+var NamespaceConflictError = class extends Error {
+  constructor(namespace, 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.`
+      `Namespace conflict: namespace "${namespace}" is already owned by package "${existingPackageId}", so package "${incomingPackageId}" cannot be installed alongside it. A namespace is the mandatory prefix of every object name (e.g. "${namespace}_account") and the container that scopes a package's UI metadata, so it must be unique per installation. Choose a different namespace for "${incomingPackageId}", or uninstall "${existingPackageId}" first. 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.name = "NamespaceConflictError";
+    this.namespace = namespace;
     this.existingPackageId = existingPackageId;
     this.incomingPackageId = incomingPackageId;
   }
@@ -1253,17 +1264,6 @@ 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) {
@@ -1275,22 +1275,6 @@ 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
    */
@@ -1333,9 +1317,23 @@ var SchemaRegistry = class {
     console.warn(`[Registry] Attempted to unregister non-existent ${type}: ${name}`);
   }
   /**
-   * Universal Get Method
+   * Universal Get Method.
+   *
+   * ADR-0048 §3.3 — *package-scoped* resolution. When `currentPackageId` is
+   * given (the package the caller is resolving within — known from the route /
+   * `activeApp._packageId`), a bare name resolves to *that package's* item
+   * before any cross-package fallback, so two packages shipping e.g.
+   * `page/home` no longer resolve by registration order (first-match-wins).
+   * Because package ids are globally unique this is unambiguous. Omitting
+   * `currentPackageId` preserves the legacy resolution exactly (backward
+   * compatible) and is best-effort: it returns the first match.
+   *
+   * Precedence (highest first):
+   *   1. bare-key runtime/DB overlay (ADR-0005 sanctioned override) — unchanged
+   *   2. the `currentPackageId` composite entry (prefer-local)
+   *   3. first composite match (legacy first-registered-wins fallback)
    */
-  getItem(type, name) {
+  getItem(type, name, currentPackageId) {
     if (type === "object" || type === "objects") {
       return this.getObject(name);
     }
@@ -1343,6 +1341,10 @@ var SchemaRegistry = class {
     if (!collection) return void 0;
     const direct = collection.get(name);
     if (direct) return direct;
+    if (currentPackageId) {
+      const local = collection.get(`${currentPackageId}:${name}`);
+      if (local) return local;
+    }
     for (const [key, item] of collection) {
       if (key.endsWith(`:${name}`)) {
         return item;
@@ -1364,13 +1366,17 @@ var SchemaRegistry = class {
    * 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) {
+  getArtifactItem(type, name, currentPackageId) {
     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;
+    if (currentPackageId) {
+      const local = collection.get(`${currentPackageId}:${name}`);
+      if (local && local._packageId && local._packageId !== "sys_metadata") return local;
+    }
     for (const [key, item] of collection) {
       if (key !== name && key.endsWith(`:${name}`)) {
         const it = item;
@@ -1454,6 +1460,20 @@ var SchemaRegistry = class {
   // Package Management
   // ==========================================
   installPackage(manifest, settings) {
+    if (manifest.namespace && !isShareableNamespace(manifest.namespace)) {
+      const conflictOwner = this.getNamespaceOwners(manifest.namespace).find(
+        (owner) => owner !== manifest.id
+      );
+      if (conflictOwner) {
+        if (this.collisionPolicy === "warn") {
+          console.warn(
+            `[Registry] Namespace conflict (downgraded to warning via OS_METADATA_COLLISION=warn): namespace "${manifest.namespace}" is already owned by "${conflictOwner}"; installing "${manifest.id}" anyway. See ADR-0048.`
+          );
+        } else {
+          throw new NamespaceConflictError(manifest.namespace, conflictOwner, manifest.id);
+        }
+      }
+    }
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const disabled = this.initialDisabledPackageIds.has(manifest.id);
     const pkg = {
@@ -1531,8 +1551,8 @@ var SchemaRegistry = class {
   registerApp(app, packageId) {
     this.registerItem("app", app, "name", packageId);
   }
-  getApp(name) {
-    const app = this.getItem("app", name);
+  getApp(name, currentPackageId) {
+    const app = this.getItem("app", name, currentPackageId);
     if (!app) return app;
     return this.applyNavContributions(app);
   }
@@ -1752,7 +1772,7 @@ var SysMetadataRepository = class {
     this.assertOpen();
     const state = opts?.state ?? "active";
     const row = await this.engine.findOne("sys_metadata", {
-      where: this.whereFor(ref, state)
+      where: this.whereFor(ref, state, opts && "packageId" in opts ? opts.packageId ?? null : void 0)
     });
     if (!row) return null;
     return this.rowToItem(ref, row);
@@ -1801,7 +1821,7 @@ var SysMetadataRepository = class {
     const hash = hashSpec(body);
     const result = await this.withTxn(async (ctx) => {
       const existing = await this.engine.findOne("sys_metadata", {
-        where: this.whereFor(ref, state),
+        where: this.whereFor(ref, state, opts.packageId ?? null),
         context: ctx
       });
       const existingHash = existing?.checksum ?? null;
@@ -2285,13 +2305,15 @@ var SysMetadataRepository = class {
     err.status = 403;
     throw err;
   }
-  whereFor(ref, state = "active") {
-    return {
+  whereFor(ref, state = "active", packageId) {
+    const where = {
       type: ref.type,
       name: ref.name,
       organization_id: this.organizationId,
       state
     };
+    if (packageId !== void 0) where.package_id = packageId;
+    return where;
   }
   fullRef(ref) {
     return {
@@ -2983,8 +3005,8 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         await exec("DROP INDEX IF EXISTS idx_sys_metadata_overlay_active");
       } catch {
       }
-      const partialSql = "CREATE UNIQUE INDEX IF NOT EXISTS idx_sys_metadata_overlay_active ON sys_metadata (type, name, organization_id) WHERE state = 'active'";
-      const fallbackSql = "CREATE INDEX IF NOT EXISTS idx_sys_metadata_overlay_active ON sys_metadata (type, name, organization_id)";
+      const partialSql = "CREATE UNIQUE INDEX IF NOT EXISTS idx_sys_metadata_overlay_active ON sys_metadata (type, name, organization_id, COALESCE(package_id, '')) WHERE state = 'active'";
+      const fallbackSql = "CREATE INDEX IF NOT EXISTS idx_sys_metadata_overlay_active ON sys_metadata (type, name, organization_id, package_id)";
       try {
         await exec(partialSql);
       } catch (err) {
@@ -2996,7 +3018,11 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           }
         }
       }
-      const draftPartialSql = "CREATE UNIQUE INDEX IF NOT EXISTS idx_sys_metadata_overlay_draft ON sys_metadata (type, name, organization_id) WHERE state = 'draft'";
+      try {
+        await exec("DROP INDEX IF EXISTS idx_sys_metadata_overlay_draft");
+      } catch {
+      }
+      const draftPartialSql = "CREATE UNIQUE INDEX IF NOT EXISTS idx_sys_metadata_overlay_draft ON sys_metadata (type, name, organization_id, COALESCE(package_id, '')) WHERE state = 'draft'";
       try {
         await exec(draftPartialSql);
       } catch (err) {
@@ -3004,7 +3030,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         if (/partial|where clause|syntax/i.test(msg)) {
           try {
             await exec(
-              "CREATE INDEX IF NOT EXISTS idx_sys_metadata_overlay_draft ON sys_metadata (type, name, organization_id)"
+              "CREATE INDEX IF NOT EXISTS idx_sys_metadata_overlay_draft ON sys_metadata (type, name, organization_id, package_id)"
             );
           } catch {
           }
@@ -3405,7 +3431,8 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         items.map((it) => {
           const a = this.lookupArtifactItem(
             request.type,
-            it?.name
+            it?.name,
+            packageId ?? it?._packageId
           );
           return mergeArtifactProtection(it, a);
         })
@@ -3419,16 +3446,28 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (request.previewDrafts && readState !== "draft") {
       try {
         const findDraft = async (oid) => {
-          const rec = await this.engine.findOne("sys_metadata", {
-            where: { type: request.type, name: request.name, state: "draft", organization_id: oid }
-          });
+          const lookup = async (t) => {
+            const base = {
+              type: t,
+              name: request.name,
+              state: "draft",
+              organization_id: oid
+            };
+            if (request.packageId) {
+              const scoped = await this.engine.findOne("sys_metadata", {
+                where: { ...base, package_id: request.packageId }
+              });
+              if (scoped) return scoped;
+              return await this.engine.findOne("sys_metadata", {
+                where: { ...base, package_id: null }
+              });
+            }
+            return await this.engine.findOne("sys_metadata", { where: base });
+          };
+          const rec = await lookup(request.type);
           if (rec) return rec;
           const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
-          if (alt) {
-            return await this.engine.findOne("sys_metadata", {
-              where: { type: alt, name: request.name, state: "draft", organization_id: oid }
-            });
-          }
+          if (alt) return await lookup(alt);
           return void 0;
         };
         const draftRec = (orgId ? await findDraft(orgId) : void 0) ?? await findDraft(null);
@@ -3446,24 +3485,28 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     }
     try {
       const findOverlay = async (oid) => {
-        const where = {
-          type: request.type,
-          name: request.name,
-          state: readState,
-          organization_id: oid
-        };
-        const rec = await this.engine.findOne("sys_metadata", { where });
-        if (rec) return rec;
-        const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
-        if (alt) {
-          const altWhere = {
-            type: alt,
+        const lookup = async (t) => {
+          const base = {
+            type: t,
             name: request.name,
             state: readState,
             organization_id: oid
           };
-          return await this.engine.findOne("sys_metadata", { where: altWhere });
-        }
+          if (request.packageId) {
+            const scoped = await this.engine.findOne("sys_metadata", {
+              where: { ...base, package_id: request.packageId }
+            });
+            if (scoped) return scoped;
+            return await this.engine.findOne("sys_metadata", {
+              where: { ...base, package_id: null }
+            });
+          }
+          return await this.engine.findOne("sys_metadata", { where: base });
+        };
+        const rec = await lookup(request.type);
+        if (rec) return rec;
+        const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+        if (alt) return await lookup(alt);
         return void 0;
       };
       const record = (orgId ? await findOverlay(orgId) : void 0) ?? await findOverlay(null);
@@ -3492,13 +3535,13 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         const services = this.getServicesRegistry?.();
         const metadataService = services?.get("metadata");
         if (metadataService && typeof metadataService.get === "function") {
-          const fromService = await metadataService.get(request.type, request.name);
+          const fromService = await metadataService.get(request.type, request.name, request.packageId);
           if (fromService !== void 0 && fromService !== null) {
             item = fromService;
           } else {
             const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
             if (alt) {
-              const altFromService = await metadataService.get(alt, request.name);
+              const altFromService = await metadataService.get(alt, request.name, request.packageId);
               if (altFromService !== void 0 && altFromService !== null) {
                 item = altFromService;
               }
@@ -3509,16 +3552,16 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
     }
     if (item === void 0) {
-      item = this.engine.registry.getItem(request.type, request.name);
+      item = this.engine.registry.getItem(request.type, request.name, request.packageId);
       if (item === void 0) {
         const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
-        if (alt) item = this.engine.registry.getItem(alt, request.name);
+        if (alt) item = this.engine.registry.getItem(alt, request.name, request.packageId);
       }
     }
     if ((request.type === "app" || request.type === "apps") && item) {
       item = this.engine.registry.applyNavContributions(item);
     }
-    const artifactItem = this.lookupArtifactItem(request.type, request.name);
+    const artifactItem = this.lookupArtifactItem(request.type, request.name, request.packageId);
     let decorated = decorateMetadataItem(
       request.type,
       mergeArtifactProtection(item, artifactItem)
@@ -3586,20 +3629,20 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       const services = this.getServicesRegistry?.();
       const metadataService = services?.get("metadata");
       if (metadataService && typeof metadataService.get === "function") {
-        let fromService = await metadataService.get(request.type, request.name);
+        let fromService = await metadataService.get(request.type, request.name, request.packageId);
         if (fromService === void 0 || fromService === null) {
           const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
-          if (alt) fromService = await metadataService.get(alt, request.name);
+          if (alt) fromService = await metadataService.get(alt, request.name, request.packageId);
         }
         if (fromService !== void 0 && fromService !== null) code = fromService;
       }
     } catch {
     }
     if (code === null) {
-      let regItem = this.lookupArtifactItem(request.type, request.name) ?? this.engine.registry.getItem(request.type, request.name);
+      let regItem = this.lookupArtifactItem(request.type, request.name, request.packageId) ?? this.engine.registry.getItem(request.type, request.name, request.packageId);
       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);
+        if (alt) regItem = this.engine.registry.getItem(alt, request.name, request.packageId);
       }
       if (regItem !== void 0) code = regItem;
     }
@@ -3607,20 +3650,28 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     let overlayScope = null;
     try {
       const findOverlay = async (oid) => {
-        const where = {
-          type: request.type,
-          name: request.name,
-          state: "active",
-          organization_id: oid
+        const lookup = async (t) => {
+          const base = {
+            type: t,
+            name: request.name,
+            state: "active",
+            organization_id: oid
+          };
+          if (request.packageId) {
+            const scoped = await this.engine.findOne("sys_metadata", {
+              where: { ...base, package_id: request.packageId }
+            });
+            if (scoped) return scoped;
+            return await this.engine.findOne("sys_metadata", {
+              where: { ...base, package_id: null }
+            });
+          }
+          return await this.engine.findOne("sys_metadata", { where: base });
         };
-        let rec = await this.engine.findOne("sys_metadata", { where });
+        let rec = await lookup(request.type);
         if (!rec) {
           const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
-          if (alt) {
-            rec = await this.engine.findOne("sys_metadata", {
-              where: { ...where, type: alt }
-            });
-          }
+          if (alt) rec = await lookup(alt);
         }
         return rec;
       };
@@ -4652,15 +4703,15 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * type and its singular/plural twin. Returns `undefined` when the
    * registry is unavailable or the item is not artifact-backed.
    */
-  lookupArtifactItem(type, name) {
+  lookupArtifactItem(type, name, currentPackageId) {
     const registry = this.engine?.registry;
     if (!registry) return void 0;
     const singular = PLURAL_TO_SINGULAR3[type] ?? type;
     if (typeof registry.getArtifactItem === "function") {
-      return registry.getArtifactItem(singular, name) ?? registry.getArtifactItem(type, name);
+      return registry.getArtifactItem(singular, name, currentPackageId) ?? registry.getArtifactItem(type, name, currentPackageId);
     }
     if (typeof registry.getItem !== "function") return void 0;
-    const item = registry.getItem(singular, name) ?? registry.getItem(type, name);
+    const item = registry.getItem(singular, name, currentPackageId) ?? registry.getItem(type, name, currentPackageId);
     if (!item || !item._packageId || item._packageId === "sys_metadata") {
       return void 0;
     }
@@ -5026,7 +5077,10 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       if (request.parentVersion !== void 0) {
         parentVersion = request.parentVersion;
       } else {
-        const current = await repo.get(ref, { state: mode === "draft" ? "draft" : "active" });
+        const current = await repo.get(ref, {
+          state: mode === "draft" ? "draft" : "active",
+          packageId: request.packageId ?? null
+        });
         parentVersion = current?.hash ?? null;
       }
       try {
@@ -9448,10 +9502,16 @@ var MetadataFacade = class {
     }
   }
   /**
-   * Get a metadata item by type and name
-   */
-  async get(type, name) {
-    const item = this.registry.getItem(type, name);
+   * Get a metadata item by type and name.
+   *
+   * `currentPackageId` (ADR-0048) opts into package-scoped resolution: when two
+   * installed packages ship an item of the same `type`/`name`, the registry
+   * prefers the one owned by `currentPackageId` (composite key
+   * `${packageId}:${name}`) before falling back to first-match. Omit it for the
+   * legacy context-free lookup.
+   */
+  async get(type, name, currentPackageId) {
+    const item = this.registry.getItem(type, name, currentPackageId);
     return item?.content ?? item;
   }
   /**
@@ -9530,6 +9590,7 @@ var ObjectQLPlugin = class {
      */
     this.startupTimeout = 12e4;
     this.skipSchemaSync = false;
+    this.hydrateMetadataFromDb = false;
     /** Unsubscribe handles for metadata-event subscriptions (ADR-0008 PR-7). */
     this.metadataUnsubscribes = [];
     this.init = async (ctx) => {
@@ -9654,7 +9715,7 @@ var ObjectQLPlugin = class {
       } else {
         await this.syncRegisteredSchemas(ctx);
       }
-      if (this.environmentId === void 0) {
+      if (this.environmentId === void 0 || this.hydrateMetadataFromDb) {
         await this.restoreMetadataFromDb(ctx);
       } else {
         ctx.logger.info("Project kernel \u2014 skipping sys_metadata hydration (metadata sourced from artifact)");
@@ -9696,6 +9757,7 @@ var ObjectQLPlugin = class {
       this.startupTimeout = opts.startupTimeout;
     }
     this.skipSchemaSync = typeof opts.skipSchemaSync === "boolean" ? opts.skipSchemaSync : process.env.OS_SKIP_SCHEMA_SYNC === "1";
+    this.hydrateMetadataFromDb = opts.hydrateMetadataFromDb === true;
   }
   /**
    * Subscribe to `object` metadata events from the metadata service and