@objectstack/objectql 9.2.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,6 +899,20 @@ function applySystemFields(schema, opts) {
     fields: { ...additions, ...schema.fields ?? {} }
   };
 }
+function isShareableNamespace(ns) {
+  return RESERVED_NAMESPACES.has(ns) || ns === "sys";
+}
+var NamespaceConflictError = class extends Error {
+  constructor(namespace, existingPackageId, incomingPackageId) {
+    super(
+      `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 = "NamespaceConflictError";
+    this.namespace = namespace;
+    this.existingPackageId = existingPackageId;
+    this.incomingPackageId = incomingPackageId;
+  }
+};
 var SchemaRegistry = class {
   constructor(options = {}) {
     // ==========================================
@@ -929,6 +956,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;
@@ -1289,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);
     }
@@ -1299,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;
@@ -1306,6 +1352,74 @@ 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, 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;
+        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
    */
@@ -1346,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 = {
@@ -1423,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);
   }
@@ -1644,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);
@@ -1693,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;
@@ -2177,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 {
@@ -2335,6 +2465,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;
@@ -2833,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) {
@@ -2846,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) {
@@ -2854,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 {
           }
@@ -3157,8 +3333,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());
@@ -3250,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);
         })
@@ -3264,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);
@@ -3291,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);
@@ -3337,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;
               }
@@ -3354,20 +3552,44 @@ 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 decorated = decorateMetadataItem(
+    const artifactItem = this.lookupArtifactItem(request.type, request.name, request.packageId);
+    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 {
@@ -3407,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.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;
     }
@@ -3428,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;
       };
@@ -4463,14 +4693,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)
@@ -4480,11 +4703,19 @@ 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 || 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, currentPackageId) ?? registry.getArtifactItem(type, name, currentPackageId);
+    }
+    if (typeof registry.getItem !== "function") return void 0;
+    const item = registry.getItem(singular, name, currentPackageId) ?? registry.getItem(type, name, currentPackageId);
+    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 +4729,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 +4871,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
@@ -4808,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 {
@@ -5466,6 +5738,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 +5755,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 +5815,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 +5854,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 +7826,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 +7964,8 @@ var _ObjectQL = class _ObjectQL {
       "hooks",
       "mappings",
       "analyticsCubes",
-      "connectors"
+      "connectors",
+      "docs"
     ];
     for (const key of metadataArrayKeys) {
       const items = plugin[key];
@@ -9231,17 +9494,24 @@ 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);
     }
   }
   /**
-   * 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;
   }
   /**
@@ -9320,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) => {
@@ -9444,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)");
@@ -9486,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
@@ -9908,7 +10180,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") {