@objectstack/objectql 6.7.0 → 6.8.0

package/dist/index.js

@@ -672,9 +672,26 @@ var SchemaRegistry = class {
 // src/sys-metadata-repository.ts
 var import_metadata_core = require("@objectstack/metadata-core");
 var import_kernel2 = require("@objectstack/spec/kernel");
+var import_shared = require("@objectstack/spec/shared");
 var OVERLAY_ALLOWED_TYPES = new Set(
   import_kernel2.DEFAULT_METADATA_TYPE_REGISTRY.filter((e) => e.allowOrgOverride).map((e) => e.type)
 );
+var _envWritableMetadataTypes = null;
+function envWritableMetadataTypes() {
+  if (_envWritableMetadataTypes !== null) return _envWritableMetadataTypes;
+  const raw = typeof process !== "undefined" && process?.env?.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;
+    set.add(singular);
+    const plural = import_shared.SINGULAR_TO_PLURAL[singular];
+    if (plural) set.add(plural);
+  }
+  _envWritableMetadataTypes = set;
+  return set;
+}
 var SysMetadataRepository = class {
   constructor(opts) {
     /**
@@ -1067,14 +1084,21 @@ var SysMetadataRepository = class {
     if (this.closed) throw new Error("SysMetadataRepository is closed");
   }
   assertAllowed(type) {
-    if (!OVERLAY_ALLOWED_TYPES.has(type)) {
-      const err = new Error(
-        `[not_overridable] '${type}' is not allowOrgOverride in the registry. Allowed: ${Array.from(OVERLAY_ALLOWED_TYPES).join(", ")}.`
-      );
-      err.code = "not_overridable";
-      err.status = 403;
-      throw err;
-    }
+    const singular = import_shared.PLURAL_TO_SINGULAR[type] ?? type;
+    const allowedByRegistry = OVERLAY_ALLOWED_TYPES.has(singular) || OVERLAY_ALLOWED_TYPES.has(type);
+    if (allowedByRegistry) return;
+    const env = envWritableMetadataTypes();
+    if (env.has(singular) || env.has(type)) return;
+    const allowed = [
+      ...OVERLAY_ALLOWED_TYPES,
+      ...envWritableMetadataTypes()
+    ];
+    const err = new Error(
+      `[not_overridable] '${type}' is not allowOrgOverride in the registry. Allowed: ${Array.from(new Set(allowed)).join(", ") || "(none)"}. Set OBJECTSTACK_METADATA_WRITABLE to enable additional types at runtime.`
+    );
+    err.code = "not_overridable";
+    err.status = 403;
+    throw err;
   }
   whereFor(ref) {
     return {
@@ -1178,12 +1202,170 @@ var SysMetadataRepository = class {
 // src/protocol.ts
 var import_metadata_core2 = require("@objectstack/metadata-core");
 var import_data2 = require("@objectstack/spec/data");
-var import_shared = require("@objectstack/spec/shared");
+var import_shared2 = require("@objectstack/spec/shared");
 var import_ui2 = require("@objectstack/spec/ui");
+var import_identity = require("@objectstack/spec/identity");
+var import_security = require("@objectstack/spec/security");
+var import_system = require("@objectstack/spec/system");
+var import_ai = require("@objectstack/spec/ai");
+var import_automation = require("@objectstack/spec/automation");
 var import_kernel3 = require("@objectstack/spec/kernel");
+var import_zod = require("zod");
+var TYPE_TO_SCHEMA = {
+  object: import_data2.ObjectSchema,
+  field: import_data2.FieldSchema,
+  dashboard: import_ui2.DashboardSchema,
+  app: import_ui2.AppSchema,
+  page: import_ui2.PageSchema,
+  report: import_ui2.ReportSchema,
+  action: import_ui2.ActionSchema,
+  role: import_identity.RoleSchema,
+  permission: import_security.PermissionSetSchema,
+  profile: import_security.PermissionSetSchema,
+  email_template: import_system.EmailTemplateSchema,
+  tool: import_ai.ToolSchema,
+  skill: import_ai.SkillSchema,
+  agent: import_ai.AgentSchema,
+  flow: import_automation.FlowSchema,
+  workflow: import_automation.WorkflowRuleSchema,
+  approval: import_automation.ApprovalProcessSchema,
+  hook: import_data2.HookSchema
+};
+var TYPE_TO_FORM = {
+  object: import_data2.objectForm,
+  field: import_data2.fieldForm,
+  hook: import_data2.hookForm,
+  report: import_ui2.reportForm,
+  view: import_ui2.viewForm,
+  app: import_ui2.appForm,
+  dashboard: import_ui2.dashboardForm,
+  role: import_identity.roleForm,
+  action: import_ui2.actionForm,
+  page: import_ui2.pageForm,
+  agent: import_ai.agentForm,
+  tool: import_ai.toolForm,
+  skill: import_ai.skillForm,
+  flow: import_automation.flowForm,
+  workflow: import_automation.workflowForm,
+  approval: import_automation.approvalForm,
+  permission: import_security.permissionForm,
+  profile: import_security.permissionForm,
+  email_template: import_system.emailTemplateForm
+};
+var _jsonSchemaCache = /* @__PURE__ */ new WeakMap();
+function toJsonSchemaSafe(schema) {
+  const cached = _jsonSchemaCache.get(schema);
+  if (cached !== void 0) return cached ?? void 0;
+  try {
+    const result = import_zod.z.toJSONSchema(schema, { unrepresentable: "any" });
+    _jsonSchemaCache.set(schema, result);
+    return result;
+  } catch {
+    _jsonSchemaCache.set(schema, null);
+    return void 0;
+  }
+}
+var HAND_CRAFTED_SCHEMAS = {
+  object: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      label: { type: "string" },
+      pluralLabel: { type: "string" },
+      icon: { type: "string" },
+      description: { type: "string" },
+      tags: { type: "array", items: { type: "string" } },
+      active: { type: "boolean", default: true },
+      isSystem: { type: "boolean", default: false },
+      abstract: { type: "boolean", default: false },
+      datasource: { type: "string" },
+      fields: {
+        type: "array",
+        default: [],
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            label: { type: "string" },
+            type: { type: "string" },
+            required: { type: "boolean", default: false },
+            unique: { type: "boolean", default: false },
+            defaultValue: {},
+            description: { type: "string" }
+          },
+          required: ["name", "type"]
+        }
+      },
+      capabilities: { type: "object", additionalProperties: true }
+    },
+    required: ["name"],
+    additionalProperties: true
+  },
+  action: {
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      label: { type: "string" },
+      objectName: { type: "string" },
+      icon: { type: "string" },
+      type: { type: "string", enum: ["url", "flow", "api", "script"] },
+      variant: { type: "string", enum: ["primary", "secondary", "danger", "ghost", "outline"] },
+      target: { type: "string" },
+      method: { type: "string", enum: ["GET", "POST", "PUT", "PATCH", "DELETE"] },
+      body: {
+        type: "array",
+        default: [],
+        items: {
+          type: "object",
+          properties: {
+            line: { type: "string" }
+          }
+        }
+      },
+      params: {
+        type: "array",
+        default: [],
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            label: { type: "string" },
+            type: { type: "string" },
+            required: { type: "boolean", default: false }
+          },
+          required: ["name"]
+        }
+      },
+      confirmText: { type: "string" },
+      successMessage: { type: "string" },
+      refreshAfter: { type: "boolean", default: true },
+      locations: {
+        type: "array",
+        default: [],
+        items: {
+          type: "object",
+          properties: {
+            location: { type: "string" }
+          }
+        }
+      },
+      component: { type: "string" },
+      visible: { type: "string" },
+      disabled: { type: "string" },
+      shortcut: { type: "string" },
+      bulkEnabled: { type: "boolean", default: false },
+      aiExposed: { type: "boolean", default: false },
+      recordIdParam: { type: "string" },
+      recordIdField: { type: "string" },
+      bodyShape: { type: "string", enum: ["flat", "nested"] }
+    },
+    required: ["name", "label", "type"],
+    additionalProperties: true
+  }
+};
 var FORM_VIEW_TYPES = /* @__PURE__ */ new Set(["simple", "tabbed", "wizard", "split", "drawer", "modal"]);
 function resolveOverlaySchema(type, item) {
-  const singular = import_shared.PLURAL_TO_SINGULAR[type] ?? type;
+  const singular = import_shared2.PLURAL_TO_SINGULAR[type] ?? type;
   switch (singular) {
     case "view": {
       const t = item && typeof item === "object" && "type" in item ? String(item.type) : void 0;
@@ -1240,6 +1422,140 @@ var SERVICE_CONFIG = {
   "file-storage": { route: "/api/v1/storage", plugin: "plugin-storage" },
   search: { route: "/api/v1/search", plugin: "plugin-search" }
 };
+var REFERENCE_PATHS = {
+  object: [
+    { fromType: "view", paths: ["object", "objectName"], kind: "view" },
+    { fromType: "dashboard", paths: ["widgets[].object", "widgets[].objectName"], kind: "dashboard widget" },
+    { fromType: "flow", paths: ["object", "context.object", "trigger.object", "targetObject"], kind: "flow" },
+    { fromType: "workflow", paths: ["object", "targetObject"], kind: "workflow" },
+    { fromType: "permission", paths: ["objects[].name", "objects[].object"], kind: "permission" },
+    { fromType: "app", paths: ["navItems[].objectName", "navItems[].object", "tabs[].objectName", "tabs[].object"], kind: "app nav" },
+    { fromType: "page", paths: ["object", "objectName"], kind: "page" },
+    { fromType: "report", paths: ["object", "objectName"], kind: "report" },
+    { fromType: "action", paths: ["object", "objectName"], kind: "action" },
+    { fromType: "validation", paths: ["object", "objectName"], kind: "validation" },
+    { fromType: "hook", paths: ["object", "objectName"], kind: "hook" },
+    { fromType: "object", paths: ["fields[].referenceTo", "fields{}.referenceTo", "fields{}.reference"], kind: "field reference" }
+  ],
+  view: [
+    { fromType: "dashboard", paths: ["widgets[].view", "widgets[].viewName"], kind: "dashboard widget" },
+    { fromType: "app", paths: ["navItems[].viewName", "tabs[].viewName"], kind: "app nav" },
+    { fromType: "page", paths: ["viewName"], kind: "page" }
+  ],
+  tool: [
+    { fromType: "agent", paths: ["tools[]", "tools[].name"], kind: "agent tool" }
+  ],
+  skill: [
+    { fromType: "agent", paths: ["skills[]", "skills[].name"], kind: "agent skill" }
+  ],
+  flow: [
+    { fromType: "app", paths: ["navItems[].flowName", "tabs[].flowName"], kind: "app nav" }
+  ],
+  dashboard: [
+    { fromType: "app", paths: ["navItems[].dashboardName", "tabs[].dashboardName"], kind: "app nav" }
+  ],
+  page: [
+    { fromType: "app", paths: ["navItems[].pageName", "tabs[].pageName"], kind: "app nav" }
+  ]
+};
+function extractPathValues(item, path) {
+  if (!item || typeof item !== "object") return [];
+  const segments = path.split(".");
+  let current = [item];
+  for (const rawSeg of segments) {
+    let kind = "value";
+    let seg = rawSeg;
+    if (seg.endsWith("[]")) {
+      kind = "array";
+      seg = seg.slice(0, -2);
+    } else if (seg.endsWith("{}")) {
+      kind = "record";
+      seg = seg.slice(0, -2);
+    }
+    const next = [];
+    for (const node of current) {
+      if (!node || typeof node !== "object") continue;
+      let value;
+      if (seg === "") {
+        value = node;
+      } else {
+        value = node[seg];
+      }
+      if (value === void 0 || value === null) continue;
+      if (kind === "array") {
+        if (Array.isArray(value)) {
+          for (const v of value) next.push(v);
+        }
+      } else if (kind === "record") {
+        if (Array.isArray(value)) {
+          for (const v of value) next.push(v);
+        } else if (typeof value === "object") {
+          for (const v of Object.values(value)) next.push(v);
+        }
+      } else {
+        next.push(value);
+      }
+    }
+    current = next;
+    if (current.length === 0) return [];
+  }
+  const out = [];
+  for (const v of current) {
+    if (typeof v === "string" && v.length > 0) out.push(v);
+    else if (v && typeof v === "object" && "name" in v && typeof v.name === "string") {
+      out.push(v.name);
+    }
+  }
+  return out;
+}
+function detectDestructiveObjectChanges(prev, next) {
+  if (!prev || typeof prev !== "object" || !next || typeof next !== "object") return [];
+  const prevFields = prev.fields && typeof prev.fields === "object" ? prev.fields : {};
+  const nextFields = next.fields && typeof next.fields === "object" ? next.fields : {};
+  const issues = [];
+  for (const fname of Object.keys(prevFields)) {
+    if (prevFields[fname]?.system) continue;
+    if (!(fname in nextFields)) {
+      issues.push({
+        code: "field_removed",
+        field: fname,
+        message: `Field '${fname}' removed \u2014 existing data in this column will become inaccessible.`
+      });
+    }
+  }
+  const TYPE_COMPATIBILITY = {
+    text: /* @__PURE__ */ new Set(["textarea", "markdown", "html", "code"]),
+    number: /* @__PURE__ */ new Set([]),
+    boolean: /* @__PURE__ */ new Set([]),
+    date: /* @__PURE__ */ new Set(["datetime"]),
+    datetime: /* @__PURE__ */ new Set(["date"])
+  };
+  for (const fname of Object.keys(nextFields)) {
+    const prevField = prevFields[fname];
+    const nextField = nextFields[fname];
+    if (!prevField) continue;
+    const prevType = prevField.type;
+    const nextType = nextField.type;
+    if (prevType && nextType && prevType !== nextType) {
+      const compatible = TYPE_COMPATIBILITY[prevType]?.has(nextType);
+      if (!compatible) {
+        issues.push({
+          code: "field_type_change",
+          field: fname,
+          message: `Field '${fname}' type changed from '${prevType}' to '${nextType}' \u2014 existing values may not convert cleanly.`
+        });
+      }
+    }
+    if (!prevField.required && nextField.required && nextField.defaultValue === void 0) {
+      issues.push({
+        code: "field_required_no_default",
+        field: fname,
+        message: `Field '${fname}' is now required but has no default value \u2014 existing rows with null values may fail validation.`
+      });
+    }
+  }
+  return issues;
+}
 var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementation {
   constructor(engine, getServicesRegistry, getFeedService, environmentId) {
     /**
@@ -1441,7 +1757,52 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     } catch {
     }
     const allTypes = Array.from(/* @__PURE__ */ new Set([...schemaTypes, ...runtimeTypes]));
-    return { types: allTypes };
+    const writableOverrides = _ObjectStackProtocolImplementation.envWritableTypes();
+    const registryByType = new Map(
+      import_kernel3.DEFAULT_METADATA_TYPE_REGISTRY.map((e) => [e.type, e])
+    );
+    const entries = allTypes.map((type) => {
+      const singular = import_shared2.PLURAL_TO_SINGULAR[type] ?? type;
+      const zodSchema = singular === "view" ? import_ui2.ListViewSchema : TYPE_TO_SCHEMA[singular];
+      const schema = (zodSchema ? toJsonSchemaSafe(zodSchema) : void 0) ?? HAND_CRAFTED_SCHEMAS[singular];
+      const form = TYPE_TO_FORM[singular];
+      const base = registryByType.get(singular);
+      if (base) {
+        const isEnvOverridden = writableOverrides.has(singular);
+        return {
+          ...base,
+          type: singular,
+          schemaId: singular,
+          // API client expects schemaId field
+          allowOrgOverride: base.allowOrgOverride || isEnvOverridden,
+          overrideSource: isEnvOverridden && !base.allowOrgOverride ? "env" : "registry",
+          schema,
+          form
+        };
+      }
+      return {
+        type: singular,
+        schemaId: singular,
+        // API client expects schemaId field
+        label: singular,
+        description: void 0,
+        filePatterns: [],
+        supportsOverlay: false,
+        allowOrgOverride: writableOverrides.has(singular),
+        allowRuntimeCreate: true,
+        supportsVersioning: false,
+        executionPinned: false,
+        loadOrder: 1e3,
+        domain: "system",
+        overrideSource: writableOverrides.has(singular) ? "env" : "registry",
+        schema,
+        form
+      };
+    }).sort((a, b) => {
+      if (a.domain !== b.domain) return a.domain.localeCompare(b.domain);
+      return a.type.localeCompare(b.type);
+    });
+    return { types: allTypes, entries };
   }
   async getMetaItems(request) {
     const { packageId } = request;
@@ -1449,13 +1810,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_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.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_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.SINGULAR_TO_PLURAL[request.type];
         if (alt) items = [...this.engine.registry.listItems(alt, packageId)];
       }
     }
@@ -1470,7 +1831,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_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
+          const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.SINGULAR_TO_PLURAL[request.type];
           if (alt) {
             const altWhere = { type: alt, state: "active", organization_id: oid };
             if (packageId) altWhere._packageId = packageId;
@@ -1553,7 +1914,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         };
         const rec = await this.engine.findOne("sys_metadata", { where });
         if (rec) return rec;
-        const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.SINGULAR_TO_PLURAL[request.type];
         if (alt) {
           const altWhere = {
             type: alt,
@@ -1580,7 +1941,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           if (fromService !== void 0 && fromService !== null) {
             item = fromService;
           } else {
-            const alt = import_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
+            const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.SINGULAR_TO_PLURAL[request.type];
             if (alt) {
               const altFromService = await metadataService.get(alt, request.name);
               if (altFromService !== void 0 && altFromService !== null) {
@@ -1595,7 +1956,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_shared.PLURAL_TO_SINGULAR[request.type] ?? import_shared.SINGULAR_TO_PLURAL[request.type];
+        const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.SINGULAR_TO_PLURAL[request.type];
         if (alt) item = this.engine.registry.getItem(alt, request.name);
       }
     }
@@ -1605,6 +1966,91 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       item
     };
   }
+  /**
+   * Phase 3a-layered-get: return the 3 layers of a metadata item
+   * separately — `code` (artifact-loaded baseline), `overlay` (per-org
+   * customisation row, if any), and `effective` (what `getMetaItem`
+   * would return, i.e. overlay-wins merge).
+   *
+   * Drives the "Code default vs Overlay vs Effective" diff tab in the
+   * generic Metadata Resource Edit page. Admins can see exactly what
+   * was customised and reset selectively.
+   *
+   * `code` is null if no artifact baseline exists; `overlay` is null if
+   * no sys_metadata row exists for the requested scope; `effective` is
+   * never null when either layer exists.
+   */
+  async getMetaItemLayered(request) {
+    const orgId = request.organizationId;
+    let code = null;
+    try {
+      const services = this.getServicesRegistry?.();
+      const metadataService = services?.get("metadata");
+      if (metadataService && typeof metadataService.get === "function") {
+        let fromService = await metadataService.get(request.type, request.name);
+        if (fromService === void 0 || fromService === null) {
+          const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.SINGULAR_TO_PLURAL[request.type];
+          if (alt) fromService = await metadataService.get(alt, request.name);
+        }
+        if (fromService !== void 0 && fromService !== null) code = fromService;
+      }
+    } catch {
+    }
+    if (code === null) {
+      let regItem = this.engine.registry.getItem(request.type, request.name);
+      if (regItem === void 0) {
+        const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.SINGULAR_TO_PLURAL[request.type];
+        if (alt) regItem = this.engine.registry.getItem(alt, request.name);
+      }
+      if (regItem !== void 0) code = regItem;
+    }
+    let overlay = null;
+    let overlayScope = null;
+    try {
+      const findOverlay = async (oid) => {
+        const where = {
+          type: request.type,
+          name: request.name,
+          state: "active",
+          organization_id: oid
+        };
+        let rec = await this.engine.findOne("sys_metadata", { where });
+        if (!rec) {
+          const alt = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? import_shared2.SINGULAR_TO_PLURAL[request.type];
+          if (alt) {
+            rec = await this.engine.findOne("sys_metadata", {
+              where: { ...where, type: alt }
+            });
+          }
+        }
+        return rec;
+      };
+      if (orgId) {
+        const rec = await findOverlay(orgId);
+        if (rec) {
+          overlay = typeof rec.metadata === "string" ? JSON.parse(rec.metadata) : rec.metadata;
+          overlayScope = "org";
+        }
+      }
+      if (overlay === null) {
+        const rec = await findOverlay(null);
+        if (rec) {
+          overlay = typeof rec.metadata === "string" ? JSON.parse(rec.metadata) : rec.metadata;
+          overlayScope = "env";
+        }
+      }
+    } catch {
+    }
+    const effective = overlay ?? code;
+    return {
+      type: request.type,
+      name: request.name,
+      code,
+      overlay,
+      overlayScope,
+      effective
+    };
+  }
   async getUiView(request) {
     const schema = this.engine.registry.getObject(request.object);
     if (!schema) throw new Error(`Object ${request.object} not found`);
@@ -2476,10 +2922,33 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       ...request.options
     });
   }
+  static envWritableTypes() {
+    if (this._envWritableTypes !== null) return this._envWritableTypes;
+    const raw = typeof process !== "undefined" && process?.env?.OBJECTSTACK_METADATA_WRITABLE || "";
+    const set = /* @__PURE__ */ new Set();
+    for (const tok of raw.split(",")) {
+      const t = tok.trim();
+      if (!t) continue;
+      const singular = import_shared2.PLURAL_TO_SINGULAR[t] ?? t;
+      set.add(singular);
+      const plural = import_shared2.SINGULAR_TO_PLURAL[singular];
+      if (plural) set.add(plural);
+    }
+    this._envWritableTypes = set;
+    return set;
+  }
+  /** Test hook — clear the memoised env-writable cache. */
+  static resetEnvWritableCache() {
+    this._envWritableTypes = null;
+  }
   /** Normalize plural→singular before consulting the allow-list. */
   static isOverlayAllowed(type) {
-    const singular = import_shared.PLURAL_TO_SINGULAR[type] ?? type;
-    return _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES.has(singular) || _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES.has(type);
+    const singular = import_shared2.PLURAL_TO_SINGULAR[type] ?? type;
+    if (this.OVERLAY_ALLOWED_TYPES.has(singular) || this.OVERLAY_ALLOWED_TYPES.has(type)) {
+      return true;
+    }
+    const env = this.envWritableTypes();
+    return env.has(singular) || env.has(type);
   }
   /**
    * Mirror an object-type overlay write into the in-memory engine
@@ -2509,12 +2978,38 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (this.environmentId !== void 0 && !_ObjectStackProtocolImplementation.isOverlayAllowed(request.type)) {
       const allowed = Array.from(_ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES).join(", ");
       const err = new Error(
-        `[not_overridable] Metadata type '${request.type}' has not opted into per-org overlay writes. Set allowOrgOverride: true on its DEFAULT_METADATA_TYPE_REGISTRY entry to enable. Currently allowed: ${allowed}. See docs/adr/0005-metadata-customization-overlay.md.`
+        `[not_overridable] Metadata type '${request.type}' has not opted into per-org overlay writes. Set allowOrgOverride: true on its DEFAULT_METADATA_TYPE_REGISTRY entry to enable, or set the OBJECTSTACK_METADATA_WRITABLE env var (comma-separated singular type names) to opt in at runtime. Currently allowed: ${allowed}. See docs/adr/0005-metadata-customization-overlay.md.`
       );
       err.code = "not_overridable";
       err.status = 403;
       throw err;
     }
+    const singularType = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    if (!request.force && (singularType === "object" || singularType === "field")) {
+      try {
+        const existing = await this.getMetaItem({
+          type: request.type,
+          name: request.name,
+          ...request.organizationId ? { organizationId: request.organizationId } : {}
+        });
+        const prev = existing?.item;
+        if (prev) {
+          const issues = detectDestructiveObjectChanges(prev, request.item);
+          if (issues.length > 0) {
+            const summary = issues.slice(0, 3).map((i) => i.message).join("; ");
+            const err = new Error(
+              `[destructive_change] ${request.type}/${request.name} would drop or transform existing data: ${summary}` + (issues.length > 3 ? ` (+${issues.length - 3} more)` : "") + ` \u2014 re-submit with ?force=true to proceed.`
+            );
+            err.code = "destructive_change";
+            err.status = 409;
+            err.issues = issues;
+            throw err;
+          }
+        }
+      } catch (err) {
+        if (err?.code === "destructive_change") throw err;
+      }
+    }
     {
       const schema = resolveOverlaySchema(request.type, request.item);
       if (schema) {
@@ -2537,7 +3032,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
     }
     await this.ensureOverlayIndex();
-    const singularTypeForRepo = import_shared.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularTypeForRepo = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     if (_ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo)) {
       const orgId = request.organizationId ?? null;
       const repo = this.getOverlayRepo(orgId);
@@ -2648,7 +3143,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * "no history" uniformly.
    */
   async historyMetaItem(request) {
-    const singularType = import_shared.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularType = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     if (!_ObjectStackProtocolImplementation.isOverlayAllowed(singularType)) {
       return { events: [] };
     }
@@ -2681,7 +3176,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       err.status = 403;
       throw err;
     }
-    const singularTypeForRepo = import_shared.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const singularTypeForRepo = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? request.type;
     const useRepoPath = _ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo);
     if (useRepoPath) {
       const orgId = request.organizationId ?? null;
@@ -2801,7 +3296,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_shared.PLURAL_TO_SINGULAR[record.type] ?? record.type;
+          const normalizedType = import_shared2.PLURAL_TO_SINGULAR[record.type] ?? record.type;
           if (normalizedType === "object") {
             this.engine.registry.registerObject(data, record.packageId || "sys_metadata");
           } else {
@@ -2821,6 +3316,68 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     return { loaded, errors };
   }
   // ==========================================
+  // Metadata References (Phase 3a-references)
+  // ==========================================
+  /**
+   * Scan all loaded metadata for references pointing at the given
+   * `{type, name}` target. Returns one row per referring artifact with
+   * the path that produced the hit, so the admin UI can render an
+   * "Used by" panel before destructive actions (rename / delete /
+   * type-narrowing).
+   *
+   * Coverage is driven by the hand-curated {@link REFERENCE_PATHS}
+   * registry. Types not present in the registry simply return no hits
+   * — the engine never throws.
+   */
+  async findReferencesToMeta(request) {
+    const singularTarget = import_shared2.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const targetName = request.name;
+    const matchers = REFERENCE_PATHS[singularTarget];
+    if (!matchers || matchers.length === 0) {
+      return { references: [] };
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    await Promise.all(
+      matchers.map(async (matcher) => {
+        let items = [];
+        try {
+          const result = await this.getMetaItems({
+            type: matcher.fromType,
+            ...request.organizationId ? { organizationId: request.organizationId } : {}
+          });
+          items = result?.items ?? [];
+        } catch {
+          return;
+        }
+        for (const raw of items) {
+          if (!raw || typeof raw !== "object") continue;
+          const sourceName = raw.name;
+          if (!sourceName) continue;
+          const isSelfReference = matcher.fromType === singularTarget && sourceName === targetName;
+          for (const path of matcher.paths) {
+            const values = extractPathValues(raw, path);
+            if (!values.includes(targetName)) continue;
+            if (isSelfReference && !path.includes("[]") && !path.includes("{}")) continue;
+            const key = `${matcher.fromType}|${sourceName}|${path}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            const label = raw.label;
+            out.push({
+              type: matcher.fromType,
+              name: sourceName,
+              ...label ? { label } : {},
+              path,
+              kind: matcher.kind
+            });
+          }
+        }
+      })
+    );
+    out.sort((a, b) => a.type.localeCompare(b.type) || a.name.localeCompare(b.name));
+    return { references: out };
+  }
+  // ==========================================
   // Feed Operations
   // ==========================================
   async listFeed(request) {
@@ -2967,18 +3524,30 @@ _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES = (() => {
   for (const entry of import_kernel3.DEFAULT_METADATA_TYPE_REGISTRY) {
     if (!entry.allowOrgOverride) continue;
     out.add(entry.type);
-    const plural = import_shared.SINGULAR_TO_PLURAL[entry.type];
+    const plural = import_shared2.SINGULAR_TO_PLURAL[entry.type];
     if (plural) out.add(plural);
   }
   return out;
 })();
+/**
+ * Phase 3a-env-writable: parse `OBJECTSTACK_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
+ * use to enable Studio-side editing of types whose protocol-level flag
+ * is still false (object, field, permission, …).
+ *
+ * Memoised at first call. Tests can override by clearing the cache via
+ * {@link ObjectStackProtocolImplementation.resetEnvWritableCache}.
+ */
+_ObjectStackProtocolImplementation._envWritableTypes = null;
 var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
 
 // src/engine.ts
 var import_kernel4 = require("@objectstack/spec/kernel");
 var import_core = require("@objectstack/core");
-var import_system = require("@objectstack/spec/system");
-var import_shared2 = require("@objectstack/spec/shared");
+var import_system2 = require("@objectstack/spec/system");
+var import_shared3 = require("@objectstack/spec/shared");
 var import_formula2 = require("@objectstack/formula");
 
 // src/hook-wrappers.ts
@@ -3780,7 +4349,7 @@ var _ObjectQL = class _ObjectQL {
    */
   getStatus() {
     return {
-      name: import_system.CoreServiceName.enum.data,
+      name: import_system2.CoreServiceName.enum.data,
       status: "running",
       version: "0.9.0",
       features: ["crud", "query", "aggregate", "transactions", "metadata"]
@@ -4248,9 +4817,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_shared2.pluralToSingular)(key), toRegister, "name", id);
+            this._registry.registerItem((0, import_shared3.pluralToSingular)(key), toRegister, "name", id);
           } else {
-            this.logger.warn(`Skipping ${(0, import_shared2.pluralToSingular)(key)} without a derivable name`, { id });
+            this.logger.warn(`Skipping ${(0, import_shared3.pluralToSingular)(key)} without a derivable name`, { id });
           }
         }
       }
@@ -4377,7 +4946,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_shared2.pluralToSingular)(key), toRegister, "name", ownerId);
+            this._registry.registerItem((0, import_shared3.pluralToSingular)(key), toRegister, "name", ownerId);
           }
         }
       }
@@ -4427,9 +4996,9 @@ var _ObjectQL = class _ObjectQL {
   resolveObjectName(name) {
     const schema = this._registry.getObject(name);
     if (schema) {
-      return import_system.StorageNameMapping.resolveTableName(schema);
+      return import_system2.StorageNameMapping.resolveTableName(schema);
     }
-    return import_system.StorageNameMapping.resolveTableName({ name });
+    return import_system2.StorageNameMapping.resolveTableName({ name });
   }
   /**
    * Helper to get the target driver
@@ -5199,7 +5768,7 @@ var _ObjectQL = class _ObjectQL {
     for (const obj of allObjects) {
       const driver = this.getDriverForObject(obj.name);
       if (!driver) continue;
-      const tableName = import_system.StorageNameMapping.resolveTableName(obj);
+      const tableName = import_system2.StorageNameMapping.resolveTableName(obj);
       if (typeof driver.syncSchemasBatch === "function" && driver.supports?.batchSchemaSync) {
       }
       if (typeof driver.syncSchema === "function") {
@@ -5535,7 +6104,7 @@ var MetadataFacade = class {
 };
 
 // src/plugin.ts
-var import_system2 = require("@objectstack/spec/system");
+var import_system3 = require("@objectstack/spec/system");
 function hasLoadMetaFromDb(service) {
   return typeof service === "object" && service !== null && typeof service["loadMetaFromDb"] === "function";
 }
@@ -5925,7 +6494,7 @@ var ObjectQLPlugin = class {
         skipped++;
         continue;
       }
-      const tableName = import_system2.StorageNameMapping.resolveTableName(obj);
+      const tableName = import_system3.StorageNameMapping.resolveTableName(obj);
       let group = driverGroups.get(driver);
       if (!group) {
         group = [];