@objectstack/objectql 7.2.0 → 7.3.0

package/dist/index.mjs

@@ -1,7 +1,9 @@
 // src/registry.ts
 import { ObjectSchema } from "@objectstack/spec/data";
+import { readEnvWithDeprecation } from "@objectstack/types";
 import { ManifestSchema, InstalledPackageSchema } from "@objectstack/spec/kernel";
 import { AppSchema } from "@objectstack/spec/ui";
+import { applyProtection } from "@objectstack/spec/shared";
 var RESERVED_NAMESPACES = /* @__PURE__ */ new Set(["base", "system"]);
 var DEFAULT_OWNER_PRIORITY = 100;
 var DEFAULT_EXTENDER_PRIORITY = 200;
@@ -126,10 +128,19 @@ var SchemaRegistry = class {
     // ==========================================
     /** Type → Name/ID → MetadataItem */
     this.metadata = /* @__PURE__ */ new Map();
+    /**
+     * Package ids that must be installed in a DISABLED state. Seeded once at
+     * boot (from persisted state) BEFORE any package registration so that every
+     * registration path — boot artifact, marketplace rehydrate, local import —
+     * honors persisted disable state uniformly without a fragile post-boot
+     * re-application hook. See {@link setInitialDisabledPackageIds} and
+     * {@link installPackage}.
+     */
+    this.initialDisabledPackageIds = /* @__PURE__ */ new Set();
     if (options.multiTenant !== void 0) {
       this.multiTenant = options.multiTenant;
     } else {
-      this.multiTenant = String(process.env.OS_MULTI_TENANT ?? "false").toLowerCase() !== "false";
+      this.multiTenant = String(readEnvWithDeprecation("OS_MULTI_ORG_ENABLED", "OS_MULTI_TENANT") ?? "false").toLowerCase() !== "false";
     }
   }
   get logLevel() {
@@ -142,6 +153,14 @@ var SchemaRegistry = class {
     if (this._logLevel === "silent" || this._logLevel === "error" || this._logLevel === "warn") return;
     console.log(msg);
   }
+  /**
+   * Seed the set of package ids that should be installed disabled. Call this
+   * before package registration begins; later `installPackage` calls for these
+   * ids land in the `disabled` state. Replaces any previously seeded set.
+   */
+  setInitialDisabledPackageIds(ids) {
+    this.initialDisabledPackageIds = new Set(ids);
+  }
   // ==========================================
   // Namespace Management
   // ==========================================
@@ -231,6 +250,7 @@ var SchemaRegistry = class {
         contributors.splice(idx, 1);
       }
     }
+    applyProtection(schema, { packageId });
     const contributor = {
       packageId,
       namespace: namespace || "",
@@ -378,9 +398,7 @@ var SchemaRegistry = class {
     }
     const collection = this.metadata.get(type);
     const baseName = String(item[keyField]);
-    if (packageId) {
-      item._packageId = packageId;
-    }
+    applyProtection(item, { packageId });
     try {
       this.validate(type, item);
     } catch (e) {
@@ -468,10 +486,23 @@ var SchemaRegistry = class {
       return this.getAllObjects(packageId);
     }
     const items = Array.from(this.metadata.get(type)?.values() || []);
+    let result = items;
     if (packageId) {
-      return items.filter((item) => item._packageId === packageId);
+      result = result.filter((item) => item._packageId === packageId);
+    }
+    if (type !== "package") {
+      result = result.filter((item) => !this.isPackageDisabled(item?._packageId));
     }
-    return items;
+    return result;
+  }
+  /**
+   * Whether a package has been explicitly disabled. Unknown packages and
+   * items with no owning package are treated as enabled.
+   */
+  isPackageDisabled(packageId) {
+    if (!packageId) return false;
+    const pkg = this.getPackage(packageId);
+    return pkg?.enabled === false || pkg?.status === "disabled";
   }
   /**
    * Get all registered metadata types (Kinds)
@@ -488,12 +519,14 @@ var SchemaRegistry = class {
   // ==========================================
   installPackage(manifest, settings) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
+    const disabled = this.initialDisabledPackageIds.has(manifest.id);
     const pkg = {
       manifest,
-      status: "installed",
-      enabled: true,
+      status: disabled ? "disabled" : "installed",
+      enabled: !disabled,
       installedAt: now,
       updatedAt: now,
+      ...disabled ? { statusChangedAt: now } : {},
       settings
     };
     if (manifest.namespace) {
@@ -629,8 +662,12 @@ var SchemaRegistry = class {
   }
 };
 
+// src/protocol.ts
+import { readEnvWithDeprecation as readEnvWithDeprecation3 } from "@objectstack/types";
+
 // src/sys-metadata-repository.ts
 import { hashSpec, ConflictError } from "@objectstack/metadata-core";
+import { readEnvWithDeprecation as readEnvWithDeprecation2 } from "@objectstack/types";
 import { DEFAULT_METADATA_TYPE_REGISTRY } from "@objectstack/spec/kernel";
 import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from "@objectstack/spec/shared";
 var OVERLAY_ALLOWED_TYPES = new Set(
@@ -645,7 +682,7 @@ var RUNTIME_CREATE_ALLOWED_TYPES = new Set(
 var _envWritableMetadataTypes = null;
 function envWritableMetadataTypes() {
   if (_envWritableMetadataTypes !== null) return _envWritableMetadataTypes;
-  const raw = typeof process !== "undefined" && process?.env?.OBJECTSTACK_METADATA_WRITABLE || "";
+  const raw = readEnvWithDeprecation2("OS_METADATA_WRITABLE", "OBJECTSTACK_METADATA_WRITABLE") || "";
   const set = /* @__PURE__ */ new Set();
   for (const tok of raw.split(",")) {
     const t = tok.trim();
@@ -775,6 +812,12 @@ var SysMetadataRepository = class {
         version,
         updated_at: now
       };
+      if (existing) {
+        const existingPkg = existing.package_id ?? null;
+        parentRowData.package_id = existingPkg ?? opts.packageId ?? null;
+      } else {
+        parentRowData.package_id = opts.packageId ?? null;
+      }
       if (existing) {
         const existingId = existing.id;
         if (existingId === void 0) {
@@ -1172,7 +1215,7 @@ var SysMetadataRepository = class {
    * at `(type, name)`. In that case we accept types with
    * `allowRuntimeCreate: true`, even when `allowOrgOverride` is false.
    *
-   * The env-var escape hatch (`OBJECTSTACK_METADATA_WRITABLE`) still
+   * The env-var escape hatch (`OS_METADATA_WRITABLE`) still
    * applies to BOTH intents, so operators can opt into artifact
    * overrides at runtime for emergency fixes.
    */
@@ -1197,7 +1240,7 @@ var SysMetadataRepository = class {
     const code = intent === "runtime-only" ? "not_creatable" : "not_overridable";
     const detail = intent === "runtime-only" ? `'${type}' has neither allowOrgOverride nor allowRuntimeCreate in the registry. ` : `'${type}' is not allowOrgOverride in the registry. `;
     const err = new Error(
-      `[${code}] ${detail}Overlay-allowed: ${Array.from(new Set(allowed)).join(", ") || "(none)"}. Set OBJECTSTACK_METADATA_WRITABLE to enable additional types at runtime.`
+      `[${code}] ${detail}Overlay-allowed: ${Array.from(new Set(allowed)).join(", ") || "(none)"}. Set OS_METADATA_WRITABLE to enable additional types at runtime.`
     );
     err.code = code;
     err.status = 403;
@@ -1569,6 +1612,8 @@ function mergeArtifactProtection(item, artifactItem) {
   const out = { ...item };
   if (a._lock !== void 0) out._lock = a._lock;
   if (a._lockReason !== void 0) out._lockReason = a._lockReason;
+  if (a._lockDocsUrl !== void 0) out._lockDocsUrl = a._lockDocsUrl;
+  if (a._lockSource !== void 0) out._lockSource = a._lockSource;
   if (a._packageId !== void 0) out._packageId = a._packageId;
   if (a._packageVersion !== void 0) out._packageVersion = a._packageVersion;
   if (a._provenance !== void 0) out._provenance = a._provenance;
@@ -2080,10 +2125,13 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
       const items = Array.isArray(listed?.items) ? listed.items : Array.isArray(listed) ? listed : [];
       const pkgSet = /* @__PURE__ */ new Set();
+      let lockedCount = 0;
       for (const item of items) {
         scannedItems += 1;
         const pkg = item?._packageId ?? null;
         if (pkg) pkgSet.add(pkg);
+        const lock = item?._lock;
+        if (lock && lock !== "none") lockedCount += 1;
         const diag = item?._diagnostics ?? computeMetadataDiagnostics(t, item);
         if (!diag) continue;
         if (diag.valid && !includeWarnings) continue;
@@ -2094,7 +2142,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           diagnostics: diag
         });
       }
-      stats[t] = { count: items.length, packages: [...pkgSet].sort() };
+      stats[t] = { count: items.length, locked: lockedCount, packages: [...pkgSet].sort() };
     }
     return {
       entries,
@@ -2128,13 +2176,13 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           state: "active",
           organization_id: oid
         };
-        if (packageId) whereClause._packageId = packageId;
+        if (packageId) whereClause.package_id = packageId;
         let rs = await this.engine.find("sys_metadata", { where: whereClause });
         if (!rs || rs.length === 0) {
           const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
           if (alt) {
             const altWhere = { type: alt, state: "active", organization_id: oid };
-            if (packageId) altWhere._packageId = packageId;
+            if (packageId) altWhere.package_id = packageId;
             rs = await this.engine.find("sys_metadata", { where: altWhere });
           }
         }
@@ -2157,6 +2205,10 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         for (const record of records) {
           const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
           if (data && typeof data === "object" && "name" in data) {
+            const recPkg = record.package_id ?? void 0;
+            if (recPkg && data._packageId === void 0) {
+              data._packageId = recPkg;
+            }
             byName.set(data.name, data);
           }
           if (this.environmentId === void 0) {
@@ -2196,6 +2248,11 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
     } catch {
     }
+    if (request.type !== "package" && request.type !== "object" && request.type !== "objects") {
+      items = items.filter(
+        (it) => !this.engine.registry.isPackageDisabled(it?._packageId)
+      );
+    }
     return {
       type: request.type,
       items: decorateMetadataItems(
@@ -2239,6 +2296,10 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       const record = (orgId ? await findOverlay(orgId) : void 0) ?? await findOverlay(null);
       if (record) {
         item = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
+        const recPkg = record.package_id ?? void 0;
+        if (recPkg && item && typeof item === "object" && item._packageId === void 0) {
+          item._packageId = recPkg;
+        }
       }
     } catch {
     }
@@ -2295,6 +2356,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       lock: lockState.lock,
       ...lockState.lockReason !== void 0 ? { lockReason: lockState.lockReason } : {},
       ...lockState.lockSource !== void 0 ? { lockSource: lockState.lockSource } : {},
+      ...lockState.lockDocsUrl !== void 0 ? { lockDocsUrl: lockState.lockDocsUrl } : {},
       ...lockState.provenance !== void 0 ? { provenance: lockState.provenance } : {},
       ...lockState.packageId !== void 0 ? { packageId: lockState.packageId } : {},
       ...lockState.packageVersion !== void 0 ? { packageVersion: lockState.packageVersion } : {},
@@ -2394,6 +2456,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       lock: lockState.lock,
       ...lockState.lockReason !== void 0 ? { lockReason: lockState.lockReason } : {},
       ...lockState.lockSource !== void 0 ? { lockSource: lockState.lockSource } : {},
+      ...lockState.lockDocsUrl !== void 0 ? { lockDocsUrl: lockState.lockDocsUrl } : {},
       ...lockState.provenance !== void 0 ? { provenance: lockState.provenance } : {},
       ...lockState.packageId !== void 0 ? { packageId: lockState.packageId } : {},
       ...lockState.packageVersion !== void 0 ? { packageVersion: lockState.packageVersion } : {},
@@ -3326,7 +3389,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
   }
   static envWritableTypes() {
     if (this._envWritableTypes !== null) return this._envWritableTypes;
-    const raw = typeof process !== "undefined" && process?.env?.OBJECTSTACK_METADATA_WRITABLE || "";
+    const raw = readEnvWithDeprecation3("OS_METADATA_WRITABLE", "OBJECTSTACK_METADATA_WRITABLE") || "";
     const set = /* @__PURE__ */ new Set();
     for (const tok of raw.split(",")) {
       const t = tok.trim();
@@ -3572,7 +3635,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       const artifactBacked = this.isArtifactBacked(request.type, request.name);
       if (artifactBacked && !overlayAllowed) {
         const err = new Error(
-          `[not_overridable] Metadata item '${request.type}/${request.name}' is provided by a code package and the type has not opted into per-org overlay writes (allowOrgOverride=false). Edit the source artifact and redeploy, or set OBJECTSTACK_METADATA_WRITABLE to grant a runtime escape hatch. See docs/adr/0005-metadata-customization-overlay.md.`
+          `[not_overridable] Metadata item '${request.type}/${request.name}' is provided by a code package and the type has not opted into per-org overlay writes (allowOrgOverride=false). Edit the source artifact and redeploy, or set OS_METADATA_WRITABLE to grant a runtime escape hatch. See docs/adr/0005-metadata-customization-overlay.md.`
         );
         err.code = "not_overridable";
         err.status = 403;
@@ -3622,6 +3685,18 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         if (err?.code === "destructive_change") throw err;
       }
     }
+    {
+      const it = request.item;
+      const looksLikeLayeredEnvelope = it && typeof it === "object" && !Array.isArray(it) && "code" in it && "overlay" in it && "overlayScope" in it && "effective" in it;
+      if (looksLikeLayeredEnvelope) {
+        const err = new Error(
+          `[invalid_metadata] ${request.type}/${request.name}: the request body is a layered read envelope ({ code, overlay, overlayScope, effective }), not a metadata body. Unwrap and send the effective/overlay document instead \u2014 the layered shape is read-only (GET ?layers=true) and must never be persisted.`
+        );
+        err.code = "invalid_metadata";
+        err.status = 422;
+        throw err;
+      }
+    }
     {
       const schema = resolveOverlaySchema(request.type, request.item);
       if (schema) {
@@ -3671,7 +3746,8 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           actor: request.actor ?? "system",
           source: "protocol.saveMetaItem",
           intent,
-          state: mode === "draft" ? "draft" : "active"
+          state: mode === "draft" ? "draft" : "active",
+          ...request.packageId !== void 0 ? { packageId: request.packageId } : {}
         });
         if (mode === "publish") {
           this.applyObjectRegistryMutation(request);
@@ -3722,12 +3798,16 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         where: scopedWhere
       });
       if (existing) {
-        await this.engine.update("sys_metadata", {
+        const updateRow = {
           metadata: JSON.stringify(request.item),
           updated_at: now,
           version: (existing.version || 0) + 1,
           state: "active"
-        }, {
+        };
+        const existingPkg = existing.package_id ?? null;
+        const nextPkg = existingPkg ?? request.packageId ?? null;
+        if (nextPkg !== null) updateRow.package_id = nextPkg;
+        await this.engine.update("sys_metadata", updateRow, {
           where: { id: existing.id }
         });
       } else {
@@ -3747,6 +3827,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           updated_at: now,
           organization_id: orgId
         };
+        if (request.packageId) row.package_id = request.packageId;
         await this.engine.insert("sys_metadata", row);
       }
       return {
@@ -4419,7 +4500,7 @@ _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES = (() => {
   return out;
 })();
 /**
- * Phase 3a-env-writable: parse `OBJECTSTACK_METADATA_WRITABLE` once.
+ * Phase 3a-env-writable: parse `OS_METADATA_WRITABLE` once.
  * Comma-separated singular type names. When the env var is set, the
  * listed types get treated as `allowOrgOverride: true` regardless of
  * their static registry entry. This is the runtime escape hatch admins
@@ -5724,6 +5805,8 @@ var _ObjectQL = class _ObjectQL {
       "policies",
       // AI Protocol
       "agents",
+      "tools",
+      "skills",
       "ragPipelines",
       // API Protocol
       "apis",