@objectstack/objectql 7.2.0 → 7.2.1

package/dist/index.d.mts

@@ -536,6 +536,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
          */
         stats: Record<string, {
             count: number;
+            locked: number;
             packages: string[];
         }>;
     }>;
@@ -564,6 +565,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         packageVersion?: string | undefined;
         packageId?: string | undefined;
         provenance?: "package" | "env-forced" | "org" | undefined;
+        lockDocsUrl?: string | undefined;
         lockSource?: "artifact" | "package" | "env-forced" | undefined;
         lockReason?: string | undefined;
         type: string;
@@ -609,6 +611,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         lock: MetadataLock;
         lockReason?: string;
         lockSource?: 'artifact' | 'package' | 'env-forced' | 'overlay';
+        lockDocsUrl?: string;
         provenance?: MetadataProvenance;
         packageId?: string;
         packageVersion?: string;
@@ -865,7 +868,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      */
     private static readonly OVERLAY_ALLOWED_TYPES;
     /**
-     * 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
@@ -1346,7 +1349,7 @@ declare class SysMetadataRepository implements MetadataRepository {
      * 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.
      */

package/dist/index.d.ts

@@ -536,6 +536,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
          */
         stats: Record<string, {
             count: number;
+            locked: number;
             packages: string[];
         }>;
     }>;
@@ -564,6 +565,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         packageVersion?: string | undefined;
         packageId?: string | undefined;
         provenance?: "package" | "env-forced" | "org" | undefined;
+        lockDocsUrl?: string | undefined;
         lockSource?: "artifact" | "package" | "env-forced" | undefined;
         lockReason?: string | undefined;
         type: string;
@@ -609,6 +611,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         lock: MetadataLock;
         lockReason?: string;
         lockSource?: 'artifact' | 'package' | 'env-forced' | 'overlay';
+        lockDocsUrl?: string;
         provenance?: MetadataProvenance;
         packageId?: string;
         packageVersion?: string;
@@ -865,7 +868,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      */
     private static readonly OVERLAY_ALLOWED_TYPES;
     /**
-     * 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
@@ -1346,7 +1349,7 @@ declare class SysMetadataRepository implements MetadataRepository {
      * 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.
      */

package/dist/index.js

@@ -50,8 +50,10 @@ module.exports = __toCommonJS(index_exports);
 
 // src/registry.ts
 var import_data = require("@objectstack/spec/data");
+var import_types = require("@objectstack/types");
 var import_kernel = require("@objectstack/spec/kernel");
 var import_ui = require("@objectstack/spec/ui");
+var import_shared = require("@objectstack/spec/shared");
 var RESERVED_NAMESPACES = /* @__PURE__ */ new Set(["base", "system"]);
 var DEFAULT_OWNER_PRIORITY = 100;
 var DEFAULT_EXTENDER_PRIORITY = 200;
@@ -179,7 +181,7 @@ var SchemaRegistry = class {
     if (options.multiTenant !== void 0) {
       this.multiTenant = options.multiTenant;
     } else {
-      this.multiTenant = String(process.env.OS_MULTI_TENANT ?? "false").toLowerCase() !== "false";
+      this.multiTenant = String((0, import_types.readEnvWithDeprecation)("OS_MULTI_ORG_ENABLED", "OS_MULTI_TENANT") ?? "false").toLowerCase() !== "false";
     }
   }
   get logLevel() {
@@ -281,6 +283,7 @@ var SchemaRegistry = class {
         contributors.splice(idx, 1);
       }
     }
+    (0, import_shared.applyProtection)(schema, { packageId });
     const contributor = {
       packageId,
       namespace: namespace || "",
@@ -428,9 +431,7 @@ var SchemaRegistry = class {
     }
     const collection = this.metadata.get(type);
     const baseName = String(item[keyField]);
-    if (packageId) {
-      item._packageId = packageId;
-    }
+    (0, import_shared.applyProtection)(item, { packageId });
     try {
       this.validate(type, item);
     } catch (e) {
@@ -679,10 +680,14 @@ var SchemaRegistry = class {
   }
 };
 
+// src/protocol.ts
+var import_types3 = require("@objectstack/types");
+
 // src/sys-metadata-repository.ts
 var import_metadata_core = require("@objectstack/metadata-core");
+var import_types2 = require("@objectstack/types");
 var import_kernel2 = require("@objectstack/spec/kernel");
-var import_shared = require("@objectstack/spec/shared");
+var import_shared2 = require("@objectstack/spec/shared");
 var OVERLAY_ALLOWED_TYPES = new Set(
   import_kernel2.DEFAULT_METADATA_TYPE_REGISTRY.filter((e) => e.allowOrgOverride).map((e) => e.type)
 );
@@ -695,14 +700,14 @@ 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 = (0, import_types2.readEnvWithDeprecation)("OS_METADATA_WRITABLE", "OBJECTSTACK_METADATA_WRITABLE") || "";
   const set = /* @__PURE__ */ new Set();
   for (const tok of raw.split(",")) {
     const t = tok.trim();
     if (!t) continue;
-    const singular = import_shared.PLURAL_TO_SINGULAR[t] ?? t;
+    const singular = import_shared2.PLURAL_TO_SINGULAR[t] ?? t;
     set.add(singular);
-    const plural = import_shared.SINGULAR_TO_PLURAL[singular];
+    const plural = import_shared2.SINGULAR_TO_PLURAL[singular];
     if (plural) set.add(plural);
   }
   _envWritableMetadataTypes = set;
@@ -1222,12 +1227,12 @@ 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.
    */
   assertAllowed(type, intent = "override-artifact") {
-    const singular = import_shared.PLURAL_TO_SINGULAR[type] ?? type;
+    const singular = import_shared2.PLURAL_TO_SINGULAR[type] ?? type;
     const allowedByRegistry = OVERLAY_ALLOWED_TYPES.has(singular) || OVERLAY_ALLOWED_TYPES.has(type);
     if (allowedByRegistry) return;
     if (intent === "runtime-only") {
@@ -1247,7 +1252,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;
@@ -1355,7 +1360,7 @@ var SysMetadataRepository = class {
 // src/protocol.ts
 var import_metadata_core2 = require("@objectstack/metadata-core");
 var import_data2 = require("@objectstack/spec/data");
-var import_shared3 = require("@objectstack/spec/shared");
+var import_shared4 = require("@objectstack/spec/shared");
 var import_system = require("@objectstack/spec/system");
 var import_kernel4 = require("@objectstack/spec/kernel");
 var import_kernel5 = require("@objectstack/spec/kernel");
@@ -1363,9 +1368,9 @@ var import_zod = require("zod");
 
 // src/metadata-diagnostics.ts
 var import_kernel3 = require("@objectstack/spec/kernel");
-var import_shared2 = require("@objectstack/spec/shared");
+var import_shared3 = require("@objectstack/spec/shared");
 function computeMetadataDiagnostics(type, item) {
-  const singular = import_shared2.PLURAL_TO_SINGULAR[type] ?? type;
+  const singular = import_shared3.PLURAL_TO_SINGULAR[type] ?? type;
   const schema = (0, import_kernel3.getMetadataTypeSchema)(singular);
   if (!schema) return void 0;
   if (item === null || item === void 0 || typeof item !== "object") {
@@ -1603,7 +1608,7 @@ var HAND_CRAFTED_SCHEMAS = {
   }
 };
 function resolveOverlaySchema(type, _item) {
-  const singular = import_shared3.PLURAL_TO_SINGULAR[type] ?? type;
+  const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
   return (0, import_kernel4.getMetadataTypeSchema)(singular) ?? null;
 }
 function mergeArtifactProtection(item, artifactItem) {
@@ -1614,6 +1619,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;
@@ -2044,7 +2051,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       import_kernel4.DEFAULT_METADATA_TYPE_REGISTRY.map((e) => [e.type, e])
     );
     const entries = allTypes.map((type) => {
-      const singular = import_shared3.PLURAL_TO_SINGULAR[type] ?? type;
+      const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
       const zodSchema = (0, import_kernel4.getMetadataTypeSchema)(singular);
       const schema = (zodSchema ? toJsonSchemaSafe(zodSchema) : void 0) ?? HAND_CRAFTED_SCHEMAS[singular];
       const form = TYPE_TO_FORM[singular];
@@ -2125,10 +2132,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;
@@ -2139,7 +2149,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,
@@ -2155,13 +2165,13 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (this.environmentId === void 0) {
       items = [...this.engine.registry.listItems(request.type, packageId)];
       if (items.length === 0) {
-        const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
         if (alt) items = [...this.engine.registry.listItems(alt, packageId)];
       }
     } else {
       items = [...this.engine.registry.listItems(request.type, packageId)];
       if (items.length === 0) {
-        const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
         if (alt) items = [...this.engine.registry.listItems(alt, packageId)];
       }
     }
@@ -2176,7 +2186,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         if (packageId) whereClause._packageId = packageId;
         let rs = await this.engine.find("sys_metadata", { where: whereClause });
         if (!rs || rs.length === 0) {
-          const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+          const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
           if (alt) {
             const altWhere = { type: alt, state: "active", organization_id: oid };
             if (packageId) altWhere._packageId = packageId;
@@ -2269,7 +2279,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         };
         const rec = await this.engine.findOne("sys_metadata", { where });
         if (rec) return rec;
-        const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
         if (alt) {
           const altWhere = {
             type: alt,
@@ -2307,7 +2317,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           if (fromService !== void 0 && fromService !== null) {
             item = fromService;
           } else {
-            const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+            const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
             if (alt) {
               const altFromService = await metadataService.get(alt, request.name);
               if (altFromService !== void 0 && altFromService !== null) {
@@ -2322,7 +2332,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (item === void 0) {
       item = this.engine.registry.getItem(request.type, request.name);
       if (item === void 0) {
-        const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
         if (alt) item = this.engine.registry.getItem(alt, request.name);
       }
     }
@@ -2340,6 +2350,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 } : {},
@@ -2371,7 +2382,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       if (metadataService && typeof metadataService.get === "function") {
         let fromService = await metadataService.get(request.type, request.name);
         if (fromService === void 0 || fromService === null) {
-          const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+          const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
           if (alt) fromService = await metadataService.get(alt, request.name);
         }
         if (fromService !== void 0 && fromService !== null) code = fromService;
@@ -2381,7 +2392,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (code === null) {
       let regItem = this.engine.registry.getItem(request.type, request.name);
       if (regItem === void 0) {
-        const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
         if (alt) regItem = this.engine.registry.getItem(alt, request.name);
       }
       if (regItem !== void 0) code = regItem;
@@ -2398,7 +2409,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         };
         let rec = await this.engine.findOne("sys_metadata", { where });
         if (!rec) {
-          const alt = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? import_shared3.SINGULAR_TO_PLURAL[request.type];
+          const alt = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? import_shared4.SINGULAR_TO_PLURAL[request.type];
           if (alt) {
             rec = await this.engine.findOne("sys_metadata", {
               where: { ...where, type: alt }
@@ -2439,6 +2450,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 } : {},
@@ -2462,7 +2474,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * raising, keeping the Studio tab harmless.
    */
   async auditMetaItem(request) {
-    const singular = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singular = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     const limit = Math.min(
       Math.max(1, request.limit ?? 100),
       500
@@ -3371,14 +3383,14 @@ 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 = (0, import_types3.readEnvWithDeprecation)("OS_METADATA_WRITABLE", "OBJECTSTACK_METADATA_WRITABLE") || "";
     const set = /* @__PURE__ */ new Set();
     for (const tok of raw.split(",")) {
       const t = tok.trim();
       if (!t) continue;
-      const singular = import_shared3.PLURAL_TO_SINGULAR[t] ?? t;
+      const singular = import_shared4.PLURAL_TO_SINGULAR[t] ?? t;
       set.add(singular);
-      const plural = import_shared3.SINGULAR_TO_PLURAL[singular];
+      const plural = import_shared4.SINGULAR_TO_PLURAL[singular];
       if (plural) set.add(plural);
     }
     this._envWritableTypes = set;
@@ -3390,7 +3402,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
   }
   /** Normalize plural→singular before consulting the allow-list. */
   static isOverlayAllowed(type) {
-    const singular = import_shared3.PLURAL_TO_SINGULAR[type] ?? type;
+    const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
     if (this.OVERLAY_ALLOWED_TYPES.has(singular) || this.OVERLAY_ALLOWED_TYPES.has(type)) {
       return true;
     }
@@ -3399,7 +3411,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
   }
   /** Does this type permit creating brand-new (artifact-free) items? */
   static isRuntimeCreateAllowed(type) {
-    const singular = import_shared3.PLURAL_TO_SINGULAR[type] ?? type;
+    const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
     if (this.RUNTIME_CREATE_ALLOWED_TYPES.has(singular) || this.RUNTIME_CREATE_ALLOWED_TYPES.has(type)) {
       return true;
     }
@@ -3428,7 +3440,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (!registry || typeof registry.getItem !== "function") {
       return false;
     }
-    const singular = import_shared3.PLURAL_TO_SINGULAR[type] ?? type;
+    const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
     const item = registry.getItem(singular, name) ?? registry.getItem(type, name);
     if (!item || !item._packageId) return false;
     return item._packageId !== "sys_metadata";
@@ -3444,7 +3456,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
   lookupArtifactItem(type, name) {
     const registry = this.engine?.registry;
     if (!registry || typeof registry.getItem !== "function") return void 0;
-    const singular = import_shared3.PLURAL_TO_SINGULAR[type] ?? type;
+    const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
     return registry.getItem(singular, name) ?? registry.getItem(type, name);
   }
   /**
@@ -3460,7 +3472,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    */
   async getEffectiveLock(type, name, organizationId) {
     const registry = this.engine?.registry;
-    const singular = import_shared3.PLURAL_TO_SINGULAR[type] ?? type;
+    const singular = import_shared4.PLURAL_TO_SINGULAR[type] ?? type;
     let artifactItem;
     if (registry && typeof registry.getItem === "function") {
       artifactItem = registry.getItem(singular, name) ?? registry.getItem(type, name);
@@ -3504,7 +3516,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         occurred_at: (/* @__PURE__ */ new Date()).toISOString(),
         actor: entry.actor ?? "system",
         source: entry.source ?? "protocol",
-        type: import_shared3.PLURAL_TO_SINGULAR[entry.type] ?? entry.type,
+        type: import_shared4.PLURAL_TO_SINGULAR[entry.type] ?? entry.type,
         name: entry.name,
         organization_id: entry.organizationId ?? null,
         operation: entry.operation,
@@ -3617,7 +3629,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;
@@ -3641,7 +3653,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       });
       if (lockErr) throw lockErr;
     }
-    const singularType = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularType = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     if (!request.force && (singularType === "object" || singularType === "field")) {
       try {
         const existing = await this.getMetaItem({
@@ -3667,6 +3679,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) {
@@ -3689,7 +3713,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
     }
     await this.ensureOverlayIndex();
-    const singularTypeForRepo = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularTypeForRepo = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     const overlayAllowedForRepo = _ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo);
     const runtimeCreateAllowedForRepo = _ObjectStackProtocolImplementation.isRuntimeCreateAllowed(singularTypeForRepo);
     const useRepoPath = overlayAllowedForRepo || runtimeCreateAllowedForRepo;
@@ -3821,7 +3845,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * "no history" uniformly.
    */
   async historyMetaItem(request) {
-    const singularType = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularType = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     if (!_ObjectStackProtocolImplementation.isOverlayAllowed(singularType) && !_ObjectStackProtocolImplementation.isRuntimeCreateAllowed(singularType)) {
       return { events: [] };
     }
@@ -3845,7 +3869,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * when there is nothing to publish.
    */
   async publishMetaItem(request) {
-    const singularType = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularType = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     if (!_ObjectStackProtocolImplementation.isOverlayAllowed(singularType) && !_ObjectStackProtocolImplementation.isRuntimeCreateAllowed(singularType)) {
       const err = new Error(
         `[not_overridable] Metadata type '${request.type}' is not draftable \u2014 no overlay/runtime-create permission.`
@@ -3921,7 +3945,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       err.status = 400;
       throw err;
     }
-    const singularType = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularType = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     if (!_ObjectStackProtocolImplementation.isOverlayAllowed(singularType) && !_ObjectStackProtocolImplementation.isRuntimeCreateAllowed(singularType)) {
       const err = new Error(
         `[not_overridable] Metadata type '${request.type}' is not revertable \u2014 no overlay/runtime-create permission.`
@@ -3992,7 +4016,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * are reported as a single change record.
    */
   async diffMetaItem(request) {
-    const singularType = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularType = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     const orgId = request.organizationId ?? null;
     const events = (await this.historyMetaItem({
       type: singularType,
@@ -4094,7 +4118,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       });
       if (lockErr) throw lockErr;
     }
-    const singularTypeForRepo = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularTypeForRepo = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     const overlayAllowedForRepoDel = _ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo);
     const runtimeCreateAllowedForRepoDel = _ObjectStackProtocolImplementation.isRuntimeCreateAllowed(singularTypeForRepo);
     const useRepoPath = overlayAllowedForRepoDel || runtimeCreateAllowedForRepoDel;
@@ -4230,7 +4254,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       for (const record of records) {
         try {
           const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-          const normalizedType = import_shared3.PLURAL_TO_SINGULAR[record.type] ?? record.type;
+          const normalizedType = import_shared4.PLURAL_TO_SINGULAR[record.type] ?? record.type;
           if (normalizedType === "object") {
             this.engine.registry.registerObject(data, record.packageId || "sys_metadata");
           } else {
@@ -4264,7 +4288,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * — the engine never throws.
    */
   async findReferencesToMeta(request) {
-    const singularTarget = import_shared3.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularTarget = import_shared4.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     const targetName = request.name;
     const matchers = REFERENCE_PATHS[singularTarget];
     if (!matchers || matchers.length === 0) {
@@ -4458,13 +4482,13 @@ _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES = (() => {
   for (const entry of import_kernel4.DEFAULT_METADATA_TYPE_REGISTRY) {
     if (!entry.allowOrgOverride) continue;
     out.add(entry.type);
-    const plural = import_shared3.SINGULAR_TO_PLURAL[entry.type];
+    const plural = import_shared4.SINGULAR_TO_PLURAL[entry.type];
     if (plural) out.add(plural);
   }
   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
@@ -4495,7 +4519,7 @@ _ObjectStackProtocolImplementation.STATIC_REGISTRY_TYPES = (() => {
   const out = /* @__PURE__ */ new Set();
   for (const entry of import_kernel4.DEFAULT_METADATA_TYPE_REGISTRY) {
     out.add(entry.type);
-    const plural = import_shared3.SINGULAR_TO_PLURAL[entry.type];
+    const plural = import_shared4.SINGULAR_TO_PLURAL[entry.type];
     if (plural) out.add(plural);
   }
   return out;
@@ -4505,7 +4529,7 @@ _ObjectStackProtocolImplementation.RUNTIME_CREATE_ALLOWED_TYPES = (() => {
   for (const entry of import_kernel4.DEFAULT_METADATA_TYPE_REGISTRY) {
     if (!entry.allowRuntimeCreate) continue;
     out.add(entry.type);
-    const plural = import_shared3.SINGULAR_TO_PLURAL[entry.type];
+    const plural = import_shared4.SINGULAR_TO_PLURAL[entry.type];
     if (plural) out.add(plural);
   }
   return out;
@@ -4516,7 +4540,7 @@ var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
 var import_kernel6 = require("@objectstack/spec/kernel");
 var import_core = require("@objectstack/core");
 var import_system2 = require("@objectstack/spec/system");
-var import_shared4 = require("@objectstack/spec/shared");
+var import_shared5 = require("@objectstack/spec/shared");
 var import_formula2 = require("@objectstack/formula");
 
 // src/hook-wrappers.ts
@@ -5787,9 +5811,9 @@ var _ObjectQL = class _ObjectQL {
           const itemName = resolveMetadataItemName(key, item);
           if (itemName) {
             const toRegister = item.name === itemName ? item : { ...item, name: itemName };
-            this._registry.registerItem((0, import_shared4.pluralToSingular)(key), toRegister, "name", id);
+            this._registry.registerItem((0, import_shared5.pluralToSingular)(key), toRegister, "name", id);
           } else {
-            this.logger.warn(`Skipping ${(0, import_shared4.pluralToSingular)(key)} without a derivable name`, { id });
+            this.logger.warn(`Skipping ${(0, import_shared5.pluralToSingular)(key)} without a derivable name`, { id });
           }
         }
       }
@@ -5916,7 +5940,7 @@ var _ObjectQL = class _ObjectQL {
           const itemName = resolveMetadataItemName(key, item);
           if (itemName) {
             const toRegister = item.name === itemName ? item : { ...item, name: itemName };
-            this._registry.registerItem((0, import_shared4.pluralToSingular)(key), toRegister, "name", ownerId);
+            this._registry.registerItem((0, import_shared5.pluralToSingular)(key), toRegister, "name", ownerId);
           }
         }
       }