@objectstack/objectql 7.0.0 → 7.2.0

package/dist/index.mjs

@@ -390,6 +390,14 @@ var SchemaRegistry = class {
     if (collection.has(storageKey)) {
       this.log(`[Registry] Overwriting ${type}: ${storageKey}`);
     }
+    if (packageId && collection.has(baseName)) {
+      const dbOnly = collection.get(baseName);
+      if (dbOnly && !dbOnly._packageId) {
+        console.warn(
+          `[Registry] Collision: ${type}/${baseName} ships from package "${packageId}" but a runtime-authored row with the same name already exists in sys_metadata. The runtime row will shadow the package value (ADR-0005 overlay precedence). Rename one, or delete the sys_metadata row if the package value should win.`
+        );
+      }
+    }
     collection.set(storageKey, item);
     this.log(`[Registry] Registered ${type}: ${storageKey}`);
   }
@@ -446,7 +454,9 @@ var SchemaRegistry = class {
     const direct = collection.get(name);
     if (direct) return direct;
     for (const [key, item] of collection) {
-      if (key.endsWith(`:${name}`)) return item;
+      if (key.endsWith(`:${name}`)) {
+        return item;
+      }
     }
     return void 0;
   }
@@ -626,6 +636,12 @@ import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from "@objectstack/spec/shared
 var OVERLAY_ALLOWED_TYPES = new Set(
   DEFAULT_METADATA_TYPE_REGISTRY.filter((e) => e.allowOrgOverride).map((e) => e.type)
 );
+var STATIC_REGISTRY_TYPES = new Set(
+  DEFAULT_METADATA_TYPE_REGISTRY.map((e) => e.type)
+);
+var RUNTIME_CREATE_ALLOWED_TYPES = new Set(
+  DEFAULT_METADATA_TYPE_REGISTRY.filter((e) => e.allowRuntimeCreate).map((e) => e.type)
+);
 var _envWritableMetadataTypes = null;
 function envWritableMetadataTypes() {
   if (_envWritableMetadataTypes !== null) return _envWritableMetadataTypes;
@@ -675,11 +691,16 @@ var SysMetadataRepository = class {
   /**
    * Read the current overlay row. Returns null if no row exists —
    * callers (e.g. LayeredRepository) fall through to lower layers.
+   *
+   * `opts.state` selects which lifecycle row to read: defaults to the
+   * live published row (`'active'`). Pass `'draft'` to read the pending
+   * unpublished revision (if any).
    */
-  async get(ref) {
+  async get(ref, opts) {
     this.assertOpen();
+    const state = opts?.state ?? "active";
     const row = await this.engine.findOne("sys_metadata", {
-      where: this.whereFor(ref)
+      where: this.whereFor(ref, state)
     });
     if (!row) return null;
     return this.rowToItem(ref, row);
@@ -722,12 +743,13 @@ var SysMetadataRepository = class {
   }
   async put(ref, spec, opts) {
     this.assertOpen();
-    this.assertAllowed(ref.type);
+    this.assertAllowed(ref.type, opts.intent);
+    const state = opts.state ?? "active";
     const body = spec ?? {};
     const hash = hashSpec(body);
     const result = await this.withTxn(async (ctx) => {
       const existing = await this.engine.findOne("sys_metadata", {
-        where: this.whereFor(ref),
+        where: this.whereFor(ref, state),
         context: ctx
       });
       const existingHash = existing?.checksum ?? null;
@@ -739,7 +761,8 @@ var SysMetadataRepository = class {
         return { skipped: true, version: hash, seq: item2.seq, item: item2 };
       }
       const now = (/* @__PURE__ */ new Date()).toISOString();
-      const op = existing ? "update" : "create";
+      const baseOp = existing ? "update" : "create";
+      const op = opts.opType ?? baseOp;
       const version = await this.nextItemVersion(ref, ctx);
       const eventSeq = await this.nextEventSeq(ctx);
       const parentRowData = {
@@ -748,7 +771,7 @@ var SysMetadataRepository = class {
         organization_id: this.organizationId,
         metadata: JSON.stringify(body),
         checksum: hash,
-        state: "active",
+        state,
         version,
         updated_at: now
       };
@@ -814,25 +837,28 @@ var SysMetadataRepository = class {
       return { version: result.version, seq: result.seq, item: result.item };
     }
     this.seqCounter = result.seq;
-    this.broadcast({
-      seq: result.seq,
-      op: result.op,
-      ref: this.fullRef(ref),
-      hash: result.version,
-      parentHash: result.existingHash,
-      actor: result.actor,
-      message: result.message,
-      ts: result.now,
-      source: result.source
-    });
+    if (state === "active") {
+      this.broadcast({
+        seq: result.seq,
+        op: result.op,
+        ref: this.fullRef(ref),
+        hash: result.version,
+        parentHash: result.existingHash,
+        actor: result.actor,
+        message: result.message,
+        ts: result.now,
+        source: result.source
+      });
+    }
     return { version: result.version, seq: result.seq, item: result.item };
   }
   async delete(ref, opts) {
     this.assertOpen();
-    this.assertAllowed(ref.type);
+    this.assertAllowed(ref.type, opts.intent);
+    const state = opts.state ?? "active";
     const result = await this.withTxn(async (ctx) => {
       const existing = await this.engine.findOne("sys_metadata", {
-        where: this.whereFor(ref),
+        where: this.whereFor(ref, state),
         context: ctx
       });
       if (!existing) {
@@ -849,32 +875,38 @@ var SysMetadataRepository = class {
         );
       }
       const now = (/* @__PURE__ */ new Date()).toISOString();
-      const version = await this.nextItemVersion(ref, ctx);
-      const eventSeq = await this.nextEventSeq(ctx);
+      let version = 0;
+      let eventSeq = 0;
+      if (state === "active") {
+        version = await this.nextItemVersion(ref, ctx);
+        eventSeq = await this.nextEventSeq(ctx);
+      }
       await this.engine.delete("sys_metadata", {
         where: { id: existingId },
         context: ctx
       });
-      await this.engine.insert(
-        this.historyTable,
-        {
-          id: this.uuid(),
-          event_seq: eventSeq,
-          type: ref.type,
-          name: ref.name,
-          version,
-          operation_type: "delete",
-          metadata: null,
-          checksum: null,
-          previous_checksum: existingHash,
-          change_note: opts.message,
-          source: opts.source ?? "sys-metadata-repo",
-          organization_id: this.organizationId,
-          recorded_by: opts.actor,
-          recorded_at: now
-        },
-        { context: ctx }
-      );
+      if (state === "active") {
+        await this.engine.insert(
+          this.historyTable,
+          {
+            id: this.uuid(),
+            event_seq: eventSeq,
+            type: ref.type,
+            name: ref.name,
+            version,
+            operation_type: "delete",
+            metadata: null,
+            checksum: null,
+            previous_checksum: existingHash,
+            change_note: opts.message,
+            source: opts.source ?? "sys-metadata-repo",
+            organization_id: this.organizationId,
+            recorded_by: opts.actor,
+            recorded_at: now
+          },
+          { context: ctx }
+        );
+      }
       return {
         eventSeq,
         existingHash,
@@ -884,20 +916,117 @@ var SysMetadataRepository = class {
         actor: opts.actor
       };
     });
-    this.seqCounter = result.eventSeq;
-    this.broadcast({
-      seq: result.eventSeq,
-      op: "delete",
-      ref: this.fullRef(ref),
-      hash: null,
-      parentHash: result.existingHash,
-      actor: result.actor,
-      message: result.message,
-      ts: result.now,
-      source: result.source
-    });
+    if (state === "active") {
+      this.seqCounter = result.eventSeq;
+      this.broadcast({
+        seq: result.eventSeq,
+        op: "delete",
+        ref: this.fullRef(ref),
+        hash: null,
+        parentHash: result.existingHash,
+        actor: result.actor,
+        message: result.message,
+        ts: result.now,
+        source: result.source
+      });
+    }
     return { seq: result.eventSeq };
   }
+  /**
+   * Promote the pending draft row for `ref` into the live (`active`)
+   * overlay. Atomic: reads the draft inside the same transaction, runs
+   * the canonical `put` to upsert the active row (which appends a
+   * history event with `operation_type='publish'`), then deletes the
+   * draft row.
+   *
+   * Errors if no draft exists (callers should 404). The active row's
+   * `parentVersion` is computed from the current active hash so this
+   * also surfaces optimistic-lock conflicts when something else has
+   * published in between (e.g. another admin reverted to an older
+   * version since the draft was authored).
+   */
+  async promoteDraft(ref, opts) {
+    this.assertOpen();
+    const draft = await this.get(ref, { state: "draft" });
+    if (!draft) {
+      const err = new Error(
+        `[no_draft] No pending draft exists for ${ref.type}/${ref.name} \u2014 nothing to publish.`
+      );
+      err.code = "no_draft";
+      err.status = 404;
+      throw err;
+    }
+    const currentActive = await this.get(ref, { state: "active" });
+    const result = await this.put(ref, draft.body, {
+      parentVersion: currentActive?.hash ?? null,
+      actor: opts.actor,
+      source: opts.source ?? "sys-metadata-repo.publish",
+      message: opts.message ?? `publish draft (hash ${draft.hash})`,
+      intent: opts.intent ?? "override-artifact",
+      state: "active",
+      opType: "publish"
+    });
+    try {
+      await this.delete(ref, {
+        parentVersion: draft.hash,
+        actor: opts.actor,
+        source: opts.source ?? "sys-metadata-repo.publish",
+        intent: opts.intent ?? "override-artifact",
+        state: "draft"
+      });
+    } catch {
+    }
+    return result;
+  }
+  /**
+   * Restore the body recorded in history at `targetVersion` (per-org
+   * lineage counter) as the new active row. Writes a history event
+   * with `operation_type='revert'` so the audit trail captures the
+   * intent. Does NOT touch any draft row.
+   *
+   * Throws `[version_not_found]` (404) if the target version row is
+   * missing or is a delete tombstone (no body to restore).
+   */
+  async restoreVersion(ref, targetVersion, opts) {
+    this.assertOpen();
+    const full = this.fullRef(ref);
+    const row = await this.engine.findOne(this.historyTable, {
+      where: {
+        organization_id: this.organizationId,
+        type: full.type,
+        name: full.name,
+        version: targetVersion
+      }
+    });
+    if (!row) {
+      const err = new Error(
+        `[version_not_found] No history row at version ${targetVersion} for ${ref.type}/${ref.name}.`
+      );
+      err.code = "version_not_found";
+      err.status = 404;
+      throw err;
+    }
+    const raw = row.metadata;
+    if (raw === null || raw === void 0) {
+      const err = new Error(
+        `[version_not_restorable] Version ${targetVersion} for ${ref.type}/${ref.name} is a delete tombstone \u2014 nothing to restore.`
+      );
+      err.code = "version_not_restorable";
+      err.status = 409;
+      throw err;
+    }
+    const body = typeof raw === "string" ? JSON.parse(raw) : raw;
+    const currentActive = await this.get(ref, { state: "active" });
+    return this.put(ref, body, {
+      parentVersion: currentActive?.hash ?? null,
+      actor: opts.actor,
+      source: opts.source ?? "sys-metadata-repo.revert",
+      message: opts.message ?? `revert to version ${targetVersion}`,
+      intent: opts.intent ?? "override-artifact",
+      state: "active",
+      opType: "revert"
+    });
+  }
   async *list(filter) {
     this.assertOpen();
     const where = {
@@ -952,6 +1081,7 @@ var SysMetadataRepository = class {
         ref: full,
         hash: row.checksum ?? null,
         parentHash: row.previous_checksum ?? null,
+        version: typeof row.version === "number" ? row.version : void 0,
         actor: row.recorded_by ?? "unknown",
         message: row.change_note ?? void 0,
         ts: row.recorded_at ?? (/* @__PURE__ */ new Date(0)).toISOString(),
@@ -1033,29 +1163,52 @@ var SysMetadataRepository = class {
   assertOpen() {
     if (this.closed) throw new Error("SysMetadataRepository is closed");
   }
-  assertAllowed(type) {
+  /**
+   * Defense-in-depth authorization gate.
+   *
+   * `intent` defaults to `'override-artifact'` (the historical strict
+   * behavior). The protocol layer passes `'runtime-only'` after it has
+   * verified — via the schema registry — that no artifact item exists
+   * 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
+   * applies to BOTH intents, so operators can opt into artifact
+   * overrides at runtime for emergency fixes.
+   */
+  assertAllowed(type, intent = "override-artifact") {
     const singular = PLURAL_TO_SINGULAR[type] ?? type;
     const allowedByRegistry = OVERLAY_ALLOWED_TYPES.has(singular) || OVERLAY_ALLOWED_TYPES.has(type);
     if (allowedByRegistry) return;
+    if (intent === "runtime-only") {
+      if (RUNTIME_CREATE_ALLOWED_TYPES.has(singular) || RUNTIME_CREATE_ALLOWED_TYPES.has(type)) {
+        return;
+      }
+      if (!STATIC_REGISTRY_TYPES.has(singular) && !STATIC_REGISTRY_TYPES.has(type)) {
+        return;
+      }
+    }
     const env = envWritableMetadataTypes();
     if (env.has(singular) || env.has(type)) return;
     const allowed = [
       ...OVERLAY_ALLOWED_TYPES,
       ...envWritableMetadataTypes()
     ];
+    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(
-      `[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.`
+      `[${code}] ${detail}Overlay-allowed: ${Array.from(new Set(allowed)).join(", ") || "(none)"}. Set OBJECTSTACK_METADATA_WRITABLE to enable additional types at runtime.`
     );
-    err.code = "not_overridable";
+    err.code = code;
     err.status = 403;
     throw err;
   }
-  whereFor(ref) {
+  whereFor(ref, state = "active") {
     return {
       type: ref.type,
       name: ref.name,
       organization_id: this.organizationId,
-      state: "active"
+      state
     };
   }
   fullRef(ref) {
@@ -1151,37 +1304,64 @@ var SysMetadataRepository = class {
 
 // src/protocol.ts
 import { ConflictError as ConflictError2 } from "@objectstack/metadata-core";
-import { parseFilterAST, isFilterAST, ObjectSchema as ObjectSchema2, FieldSchema, HookSchema } from "@objectstack/spec/data";
-import { PLURAL_TO_SINGULAR as PLURAL_TO_SINGULAR2, SINGULAR_TO_PLURAL as SINGULAR_TO_PLURAL2 } from "@objectstack/spec/shared";
-import { ListViewSchema, FormViewSchema, DashboardSchema, AppSchema as AppSchema2, PageSchema, ReportSchema, ActionSchema } from "@objectstack/spec/ui";
-import { RoleSchema } from "@objectstack/spec/identity";
-import { PermissionSetSchema } from "@objectstack/spec/security";
-import { EmailTemplateSchema, JobSchema, METADATA_FORM_REGISTRY } from "@objectstack/spec/system";
-import { ToolSchema, SkillSchema, AgentSchema } from "@objectstack/spec/ai";
-import { FlowSchema, WorkflowRuleSchema, ApprovalProcessSchema } from "@objectstack/spec/automation";
-import { DEFAULT_METADATA_TYPE_REGISTRY as DEFAULT_METADATA_TYPE_REGISTRY2 } from "@objectstack/spec/kernel";
+import { parseFilterAST, isFilterAST } from "@objectstack/spec/data";
+import { PLURAL_TO_SINGULAR as PLURAL_TO_SINGULAR3, SINGULAR_TO_PLURAL as SINGULAR_TO_PLURAL2 } from "@objectstack/spec/shared";
+import { METADATA_FORM_REGISTRY } from "@objectstack/spec/system";
+import { DEFAULT_METADATA_TYPE_REGISTRY as DEFAULT_METADATA_TYPE_REGISTRY2, getMetadataTypeSchema as getMetadataTypeSchema2 } from "@objectstack/spec/kernel";
+import {
+  extractProtection,
+  evaluateLockForWrite,
+  evaluateLockForDelete,
+  resolveLockState
+} from "@objectstack/spec/kernel";
 import { z } from "zod";
-var TYPE_TO_SCHEMA = {
-  object: ObjectSchema2,
-  field: FieldSchema,
-  dashboard: DashboardSchema,
-  app: AppSchema2,
-  page: PageSchema,
-  report: ReportSchema,
-  action: ActionSchema,
-  role: RoleSchema,
-  permission: PermissionSetSchema,
-  profile: PermissionSetSchema,
-  email_template: EmailTemplateSchema,
-  tool: ToolSchema,
-  skill: SkillSchema,
-  agent: AgentSchema,
-  flow: FlowSchema,
-  workflow: WorkflowRuleSchema,
-  approval: ApprovalProcessSchema,
-  job: JobSchema,
-  hook: HookSchema
-};
+
+// src/metadata-diagnostics.ts
+import { getMetadataTypeSchema } from "@objectstack/spec/kernel";
+import { PLURAL_TO_SINGULAR as PLURAL_TO_SINGULAR2 } from "@objectstack/spec/shared";
+function computeMetadataDiagnostics(type, item) {
+  const singular = PLURAL_TO_SINGULAR2[type] ?? type;
+  const schema = getMetadataTypeSchema(singular);
+  if (!schema) return void 0;
+  if (item === null || item === void 0 || typeof item !== "object") {
+    return {
+      valid: false,
+      errors: [{
+        path: "",
+        message: "Metadata document must be a non-null object",
+        code: "invalid_type"
+      }]
+    };
+  }
+  const candidate = "_diagnostics" in item ? stripDiagnostics(item) : item;
+  const parsed = schema.safeParse(candidate);
+  if (parsed.success) {
+    return { valid: true };
+  }
+  const errors = parsed.error.issues.map((issue) => ({
+    path: issue.path.map(String).join("."),
+    message: issue.message,
+    code: issue.code
+  }));
+  return { valid: false, errors };
+}
+function stripDiagnostics(item) {
+  const { _diagnostics: _drop, ...rest } = item;
+  void _drop;
+  return rest;
+}
+function decorateMetadataItem(type, item) {
+  if (!item || typeof item !== "object") return item;
+  const diagnostics = computeMetadataDiagnostics(type, item);
+  if (!diagnostics) return item;
+  return { ...item, _diagnostics: diagnostics };
+}
+function decorateMetadataItems(type, items) {
+  if (!Array.isArray(items)) return items;
+  return items.map((item) => decorateMetadataItem(type, item));
+}
+
+// src/protocol.ts
 var TYPE_TO_FORM = METADATA_FORM_REGISTRY;
 var _jsonSchemaCache = /* @__PURE__ */ new WeakMap();
 function toJsonSchemaSafe(schema) {
@@ -1211,9 +1391,17 @@ var HAND_CRAFTED_SCHEMAS = {
       abstract: { type: "boolean", default: false },
       datasource: { type: "string" },
       fields: {
-        type: "array",
-        default: [],
-        items: {
+        // Canonical Object.fields is a name-keyed map
+        // (Record<string, FieldDefinition>) — insertion order is
+        // display order. The SchemaForm engine recognises
+        // `additionalProperties` as a Record and dispatches to
+        // the `record` form-field renderer (ADR-0007). The form
+        // layout in `object.form.ts` declares `type: 'record'`
+        // so the inner `additionalProperties` schema is used to
+        // shape each value.
+        type: "object",
+        default: {},
+        additionalProperties: {
           type: "object",
           properties: {
             name: { type: "string" },
@@ -1224,7 +1412,7 @@ var HAND_CRAFTED_SCHEMAS = {
             defaultValue: {},
             description: { type: "string" }
           },
-          required: ["name", "type"]
+          required: ["type"]
         }
       },
       capabilities: { type: "object", additionalProperties: true }
@@ -1369,19 +1557,22 @@ var HAND_CRAFTED_SCHEMAS = {
     additionalProperties: true
   }
 };
-var FORM_VIEW_TYPES = /* @__PURE__ */ new Set(["simple", "tabbed", "wizard", "split", "drawer", "modal"]);
-function resolveOverlaySchema(type, item) {
-  const singular = PLURAL_TO_SINGULAR2[type] ?? type;
-  switch (singular) {
-    case "view": {
-      const t = item && typeof item === "object" && "type" in item ? String(item.type) : void 0;
-      return t && FORM_VIEW_TYPES.has(t) ? FormViewSchema : ListViewSchema;
-    }
-    case "dashboard":
-      return DashboardSchema;
-    default:
-      return null;
-  }
+function resolveOverlaySchema(type, _item) {
+  const singular = PLURAL_TO_SINGULAR3[type] ?? type;
+  return getMetadataTypeSchema2(singular) ?? null;
+}
+function mergeArtifactProtection(item, artifactItem) {
+  if (item === void 0 || item === null) return item;
+  if (artifactItem === void 0 || artifactItem === null) return item;
+  const a = artifactItem;
+  if (typeof a !== "object") return item;
+  const out = { ...item };
+  if (a._lock !== void 0) out._lock = a._lock;
+  if (a._lockReason !== void 0) out._lockReason = a._lockReason;
+  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;
+  return out;
 }
 function simpleHash(str) {
   let hash = 0;
@@ -1514,6 +1705,32 @@ function extractPathValues(item, path) {
   }
   return out;
 }
+function diffShallow(from, to) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  const fromKeys = new Set(Object.keys(from ?? {}));
+  const toKeys = new Set(Object.keys(to ?? {}));
+  for (const k of toKeys) {
+    if (!fromKeys.has(k)) {
+      added.push({ path: k, value: to[k] });
+    } else {
+      const a = from[k];
+      const b = to[k];
+      const aStr = JSON.stringify(a);
+      const bStr = JSON.stringify(b);
+      if (aStr !== bStr) {
+        changed.push({ path: k, from: a, to: b });
+      }
+    }
+  }
+  for (const k of fromKeys) {
+    if (!toKeys.has(k)) {
+      removed.push({ path: k, value: from[k] });
+    }
+  }
+  return { added, removed, changed };
+}
 function detectDestructiveObjectChanges(prev, next) {
   if (!prev || typeof prev !== "object" || !next || typeof next !== "object") return [];
   const prevFields = prev.fields && typeof prev.fields === "object" ? prev.fields : {};
@@ -1645,6 +1862,20 @@ 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(draftPartialSql);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        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)"
+            );
+          } catch {
+          }
+        }
+      }
     } catch {
     }
   }
@@ -1768,8 +1999,8 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       DEFAULT_METADATA_TYPE_REGISTRY2.map((e) => [e.type, e])
     );
     const entries = allTypes.map((type) => {
-      const singular = PLURAL_TO_SINGULAR2[type] ?? type;
-      const zodSchema = singular === "view" ? ListViewSchema : TYPE_TO_SCHEMA[singular];
+      const singular = PLURAL_TO_SINGULAR3[type] ?? type;
+      const zodSchema = getMetadataTypeSchema2(singular);
       const schema = (zodSchema ? toJsonSchemaSafe(zodSchema) : void 0) ?? HAND_CRAFTED_SCHEMAS[singular];
       const form = TYPE_TO_FORM[singular];
       const base = registryByType.get(singular);
@@ -1810,19 +2041,82 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     });
     return { types: allTypes, entries };
   }
+  /**
+   * Sweep all (or filtered) metadata types and report entries that
+   * fail spec validation. Powers the Studio governance view
+   * (`GET /api/v1/meta/diagnostics`) and `os doctor`-style CLI
+   * checks.
+   *
+   * `severity` defaults to `'error'` — only entries with at least
+   * one Zod error issue are returned. `'warning'` includes
+   * everything we surface (warnings are reserved for a future lint
+   * layer on top of spec validation).
+   *
+   * `type` may be either a singular (`'view'`) or plural (`'views'`)
+   * identifier; the underlying `getMetaItems` already normalises.
+   *
+   * Implementation note: leverages the `_diagnostics` already
+   * decorated onto items by `getMetaItems()` to avoid running
+   * `safeParse()` twice. For types whose schema is unregistered we
+   * skip silently (they cannot be validated and should not appear
+   * as "valid" either — they are simply opaque to this report).
+   */
+  async getMetaDiagnostics(request = {}) {
+    const includeWarnings = request.severity === "warning";
+    const targetTypes = request.type ? [request.type] : DEFAULT_METADATA_TYPE_REGISTRY2.filter((e) => getMetadataTypeSchema2(e.type)).map((e) => e.type);
+    const entries = [];
+    const stats = {};
+    let scannedItems = 0;
+    for (const t of targetTypes) {
+      let listed;
+      try {
+        listed = await this.getMetaItems({
+          type: t,
+          organizationId: request.organizationId,
+          packageId: request.packageId
+        });
+      } catch {
+        continue;
+      }
+      const items = Array.isArray(listed?.items) ? listed.items : Array.isArray(listed) ? listed : [];
+      const pkgSet = /* @__PURE__ */ new Set();
+      for (const item of items) {
+        scannedItems += 1;
+        const pkg = item?._packageId ?? null;
+        if (pkg) pkgSet.add(pkg);
+        const diag = item?._diagnostics ?? computeMetadataDiagnostics(t, item);
+        if (!diag) continue;
+        if (diag.valid && !includeWarnings) continue;
+        if (diag.valid && includeWarnings && !diag.warnings?.length) continue;
+        entries.push({
+          type: t,
+          name: typeof item?.name === "string" ? item.name : "<unknown>",
+          diagnostics: diag
+        });
+      }
+      stats[t] = { count: items.length, packages: [...pkgSet].sort() };
+    }
+    return {
+      entries,
+      total: entries.length,
+      scannedTypes: targetTypes.length,
+      scannedItems,
+      stats
+    };
+  }
   async getMetaItems(request) {
     const { packageId } = request;
     let items = [];
     if (this.environmentId === void 0) {
       items = [...this.engine.registry.listItems(request.type, packageId)];
       if (items.length === 0) {
-        const alt = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+        const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[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 = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+        const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
         if (alt) items = [...this.engine.registry.listItems(alt, packageId)];
       }
     }
@@ -1837,7 +2131,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 = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+          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;
@@ -1904,28 +2198,38 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     }
     return {
       type: request.type,
-      items
+      items: decorateMetadataItems(
+        request.type,
+        items.map((it) => {
+          const a = this.lookupArtifactItem(
+            request.type,
+            it?.name
+          );
+          return mergeArtifactProtection(it, a);
+        })
+      )
     };
   }
   async getMetaItem(request) {
     let item;
     const orgId = request.organizationId;
+    const readState = request.state === "draft" ? "draft" : "active";
     try {
       const findOverlay = async (oid) => {
         const where = {
           type: request.type,
           name: request.name,
-          state: "active",
+          state: readState,
           organization_id: oid
         };
         const rec = await this.engine.findOne("sys_metadata", { where });
         if (rec) return rec;
-        const alt = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+        const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
         if (alt) {
           const altWhere = {
             type: alt,
             name: request.name,
-            state: "active",
+            state: readState,
             organization_id: oid
           };
           return await this.engine.findOne("sys_metadata", { where: altWhere });
@@ -1938,6 +2242,17 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
     } catch {
     }
+    if (readState === "draft") {
+      if (item === void 0) {
+        const err = new Error(
+          `[no_draft] No pending draft exists for ${request.type}/${request.name}.`
+        );
+        err.code = "no_draft";
+        err.status = 404;
+        throw err;
+      }
+      return { type: request.type, name: request.name, item: decorateMetadataItem(request.type, item) };
+    }
     if (item === void 0) {
       try {
         const services = this.getServicesRegistry?.();
@@ -1947,7 +2262,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           if (fromService !== void 0 && fromService !== null) {
             item = fromService;
           } else {
-            const alt = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+            const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
             if (alt) {
               const altFromService = await metadataService.get(alt, request.name);
               if (altFromService !== void 0 && altFromService !== null) {
@@ -1962,14 +2277,30 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (item === void 0) {
       item = this.engine.registry.getItem(request.type, request.name);
       if (item === void 0) {
-        const alt = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+        const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
         if (alt) item = this.engine.registry.getItem(alt, request.name);
       }
     }
+    const artifactItem = this.lookupArtifactItem(request.type, request.name);
+    const decorated = decorateMetadataItem(
+      request.type,
+      mergeArtifactProtection(item, artifactItem)
+    );
+    const artifactBacked = this.isArtifactBacked(request.type, request.name);
+    const lockState = resolveLockState(decorated, artifactBacked);
     return {
       type: request.type,
       name: request.name,
-      item
+      item: decorated,
+      lock: lockState.lock,
+      ...lockState.lockReason !== void 0 ? { lockReason: lockState.lockReason } : {},
+      ...lockState.lockSource !== void 0 ? { lockSource: lockState.lockSource } : {},
+      ...lockState.provenance !== void 0 ? { provenance: lockState.provenance } : {},
+      ...lockState.packageId !== void 0 ? { packageId: lockState.packageId } : {},
+      ...lockState.packageVersion !== void 0 ? { packageVersion: lockState.packageVersion } : {},
+      editable: lockState.editable,
+      deletable: lockState.deletable,
+      resettable: lockState.resettable
     };
   }
   /**
@@ -1995,7 +2326,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 = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+          const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
           if (alt) fromService = await metadataService.get(alt, request.name);
         }
         if (fromService !== void 0 && fromService !== null) code = fromService;
@@ -2005,7 +2336,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (code === null) {
       let regItem = this.engine.registry.getItem(request.type, request.name);
       if (regItem === void 0) {
-        const alt = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+        const alt = PLURAL_TO_SINGULAR3[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
         if (alt) regItem = this.engine.registry.getItem(alt, request.name);
       }
       if (regItem !== void 0) code = regItem;
@@ -2022,7 +2353,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         };
         let rec = await this.engine.findOne("sys_metadata", { where });
         if (!rec) {
-          const alt = PLURAL_TO_SINGULAR2[request.type] ?? SINGULAR_TO_PLURAL2[request.type];
+          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 }
@@ -2048,15 +2379,80 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     } catch {
     }
     const effective = overlay ?? code;
+    const _diagnostics = effective !== null && effective !== void 0 ? computeMetadataDiagnostics(request.type, effective) : void 0;
+    const artifactBacked = this.isArtifactBacked(request.type, request.name);
+    const lockSource = code ?? overlay ?? {};
+    const lockState = resolveLockState(lockSource, artifactBacked);
     return {
       type: request.type,
       name: request.name,
       code,
       overlay,
       overlayScope,
-      effective
+      effective,
+      ..._diagnostics ? { _diagnostics } : {},
+      lock: lockState.lock,
+      ...lockState.lockReason !== void 0 ? { lockReason: lockState.lockReason } : {},
+      ...lockState.lockSource !== void 0 ? { lockSource: lockState.lockSource } : {},
+      ...lockState.provenance !== void 0 ? { provenance: lockState.provenance } : {},
+      ...lockState.packageId !== void 0 ? { packageId: lockState.packageId } : {},
+      ...lockState.packageVersion !== void 0 ? { packageVersion: lockState.packageVersion } : {},
+      editable: lockState.editable,
+      deletable: lockState.deletable,
+      resettable: lockState.resettable
     };
   }
+  /**
+   * ADR-0010 §3.6 / Phase 4.1 — read the metadata-protection audit log
+   * for a single item. Returns the most-recent rows of
+   * `sys_metadata_audit` for this (type, name) tuple, sorted newest
+   * first. Refused (`denied`) and forced (`forced`) writes both appear
+   * here — they never reach the `history` endpoint, which only tracks
+   * successful body snapshots.
+   *
+   * The table is provisioned by `platform-objects` and is the
+   * compliance surface for the lock-enforcement story. When the
+   * environment has not yet provisioned the table (legacy install
+   * prior to ADR-0010) the call returns `{ events: [] }` instead of
+   * raising, keeping the Studio tab harmless.
+   */
+  async auditMetaItem(request) {
+    const singular = PLURAL_TO_SINGULAR3[request.type] ?? request.type;
+    const limit = Math.min(
+      Math.max(1, request.limit ?? 100),
+      500
+    );
+    try {
+      const where = {
+        type: singular,
+        name: request.name
+      };
+      const rows = await this.engine.find("sys_metadata_audit", {
+        where,
+        orderBy: [{ field: "occurred_at", direction: "desc" }],
+        limit
+      });
+      const events = (Array.isArray(rows) ? rows : []).map((r) => ({
+        id: r.id,
+        occurredAt: typeof r.occurred_at === "string" ? r.occurred_at : r.occurred_at instanceof Date ? r.occurred_at.toISOString() : String(r.occurred_at ?? ""),
+        actor: String(r.actor ?? "system"),
+        source: r.source ?? null,
+        operation: r.operation,
+        outcome: r.outcome,
+        code: String(r.code ?? ""),
+        lockState: r.lock_state ?? null,
+        lockOverridden: Boolean(r.lock_overridden),
+        requestId: r.request_id ?? null,
+        note: r.note ?? null
+      }));
+      return { events };
+    } catch (err) {
+      console.warn(
+        `[Protocol] auditMetaItem read failed for ${request.type}/${request.name}: ${err?.message ?? err}`
+      );
+      return { events: [] };
+    }
+  }
   async getUiView(request) {
     const schema = this.engine.registry.getObject(request.object);
     if (!schema) throw new Error(`Object ${request.object} not found`);
@@ -2935,7 +3331,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     for (const tok of raw.split(",")) {
       const t = tok.trim();
       if (!t) continue;
-      const singular = PLURAL_TO_SINGULAR2[t] ?? t;
+      const singular = PLURAL_TO_SINGULAR3[t] ?? t;
       set.add(singular);
       const plural = SINGULAR_TO_PLURAL2[singular];
       if (plural) set.add(plural);
@@ -2949,13 +3345,201 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
   }
   /** Normalize plural→singular before consulting the allow-list. */
   static isOverlayAllowed(type) {
-    const singular = PLURAL_TO_SINGULAR2[type] ?? type;
+    const singular = PLURAL_TO_SINGULAR3[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);
   }
+  /** Does this type permit creating brand-new (artifact-free) items? */
+  static isRuntimeCreateAllowed(type) {
+    const singular = PLURAL_TO_SINGULAR3[type] ?? type;
+    if (this.RUNTIME_CREATE_ALLOWED_TYPES.has(singular) || this.RUNTIME_CREATE_ALLOWED_TYPES.has(type)) {
+      return true;
+    }
+    if (!this.STATIC_REGISTRY_TYPES.has(singular) && !this.STATIC_REGISTRY_TYPES.has(type)) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Does an artifact (npm-package-loaded) item exist at `(type, name)`?
+   *
+   * The schema registry's `_packageId` tag is set only when
+   * `registerItem(..., packageId)` is called with a truthy packageId
+   * — and only artifact loaders do that. DB-rehydrated items
+   * (sys_metadata rows registered back into the registry by
+   * `getMetaItems` / `loadMetaFromDb`) call `registerItem` without a
+   * packageId, so they carry no `_packageId` and are correctly
+   * excluded here.
+   *
+   * Used by the two-tier authorization model to distinguish
+   * "overlaying a packaged item" (requires `allowOrgOverride`) from
+   * "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";
+  }
+  // ───────────────────────────────────────────────────────────────────
+  // ADR-0010 — metadata protection (Phase 1: L3 item-level lock)
+  // ───────────────────────────────────────────────────────────────────
+  /**
+   * Look up an item from the artifact registry across both the requested
+   * type and its singular/plural twin. Returns `undefined` when the
+   * registry is unavailable or the item is not artifact-backed.
+   */
+  lookupArtifactItem(type, name) {
+    const registry = this.engine?.registry;
+    if (!registry || typeof registry.getItem !== "function") return void 0;
+    const singular = PLURAL_TO_SINGULAR3[type] ?? type;
+    return registry.getItem(singular, name) ?? registry.getItem(type, name);
+  }
+  /**
+   * Resolve the effective `_lock` for an item by consulting the
+   * artifact registry first, then the persisted overlay row. Artifact
+   * always wins — by design, an overlay cannot loosen a packaged
+   * lock (ADR-0010 §3.3).
+   *
+   * Returns `'none'` when nothing is locked, which is the common
+   * case. Safe to call when `environmentId` is undefined (control-
+   * plane bootstrap) — the lock check is only meaningful in tenant
+   * 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 p = extractProtection(artifactItem);
+      if (p.lock !== "none") {
+        return { lock: p.lock, lockReason: p.lockReason, lockSource: "artifact" };
+      }
+    }
+    try {
+      const where = {
+        type,
+        name,
+        state: "active",
+        organization_id: organizationId ?? null
+      };
+      const row = await this.engine.findOne("sys_metadata", { where });
+      if (row) {
+        const body = typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata;
+        const p = extractProtection(body);
+        if (p.lock !== "none") {
+          return { lock: p.lock, lockReason: p.lockReason, lockSource: "overlay" };
+        }
+      }
+    } catch {
+    }
+    return { lock: "none", lockReason: void 0, lockSource: void 0 };
+  }
+  /**
+   * Best-effort audit-row writer (ADR-0010 §3.6). Failures here are
+   * logged but never block the underlying decision: an environment
+   * without the audit table provisioned (legacy installs before this
+   * ADR landed) still answers normal API calls, just without the
+   * compliance trail. Phase 2 will make the audit table a hard
+   * dependency.
+   */
+  async recordMetadataAudit(entry) {
+    try {
+      await this.engine.insert("sys_metadata_audit", {
+        occurred_at: (/* @__PURE__ */ new Date()).toISOString(),
+        actor: entry.actor ?? "system",
+        source: entry.source ?? "protocol",
+        type: PLURAL_TO_SINGULAR3[entry.type] ?? entry.type,
+        name: entry.name,
+        organization_id: entry.organizationId ?? null,
+        operation: entry.operation,
+        outcome: entry.outcome,
+        code: entry.code,
+        lock_state: entry.lockState ?? "none",
+        lock_overridden: entry.lockOverridden ?? false,
+        request_id: entry.requestId ?? null,
+        note: entry.note ?? null
+      });
+    } catch (err) {
+      console.warn(
+        `[Protocol] sys_metadata_audit write failed for ${entry.type}/${entry.name}: ${err?.message ?? err}`
+      );
+    }
+  }
+  /**
+   * Phase 1 L3 enforcement for write operations (save / publish /
+   * rollback). Returns null on allow. Returns the structured `Error`
+   * the caller should `throw` on deny — also records the denial in
+   * the audit log so refused attempts are visible in compliance
+   * reports (refused writes never reach sys_metadata_history).
+   */
+  async assertLockAllowsWrite(args) {
+    if (this.environmentId === void 0) return null;
+    const state = await this.getEffectiveLock(args.type, args.name, args.organizationId ?? null);
+    const refusal = evaluateLockForWrite(state.lock);
+    if (!refusal) return null;
+    const reason = state.lockReason ?? refusal.reason;
+    const err = new Error(
+      `[item_locked] ${args.type}/${args.name} is locked (_lock=${state.lock}${state.lockSource ? `, source=${state.lockSource}` : ""}). ${reason} \u2014 See ADR-0010 \xA73.3.`
+    );
+    err.code = "item_locked";
+    err.status = 403;
+    err.lock = state.lock;
+    err.lockReason = reason;
+    await this.recordMetadataAudit({
+      type: args.type,
+      name: args.name,
+      organizationId: args.organizationId ?? null,
+      operation: args.operation,
+      outcome: "denied",
+      code: "item_locked",
+      lockState: state.lock,
+      actor: args.actor,
+      source: args.source ?? `protocol.${args.operation}MetaItem`,
+      requestId: args.requestId,
+      note: reason
+    });
+    return err;
+  }
+  /** Counterpart of {@link assertLockAllowsWrite} for delete. */
+  async assertLockAllowsDelete(args) {
+    if (this.environmentId === void 0) return null;
+    const state = await this.getEffectiveLock(args.type, args.name, args.organizationId ?? null);
+    const refusal = evaluateLockForDelete(state.lock);
+    if (!refusal) return null;
+    const reason = state.lockReason ?? refusal.reason;
+    const err = new Error(
+      `[item_locked] ${args.type}/${args.name} is locked (_lock=${state.lock}${state.lockSource ? `, source=${state.lockSource}` : ""}). ${reason} \u2014 See ADR-0010 \xA73.3.`
+    );
+    err.code = "item_locked";
+    err.status = 403;
+    err.lock = state.lock;
+    err.lockReason = reason;
+    await this.recordMetadataAudit({
+      type: args.type,
+      name: args.name,
+      organizationId: args.organizationId ?? null,
+      operation: "delete",
+      outcome: "denied",
+      code: "item_locked",
+      lockState: state.lock,
+      actor: args.actor,
+      source: args.source ?? "protocol.deleteMetaItem",
+      requestId: args.requestId,
+      note: reason
+    });
+    return err;
+  }
   /**
    * Mirror an object-type overlay write into the in-memory engine
    * registry so subsequent CRUD finds the new schema. Idempotent and
@@ -2981,16 +3565,38 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     if (!request.item) {
       throw new Error("Item data is required");
     }
-    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, 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 mode = request.mode === "draft" ? "draft" : "publish";
+    if (this.environmentId !== void 0) {
+      const overlayAllowed = _ObjectStackProtocolImplementation.isOverlayAllowed(request.type);
+      const runtimeCreateAllowed = _ObjectStackProtocolImplementation.isRuntimeCreateAllowed(request.type);
+      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.`
+        );
+        err.code = "not_overridable";
+        err.status = 403;
+        throw err;
+      }
+      if (!artifactBacked && !overlayAllowed && !runtimeCreateAllowed) {
+        const err = new Error(
+          `[not_creatable] Metadata type '${request.type}' does not allow runtime creation (allowRuntimeCreate=false, allowOrgOverride=false). New items of this type must be defined in source code.`
+        );
+        err.code = "not_creatable";
+        err.status = 403;
+        throw err;
+      }
+      const lockErr = await this.assertLockAllowsWrite({
+        type: request.type,
+        name: request.name,
+        ...request.organizationId ? { organizationId: request.organizationId } : {},
+        operation: "save",
+        ...request.actor ? { actor: request.actor } : {},
+        source: "protocol.saveMetaItem"
+      });
+      if (lockErr) throw lockErr;
     }
-    const singularType = PLURAL_TO_SINGULAR2[request.type] ?? request.type;
+    const singularType = PLURAL_TO_SINGULAR3[request.type] ?? request.type;
     if (!request.force && (singularType === "object" || singularType === "field")) {
       try {
         const existing = await this.getMetaItem({
@@ -3038,8 +3644,13 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
     }
     await this.ensureOverlayIndex();
-    const singularTypeForRepo = PLURAL_TO_SINGULAR2[request.type] ?? request.type;
-    if (_ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo)) {
+    const singularTypeForRepo = PLURAL_TO_SINGULAR3[request.type] ?? request.type;
+    const overlayAllowedForRepo = _ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo);
+    const runtimeCreateAllowedForRepo = _ObjectStackProtocolImplementation.isRuntimeCreateAllowed(singularTypeForRepo);
+    const useRepoPath = overlayAllowedForRepo || runtimeCreateAllowedForRepo;
+    if (useRepoPath) {
+      const artifactBacked = this.isArtifactBacked(singularTypeForRepo, request.name);
+      const intent = artifactBacked ? "override-artifact" : "runtime-only";
       const orgId = request.organizationId ?? null;
       const repo = this.getOverlayRepo(orgId);
       const ref = {
@@ -3051,21 +3662,37 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       if (request.parentVersion !== void 0) {
         parentVersion = request.parentVersion;
       } else {
-        const current = await repo.get(ref);
+        const current = await repo.get(ref, { state: mode === "draft" ? "draft" : "active" });
         parentVersion = current?.hash ?? null;
       }
       try {
         const result = await repo.put(ref, request.item, {
           parentVersion,
           actor: request.actor ?? "system",
-          source: "protocol.saveMetaItem"
+          source: "protocol.saveMetaItem",
+          intent,
+          state: mode === "draft" ? "draft" : "active"
+        });
+        if (mode === "publish") {
+          this.applyObjectRegistryMutation(request);
+        }
+        await this.recordMetadataAudit({
+          type: request.type,
+          name: request.name,
+          organizationId: orgId,
+          operation: "save",
+          outcome: "allowed",
+          code: "ok",
+          ...request.actor ? { actor: request.actor } : {},
+          source: "protocol.saveMetaItem",
+          note: mode === "draft" ? "draft" : "active"
         });
-        this.applyObjectRegistryMutation(request);
         return {
           success: true,
           version: result.version,
           seq: result.seq,
-          message: orgId ? `Saved customization overlay (org=${orgId}) \u2014 type=${request.type}, name=${request.name} [seq=${result.seq}]` : `Saved customization overlay (env-wide) \u2014 type=${request.type}, name=${request.name} [seq=${result.seq}]`
+          state: mode === "draft" ? "draft" : "active",
+          message: orgId ? `Saved customization overlay (org=${orgId}, state=${mode === "draft" ? "draft" : "active"}) \u2014 type=${request.type}, name=${request.name} [seq=${result.seq}]` : `Saved customization overlay (env-wide, state=${mode === "draft" ? "draft" : "active"}) \u2014 type=${request.type}, name=${request.name} [seq=${result.seq}]`
         };
       } catch (err) {
         if (err instanceof ConflictError2) {
@@ -3149,8 +3776,8 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * "no history" uniformly.
    */
   async historyMetaItem(request) {
-    const singularType = PLURAL_TO_SINGULAR2[request.type] ?? request.type;
-    if (!_ObjectStackProtocolImplementation.isOverlayAllowed(singularType)) {
+    const singularType = PLURAL_TO_SINGULAR3[request.type] ?? request.type;
+    if (!_ObjectStackProtocolImplementation.isOverlayAllowed(singularType) && !_ObjectStackProtocolImplementation.isRuntimeCreateAllowed(singularType)) {
       return { events: [] };
     }
     const orgId = request.organizationId ?? null;
@@ -3168,22 +3795,264 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     return { events };
   }
   /**
-   * Remove a customization overlay row for the given metadata item, so the
-   * next read falls through to the artifact-loaded default. Implements the
-   * "Reset to factory default" semantic from ADR-0005. Whitelist is shared
-   * with {@link saveMetaItem}.
+   * Promote the pending draft overlay to the live (`active`) row.
+   * Records a history event with `op='publish'`. 404 (`[no_draft]`)
+   * when there is nothing to publish.
    */
-  async deleteMetaItem(request) {
-    if (this.environmentId !== void 0 && !_ObjectStackProtocolImplementation.isOverlayAllowed(request.type)) {
+  async publishMetaItem(request) {
+    const singularType = PLURAL_TO_SINGULAR3[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.`
+      );
+      err.code = "not_overridable";
+      err.status = 403;
+      throw err;
+    }
+    const _publishLockErr = await this.assertLockAllowsWrite({
+      type: request.type,
+      name: request.name,
+      ...request.organizationId ? { organizationId: request.organizationId } : {},
+      operation: "publish",
+      ...request.actor ? { actor: request.actor } : {},
+      source: "protocol.publishMetaItem"
+    });
+    if (_publishLockErr) throw _publishLockErr;
+    await this.ensureOverlayIndex();
+    const orgId = request.organizationId ?? null;
+    const repo = this.getOverlayRepo(orgId);
+    const artifactBacked = this.isArtifactBacked(singularType, request.name);
+    const intent = artifactBacked ? "override-artifact" : "runtime-only";
+    const ref = {
+      type: singularType,
+      name: request.name,
+      org: orgId ?? "env"
+    };
+    try {
+      const result = await repo.promoteDraft(ref, {
+        actor: request.actor ?? "system",
+        source: "protocol.publishMetaItem",
+        ...request.message ? { message: request.message } : {},
+        intent
+      });
+      this.applyObjectRegistryMutation({
+        type: request.type,
+        name: request.name,
+        item: result.item.body
+      });
+      return {
+        success: true,
+        version: result.version,
+        seq: result.seq,
+        message: `Published draft \u2014 type=${request.type}, name=${request.name} [seq=${result.seq}]`
+      };
+    } catch (err) {
+      if (err instanceof ConflictError2) {
+        const conflict = new Error(
+          `[metadata_conflict] ${request.type}/${request.name} published row advanced while you held the draft. Expected parent ${err.expectedParent ?? "null"} but current is ${err.actualHead ?? "null"}.`
+        );
+        conflict.code = "metadata_conflict";
+        conflict.status = 409;
+        conflict.expectedParent = err.expectedParent;
+        conflict.actualHead = err.actualHead;
+        throw conflict;
+      }
+      throw err;
+    }
+  }
+  /**
+   * Restore the body recorded at history `toVersion` as the new
+   * live row. Writes a history event with `op='revert'`. 404
+   * (`[version_not_found]`) when the target version doesn't exist;
+   * 409 (`[version_not_restorable]`) when the target is a delete
+   * tombstone (no body to bring back).
+   */
+  async rollbackMetaItem(request) {
+    if (!Number.isFinite(request.toVersion) || request.toVersion < 1) {
       const err = new Error(
-        `[not_overridable] Metadata type '${request.type}' has not opted into per-org overlay writes. See docs/adr/0005-metadata-customization-overlay.md.`
+        `[invalid_request] rollbackMetaItem requires a positive integer 'toVersion' (got ${request.toVersion}).`
+      );
+      err.code = "invalid_request";
+      err.status = 400;
+      throw err;
+    }
+    const singularType = PLURAL_TO_SINGULAR3[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.`
       );
       err.code = "not_overridable";
       err.status = 403;
       throw err;
     }
-    const singularTypeForRepo = PLURAL_TO_SINGULAR2[request.type] ?? request.type;
-    const useRepoPath = _ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo);
+    const _rollbackLockErr = await this.assertLockAllowsWrite({
+      type: request.type,
+      name: request.name,
+      ...request.organizationId ? { organizationId: request.organizationId } : {},
+      operation: "rollback",
+      ...request.actor ? { actor: request.actor } : {},
+      source: "protocol.rollbackMetaItem"
+    });
+    if (_rollbackLockErr) throw _rollbackLockErr;
+    await this.ensureOverlayIndex();
+    const orgId = request.organizationId ?? null;
+    const repo = this.getOverlayRepo(orgId);
+    const artifactBacked = this.isArtifactBacked(singularType, request.name);
+    const intent = artifactBacked ? "override-artifact" : "runtime-only";
+    const ref = {
+      type: singularType,
+      name: request.name,
+      org: orgId ?? "env"
+    };
+    try {
+      const result = await repo.restoreVersion(ref, request.toVersion, {
+        actor: request.actor ?? "system",
+        source: "protocol.rollbackMetaItem",
+        ...request.message ? { message: request.message } : {},
+        intent
+      });
+      this.applyObjectRegistryMutation({
+        type: request.type,
+        name: request.name,
+        item: result.item.body
+      });
+      return {
+        success: true,
+        version: result.version,
+        seq: result.seq,
+        restoredFromVersion: request.toVersion,
+        message: `Reverted to version ${request.toVersion} \u2014 type=${request.type}, name=${request.name} [seq=${result.seq}]`
+      };
+    } catch (err) {
+      if (err instanceof ConflictError2) {
+        const conflict = new Error(
+          `[metadata_conflict] ${request.type}/${request.name} advanced during rollback. Expected parent ${err.expectedParent ?? "null"} but current is ${err.actualHead ?? "null"}.`
+        );
+        conflict.code = "metadata_conflict";
+        conflict.status = 409;
+        conflict.expectedParent = err.expectedParent;
+        conflict.actualHead = err.actualHead;
+        throw conflict;
+      }
+      throw err;
+    }
+  }
+  /**
+   * Compute a shallow structural diff between two historical
+   * versions of a metadata item. Either side may be omitted: when
+   * `toVersion` is undefined the current active body is used; when
+   * `fromVersion` is undefined the immediately previous history row
+   * is used. Returns `{ added, removed, changed }` keyed by JSON
+   * pointer-style paths for primitive leaves; nested objects/arrays
+   * are reported as a single change record.
+   */
+  async diffMetaItem(request) {
+    const singularType = PLURAL_TO_SINGULAR3[request.type] ?? request.type;
+    const orgId = request.organizationId ?? null;
+    const events = (await this.historyMetaItem({
+      type: singularType,
+      name: request.name,
+      ...orgId ? { organizationId: orgId } : {}
+    })).events;
+    const versions = events.map((ev) => ev.version).filter((v) => typeof v === "number");
+    const repo = this.getOverlayRepo(orgId);
+    const fullRef = {
+      type: singularType,
+      name: request.name,
+      org: orgId ?? "env"
+    };
+    const histRows = [];
+    try {
+      const engineAny = this.engine;
+      const rows = await engineAny.find("sys_metadata_history", {
+        where: {
+          organization_id: orgId,
+          type: singularType,
+          name: request.name
+        }
+      });
+      rows.sort((a, b) => (a.version ?? 0) - (b.version ?? 0));
+      for (const r of rows) {
+        const body = r.metadata == null ? null : typeof r.metadata === "string" ? JSON.parse(r.metadata) : r.metadata;
+        histRows.push({ version: r.version ?? 0, body });
+      }
+    } catch {
+    }
+    const byVersion = /* @__PURE__ */ new Map();
+    for (const r of histRows) byVersion.set(r.version, r.body);
+    let fromBody = null;
+    let toBody = null;
+    let fromVersion = null;
+    let toVersion = null;
+    if (request.toVersion !== void 0) {
+      toVersion = request.toVersion;
+      toBody = byVersion.get(request.toVersion) ?? null;
+    } else {
+      const current = await repo.get(fullRef, { state: "active" });
+      toBody = current ? current.body : null;
+      toVersion = histRows.length ? histRows[histRows.length - 1].version : null;
+    }
+    if (request.fromVersion !== void 0) {
+      fromVersion = request.fromVersion;
+      fromBody = byVersion.get(request.fromVersion) ?? null;
+    } else if (toVersion !== null) {
+      const sorted = histRows.map((r) => r.version).filter((v) => v < toVersion);
+      if (sorted.length) {
+        fromVersion = sorted[sorted.length - 1];
+        fromBody = byVersion.get(fromVersion) ?? null;
+      }
+    }
+    const diff = diffShallow(fromBody ?? {}, toBody ?? {});
+    const _used = versions;
+    void _used;
+    return {
+      type: request.type,
+      name: request.name,
+      fromVersion,
+      toVersion,
+      ...diff
+    };
+  }
+  /**
+   * Remove a customization overlay row for the given metadata item, so the
+   * next read falls through to the artifact-loaded default. Implements the
+   * "Reset to factory default" semantic from ADR-0005. Whitelist is shared
+   * with {@link saveMetaItem}.
+   */
+  async deleteMetaItem(request) {
+    if (this.environmentId !== void 0) {
+      const overlayAllowed = _ObjectStackProtocolImplementation.isOverlayAllowed(request.type);
+      const runtimeCreateAllowed = _ObjectStackProtocolImplementation.isRuntimeCreateAllowed(request.type);
+      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. See docs/adr/0005-metadata-customization-overlay.md.`
+        );
+        err.code = "not_overridable";
+        err.status = 403;
+        throw err;
+      }
+      if (!artifactBacked && !overlayAllowed && !runtimeCreateAllowed) {
+        const err = new Error(
+          `[not_creatable] Metadata type '${request.type}' does not allow runtime creation or deletion.`
+        );
+        err.code = "not_creatable";
+        err.status = 403;
+        throw err;
+      }
+      const lockErr = await this.assertLockAllowsDelete({
+        type: request.type,
+        name: request.name,
+        ...request.organizationId ? { organizationId: request.organizationId } : {},
+        ...request.actor ? { actor: request.actor } : {},
+        source: "protocol.deleteMetaItem"
+      });
+      if (lockErr) throw lockErr;
+    }
+    const singularTypeForRepo = PLURAL_TO_SINGULAR3[request.type] ?? request.type;
+    const overlayAllowedForRepoDel = _ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo);
+    const runtimeCreateAllowedForRepoDel = _ObjectStackProtocolImplementation.isRuntimeCreateAllowed(singularTypeForRepo);
+    const useRepoPath = overlayAllowedForRepoDel || runtimeCreateAllowedForRepoDel;
     if (useRepoPath) {
       const orgId = request.organizationId ?? null;
       const repo = this.getOverlayRepo(orgId);
@@ -3193,19 +4062,22 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         org: orgId ?? "env"
       };
       try {
-        const current = await repo.get(ref);
+        const targetState = request.state === "draft" ? "draft" : "active";
+        const current = await repo.get(ref, { state: targetState });
         if (!current) {
           return {
             success: true,
             reset: false,
-            message: `No customization overlay found for ${request.type}/${request.name} \u2014 already at artifact default.`
+            message: targetState === "draft" ? `No pending draft for ${request.type}/${request.name}.` : `No customization overlay found for ${request.type}/${request.name} \u2014 already at artifact default.`
           };
         }
         const parentVersion = request.parentVersion !== void 0 ? request.parentVersion ?? current.hash : current.hash;
         const result = await repo.delete(ref, {
           parentVersion,
           actor: request.actor ?? "system",
-          source: "protocol.deleteMetaItem"
+          source: "protocol.deleteMetaItem",
+          intent: this.isArtifactBacked(singularTypeForRepo, request.name) ? "override-artifact" : "runtime-only",
+          state: targetState
         });
         if (this.environmentId === void 0) {
           try {
@@ -3220,11 +4092,22 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
           } catch {
           }
         }
+        await this.recordMetadataAudit({
+          type: request.type,
+          name: request.name,
+          organizationId: orgId,
+          operation: "delete",
+          outcome: "allowed",
+          code: "ok",
+          ...request.actor ? { actor: request.actor } : {},
+          source: "protocol.deleteMetaItem",
+          note: targetState
+        });
         return {
           success: true,
           reset: true,
           seq: result.seq,
-          message: `Customization overlay deleted \u2014 ${request.type}/${request.name} reset to artifact default. [seq=${result.seq}]`
+          message: request.state === "draft" ? `Draft discarded \u2014 ${request.type}/${request.name}. [seq=${result.seq}]` : `Customization overlay deleted \u2014 ${request.type}/${request.name} reset to artifact default. [seq=${result.seq}]`
         };
       } catch (err) {
         if (err instanceof ConflictError2) {
@@ -3302,7 +4185,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 = PLURAL_TO_SINGULAR2[record.type] ?? record.type;
+          const normalizedType = PLURAL_TO_SINGULAR3[record.type] ?? record.type;
           if (normalizedType === "object") {
             this.engine.registry.registerObject(data, record.packageId || "sys_metadata");
           } else {
@@ -3336,7 +4219,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
    * — the engine never throws.
    */
   async findReferencesToMeta(request) {
-    const singularTarget = PLURAL_TO_SINGULAR2[request.type] ?? request.type;
+    const singularTarget = PLURAL_TO_SINGULAR3[request.type] ?? request.type;
     const targetName = request.name;
     const matchers = REFERENCE_PATHS[singularTarget];
     if (!matchers || matchers.length === 0) {
@@ -3547,6 +4430,41 @@ _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES = (() => {
  * {@link ObjectStackProtocolImplementation.resetEnvWritableCache}.
  */
 _ObjectStackProtocolImplementation._envWritableTypes = null;
+/**
+ * Types that opt into runtime creation of brand-new items (ADR-0005
+ * extension — two-tier model). A type may have
+ * `allowOrgOverride: false` (cannot overlay artifact-shipped items)
+ * yet still set `allowRuntimeCreate: true` (users can author new
+ * items in `sys_metadata`). The two flags are orthogonal; see
+ * {@link isArtifactBacked} for how the protocol decides which gate
+ * applies to a given save/delete.
+ */
+/**
+ * Set of type names that have a static entry in
+ * `DEFAULT_METADATA_TYPE_REGISTRY`. Anything outside this set is
+ * runtime-registered (plugin-provided types like `theme`, `api`,
+ * `connector`) — the listing endpoint at `getMetaTypes()` synthesises
+ * those with `allowRuntimeCreate: true`, so this gate must agree.
+ */
+_ObjectStackProtocolImplementation.STATIC_REGISTRY_TYPES = (() => {
+  const out = /* @__PURE__ */ new Set();
+  for (const entry of DEFAULT_METADATA_TYPE_REGISTRY2) {
+    out.add(entry.type);
+    const plural = SINGULAR_TO_PLURAL2[entry.type];
+    if (plural) out.add(plural);
+  }
+  return out;
+})();
+_ObjectStackProtocolImplementation.RUNTIME_CREATE_ALLOWED_TYPES = (() => {
+  const out = /* @__PURE__ */ new Set();
+  for (const entry of DEFAULT_METADATA_TYPE_REGISTRY2) {
+    if (!entry.allowRuntimeCreate) continue;
+    out.add(entry.type);
+    const plural = SINGULAR_TO_PLURAL2[entry.type];
+    if (plural) out.add(plural);
+  }
+  return out;
+})();
 var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
 
 // src/engine.ts