@objectstack/objectql 4.2.0 → 5.1.0

package/dist/index.js

@@ -31,6 +31,7 @@ __export(index_exports, {
   RESERVED_NAMESPACES: () => RESERVED_NAMESPACES,
   SchemaRegistry: () => SchemaRegistry,
   ScopedContext: () => ScopedContext,
+  SysMetadataRepository: () => SysMetadataRepository,
   ValidationError: () => ValidationError,
   applyInMemoryAggregation: () => applyInMemoryAggregation,
   applySystemFields: () => applySystemFields,
@@ -628,6 +629,34 @@ var SchemaRegistry = class {
   // ==========================================
   // Reset (for testing)
   // ==========================================
+  /**
+   * Invalidate the merged-schema cache for a single FQN (or short name).
+   *
+   * Call this from event-driven consumers (ADR-0008 M0 PR-7) when an
+   * upstream metadata change makes the cached merged definition stale.
+   * The contributor list is preserved — only the cached merge result is
+   * dropped, so the next `resolveObject(fqn)` recomputes from scratch.
+   *
+   * Accepts either an FQN (`acme__contact`) or a bare short name
+   * (`contact`); for the latter, all entries whose suffix matches the
+   * name are invalidated.
+   */
+  invalidate(fqnOrName) {
+    if (this.mergedObjectCache.has(fqnOrName)) {
+      this.mergedObjectCache.delete(fqnOrName);
+      return;
+    }
+    const suffix = `__${fqnOrName}`;
+    for (const fqn of Array.from(this.mergedObjectCache.keys())) {
+      if (fqn === fqnOrName || fqn.endsWith(suffix)) {
+        this.mergedObjectCache.delete(fqn);
+      }
+    }
+  }
+  /** Drop every entry from the merged-schema cache. */
+  invalidateAll() {
+    this.mergedObjectCache.clear();
+  }
   /**
    * Clear all registry state. Use only for testing.
    */
@@ -640,11 +669,518 @@ var SchemaRegistry = class {
   }
 };
 
+// src/sys-metadata-repository.ts
+var import_metadata_core = require("@objectstack/metadata-core");
+var import_kernel2 = require("@objectstack/spec/kernel");
+var OVERLAY_ALLOWED_TYPES = new Set(
+  import_kernel2.DEFAULT_METADATA_TYPE_REGISTRY.filter((e) => e.allowOrgOverride).map((e) => e.type)
+);
+var SysMetadataRepository = class {
+  constructor(opts) {
+    /**
+     * Local seq counter for in-memory watch() event broadcasts. Mirrors
+     * the durable `event_seq` we write into `sys_metadata_history` on
+     * each successful put/delete — assigned AFTER the transaction commits
+     * so we never broadcast events that got rolled back.
+     */
+    this.seqCounter = 0;
+    this.watchers = /* @__PURE__ */ new Set();
+    this.closed = false;
+    /** Table name for the durable event log. */
+    this.historyTable = "sys_metadata_history";
+    this.engine = opts.engine;
+    this.organizationId = opts.organizationId ?? null;
+    this.orgLabel = opts.orgLabel ?? (opts.organizationId ?? "system");
+  }
+  /**
+   * Run `cb` inside `engine.transaction(...)` if the engine supports it,
+   * otherwise fall through to a direct call. Matches the real
+   * `ObjectQL.transaction` semantics — in-memory drivers (and our test
+   * fakes) get no rollback, which is acceptable because production
+   * always runs on a SQL driver with real ACID.
+   */
+  async withTxn(cb) {
+    if (typeof this.engine.transaction === "function") {
+      return this.engine.transaction(cb);
+    }
+    return cb(void 0);
+  }
+  /**
+   * Read the current overlay row. Returns null if no row exists —
+   * callers (e.g. LayeredRepository) fall through to lower layers.
+   */
+  async get(ref) {
+    this.assertOpen();
+    const row = await this.engine.findOne("sys_metadata", {
+      where: this.whereFor(ref)
+    });
+    if (!row) return null;
+    return this.rowToItem(ref, row);
+  }
+  /**
+   * Resolve a historical version by content hash (ADR-0009).
+   *
+   * Looks up `sys_metadata_history` by `(organization_id, type, name,
+   * checksum)`. Returns null if no row matches. `executionPinned` types
+   * are guaranteed to find their body here because history GC skips
+   * them.
+   */
+  async getByHash(ref, hash) {
+    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,
+        checksum: hash
+      }
+    });
+    if (!row) return null;
+    const rawBody = row.metadata;
+    if (rawBody === null || rawBody === void 0) {
+      return null;
+    }
+    const body = typeof rawBody === "string" ? JSON.parse(rawBody) : rawBody;
+    return {
+      ref: { ...full, version: void 0 },
+      body,
+      hash,
+      parentHash: row.previous_checksum ?? null,
+      authoredBy: row.recorded_by ?? "unknown",
+      authoredAt: row.recorded_at ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+      message: row.change_note ?? void 0,
+      seq: row.event_seq ?? 0
+    };
+  }
+  async put(ref, spec, opts) {
+    this.assertOpen();
+    this.assertAllowed(ref.type);
+    const body = spec ?? {};
+    const hash = (0, import_metadata_core.hashSpec)(body);
+    const result = await this.withTxn(async (ctx) => {
+      const existing = await this.engine.findOne("sys_metadata", {
+        where: this.whereFor(ref),
+        context: ctx
+      });
+      const existingHash = existing?.checksum ?? null;
+      if (opts.parentVersion !== existingHash) {
+        throw new import_metadata_core.ConflictError(this.fullRef(ref), opts.parentVersion, existingHash);
+      }
+      if (existing && existingHash === hash) {
+        const item2 = this.rowToItem(ref, existing);
+        return { skipped: true, version: hash, seq: item2.seq, item: item2 };
+      }
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const op = existing ? "update" : "create";
+      const version = await this.nextItemVersion(ref, ctx);
+      const eventSeq = await this.nextEventSeq(ctx);
+      const parentRowData = {
+        type: ref.type,
+        name: ref.name,
+        organization_id: this.organizationId,
+        metadata: JSON.stringify(body),
+        checksum: hash,
+        state: "active",
+        version,
+        updated_at: now
+      };
+      if (existing) {
+        const existingId = existing.id;
+        if (existingId === void 0) {
+          throw new Error(
+            `SysMetadataRepository.put: existing row for ${ref.type}/${ref.name} has no id column`
+          );
+        }
+        await this.engine.update("sys_metadata", parentRowData, {
+          where: { id: existingId },
+          context: ctx
+        });
+      } else {
+        parentRowData.created_at = now;
+        await this.engine.insert("sys_metadata", parentRowData, { context: ctx });
+      }
+      await this.engine.insert(
+        this.historyTable,
+        {
+          id: this.uuid(),
+          event_seq: eventSeq,
+          type: ref.type,
+          name: ref.name,
+          version,
+          operation_type: op,
+          metadata: JSON.stringify(body),
+          checksum: hash,
+          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 }
+      );
+      const item = {
+        ref: this.fullRef(ref),
+        body,
+        hash,
+        parentHash: existingHash,
+        authoredBy: opts.actor,
+        authoredAt: now,
+        message: opts.message,
+        seq: eventSeq
+      };
+      return {
+        skipped: false,
+        version: hash,
+        seq: eventSeq,
+        item,
+        op,
+        existingHash,
+        now,
+        source: opts.source ?? "sys-metadata-repo",
+        message: opts.message,
+        actor: opts.actor
+      };
+    });
+    if (result.skipped) {
+      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
+    });
+    return { version: result.version, seq: result.seq, item: result.item };
+  }
+  async delete(ref, opts) {
+    this.assertOpen();
+    this.assertAllowed(ref.type);
+    const result = await this.withTxn(async (ctx) => {
+      const existing = await this.engine.findOne("sys_metadata", {
+        where: this.whereFor(ref),
+        context: ctx
+      });
+      if (!existing) {
+        throw new import_metadata_core.ConflictError(this.fullRef(ref), opts.parentVersion, null);
+      }
+      const existingHash = existing.checksum ?? null;
+      if (opts.parentVersion !== existingHash) {
+        throw new import_metadata_core.ConflictError(this.fullRef(ref), opts.parentVersion, existingHash);
+      }
+      const existingId = existing.id;
+      if (existingId === void 0) {
+        throw new Error(
+          `SysMetadataRepository.delete: existing row for ${ref.type}/${ref.name} has no id column`
+        );
+      }
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const version = await this.nextItemVersion(ref, ctx);
+      const 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 }
+      );
+      return {
+        eventSeq,
+        existingHash,
+        now,
+        source: opts.source ?? "sys-metadata-repo",
+        message: opts.message,
+        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
+    });
+    return { seq: result.eventSeq };
+  }
+  async *list(filter) {
+    this.assertOpen();
+    const where = {
+      organization_id: this.organizationId,
+      state: "active"
+    };
+    if (filter.type) where.type = filter.type;
+    const rows = await this.engine.find("sys_metadata", {
+      where,
+      limit: filter.limit
+    });
+    for (const row of rows) {
+      if (filter.nameContains && !String(row.name).includes(filter.nameContains)) continue;
+      const item = this.rowToItem(
+        { ...this.fullRef({ type: row.type, name: row.name }) },
+        row
+      );
+      const { body, ...header } = item;
+      yield header;
+    }
+  }
+  /**
+   * Yield every history event for `(org, type?, name?)` from the
+   * durable log, ordered by per-(type,name) `version` ascending. When
+   * `filter.type`/`filter.name` are unset the consumer gets the full
+   * org-scoped event stream — still ordered by version within each
+   * (type,name) bucket, then by `recorded_at` across buckets (we sort
+   * client-side because the test engine doesn't honor `orderBy`).
+   */
+  async *history(ref, opts) {
+    this.assertOpen();
+    const full = this.fullRef(ref);
+    const where = {
+      organization_id: this.organizationId,
+      type: full.type,
+      name: full.name
+    };
+    const rows = await this.engine.find(this.historyTable, { where });
+    rows.sort((a, b) => {
+      const va = typeof a.event_seq === "number" ? a.event_seq : 0;
+      const vb = typeof b.event_seq === "number" ? b.event_seq : 0;
+      return va - vb;
+    });
+    let yielded = 0;
+    for (const row of rows) {
+      if (opts?.sinceSeq !== void 0 && (row.event_seq ?? 0) <= opts.sinceSeq) continue;
+      if (opts?.limit !== void 0 && yielded >= opts.limit) break;
+      yielded++;
+      yield {
+        seq: row.event_seq ?? 0,
+        op: row.operation_type ?? "update",
+        ref: full,
+        hash: row.checksum ?? null,
+        parentHash: row.previous_checksum ?? null,
+        actor: row.recorded_by ?? "unknown",
+        message: row.change_note ?? void 0,
+        ts: row.recorded_at ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+        source: row.source ?? "sys-metadata-repo"
+      };
+    }
+  }
+  /**
+   * Live event stream. Fires for every successful put/delete on THIS
+   * instance — cross-replica fan-out is M1. Manual AsyncIterator (not
+   * an async generator) so we can deterministically tear down via
+   * `iter.return()`, matching the pattern used by InMemoryRepository.
+   */
+  watch(filter, since) {
+    const self = this;
+    return {
+      [Symbol.asyncIterator]: () => {
+        const queue = [];
+        let pendingResolve = null;
+        let stopped = false;
+        const dispatch = (evt) => {
+          if (stopped) return;
+          if (!self.matchesFilter(evt, filter)) return;
+          if (since !== void 0 && evt.seq <= since) return;
+          if (pendingResolve) {
+            const r = pendingResolve;
+            pendingResolve = null;
+            r({ value: evt, done: false });
+          } else {
+            queue.push(evt);
+          }
+        };
+        self.watchers.add(dispatch);
+        return {
+          next() {
+            if (stopped) return Promise.resolve({ value: void 0, done: true });
+            const buffered = queue.shift();
+            if (buffered) return Promise.resolve({ value: buffered, done: false });
+            return new Promise((resolve) => {
+              pendingResolve = resolve;
+            });
+          },
+          return() {
+            stopped = true;
+            self.watchers.delete(dispatch);
+            if (pendingResolve) {
+              const r = pendingResolve;
+              pendingResolve = null;
+              r({ value: void 0, done: true });
+            }
+            return Promise.resolve({ value: void 0, done: true });
+          }
+        };
+      }
+    };
+  }
+  /** Shut down all watch iterators. */
+  close() {
+    this.closed = true;
+    const snapshot = Array.from(this.watchers);
+    for (const w of snapshot) {
+      try {
+        w({
+          seq: -1,
+          op: "delete",
+          ref: { org: "", type: "view", name: "_close" },
+          hash: null,
+          parentHash: null,
+          actor: "system",
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          source: "sys-metadata-repo-close"
+        });
+      } catch {
+      }
+    }
+    this.watchers.clear();
+  }
+  // ── helpers ─────────────────────────────────────────────────────────
+  assertOpen() {
+    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;
+    }
+  }
+  whereFor(ref) {
+    return {
+      type: ref.type,
+      name: ref.name,
+      organization_id: this.organizationId,
+      state: "active"
+    };
+  }
+  fullRef(ref) {
+    return {
+      org: this.orgLabel,
+      type: ref.type,
+      name: ref.name
+    };
+  }
+  rowToItem(ref, row) {
+    const body = typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata ?? {};
+    const hash = row.checksum ?? (0, import_metadata_core.hashSpec)(body);
+    return {
+      ref: this.fullRef(ref),
+      body,
+      hash,
+      parentHash: null,
+      authoredBy: row.updated_by ?? row.created_by ?? "unknown",
+      authoredAt: row.updated_at ?? row.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+      message: void 0,
+      seq: this.seqCounter
+    };
+  }
+  broadcast(evt) {
+    for (const w of Array.from(this.watchers)) {
+      try {
+        w(evt);
+      } catch {
+      }
+    }
+  }
+  matchesFilter(evt, filter) {
+    if (filter.type && evt.ref.type !== filter.type) return false;
+    if (filter.name && evt.ref.name !== filter.name) return false;
+    if (filter.org && evt.ref.org !== filter.org) return false;
+    return true;
+  }
+  /**
+   * Per-org monotonic event sequence. Reads `MAX(event_seq) + 1` from
+   * `sys_metadata_history` scoped by `organization_id`. MUST be called
+   * inside a transaction (the only caller is the put/delete txn body) —
+   * concurrent writers in the same org race otherwise.
+   */
+  async nextEventSeq(ctx) {
+    try {
+      const rows = await this.engine.find(this.historyTable, {
+        where: { organization_id: this.organizationId },
+        context: ctx
+      });
+      let max = 0;
+      for (const row of rows) {
+        const v = typeof row.event_seq === "number" ? row.event_seq : 0;
+        if (v > max) max = v;
+      }
+      return max + 1;
+    } catch {
+      return 1;
+    }
+  }
+  /**
+   * Per-(org,type,name) lineage counter. Reads from history (not from
+   * `sys_metadata.version`) so delete + recreate continues incrementing
+   * instead of restarting at 1.
+   */
+  async nextItemVersion(ref, ctx) {
+    try {
+      const rows = await this.engine.find(this.historyTable, {
+        where: {
+          organization_id: this.organizationId,
+          type: ref.type,
+          name: ref.name
+        },
+        context: ctx
+      });
+      let max = 0;
+      for (const row of rows) {
+        const v = typeof row.version === "number" ? row.version : 0;
+        if (v > max) max = v;
+      }
+      return max + 1;
+    } catch {
+      return 1;
+    }
+  }
+  /** Lightweight UUID-ish id for history rows; sufficient for an audit log. */
+  uuid() {
+    if (typeof globalThis.crypto?.randomUUID === "function") {
+      return globalThis.crypto.randomUUID();
+    }
+    return `evt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+};
+
 // 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_ui2 = require("@objectstack/spec/ui");
-var import_kernel2 = require("@objectstack/spec/kernel");
+var import_kernel3 = require("@objectstack/spec/kernel");
 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;
@@ -706,6 +1242,13 @@ var SERVICE_CONFIG = {
 };
 var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementation {
   constructor(engine, getServicesRegistry, getFeedService, projectId) {
+    /**
+     * Lazily-instantiated SysMetadataRepository per organization. Keyed by
+     * `${organizationId ?? '__env__'}`. Repositories are stateful — they
+     * carry the per-org `seqCounter` and watch subscribers — so we cache
+     * them rather than constructing one per call.
+     */
+    this.overlayRepos = /* @__PURE__ */ new Map();
     /**
      * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
      * on `sys_metadata`. ADR-0005: scopes overlays by
@@ -721,6 +1264,24 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     this.getFeedService = getFeedService;
     this.projectId = projectId;
   }
+  /**
+   * Lazily obtain a SysMetadataRepository for the given organization.
+   * Env-wide overlays (organizationId == null) share a singleton under
+   * the `__env__` key.
+   */
+  getOverlayRepo(organizationId) {
+    const key = organizationId ?? "__env__";
+    let repo = this.overlayRepos.get(key);
+    if (!repo) {
+      repo = new SysMetadataRepository({
+        engine: this.engine,
+        organizationId,
+        orgLabel: organizationId ?? "env"
+      });
+      this.overlayRepos.set(key, repo);
+    }
+    return repo;
+  }
   async ensureOverlayIndex() {
     if (this.overlayIndexEnsured) return;
     this.overlayIndexEnsured = true;
@@ -1010,23 +1571,34 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       }
     } catch {
     }
-    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];
-        if (alt) item = this.engine.registry.getItem(alt, request.name);
-      }
-    }
     if (item === void 0) {
       try {
         const services = this.getServicesRegistry?.();
         const metadataService = services?.get("metadata");
         if (metadataService && typeof metadataService.get === "function") {
-          item = await metadataService.get(request.type, request.name);
+          const fromService = await metadataService.get(request.type, request.name);
+          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];
+            if (alt) {
+              const altFromService = await metadataService.get(alt, request.name);
+              if (altFromService !== void 0 && altFromService !== null) {
+                item = altFromService;
+              }
+            }
+          }
         }
       } catch {
       }
     }
+    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];
+        if (alt) item = this.engine.registry.getItem(alt, request.name);
+      }
+    }
     return {
       type: request.type,
       name: request.name,
@@ -1909,6 +2481,27 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     const singular = import_shared.PLURAL_TO_SINGULAR[type] ?? type;
     return _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES.has(singular) || _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES.has(type);
   }
+  /**
+   * Mirror an object-type overlay write into the in-memory engine
+   * registry so subsequent CRUD finds the new schema. Idempotent and
+   * safe to call after a successful persistence call. For the legacy
+   * write path this is invoked BEFORE persistence (historical behavior
+   * preserved); for the PR-10d.3 repository path it is invoked only
+   * AFTER `put()` resolves successfully, so a failed write — DB error,
+   * optimistic-lock conflict, validation failure — never leaks a
+   * stale schema into the registry.
+   */
+  applyObjectRegistryMutation(request) {
+    if (request.type !== "object" && request.type !== "objects") return;
+    this.engine.registry.registerItem(request.type, request.item, "name");
+    try {
+      this.engine.registry.registerObject(request.item, "sys_metadata");
+    } catch (err) {
+      console.warn(
+        `[Protocol] registerObject failed for ${request.name}: ${err?.message ?? err}`
+      );
+    }
+  }
   async saveMetaItem(request) {
     if (!request.item) {
       throw new Error("Item data is required");
@@ -1943,17 +2536,51 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
         }
       }
     }
-    if (request.type === "object" || request.type === "objects") {
-      this.engine.registry.registerItem(request.type, request.item, "name");
+    await this.ensureOverlayIndex();
+    const singularTypeForRepo = import_shared.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    if (_ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo)) {
+      const orgId = request.organizationId ?? null;
+      const repo = this.getOverlayRepo(orgId);
+      const ref = {
+        type: singularTypeForRepo,
+        name: request.name,
+        org: orgId ?? "env"
+      };
+      let parentVersion;
+      if (request.parentVersion !== void 0) {
+        parentVersion = request.parentVersion;
+      } else {
+        const current = await repo.get(ref);
+        parentVersion = current?.hash ?? null;
+      }
       try {
-        this.engine.registry.registerObject(request.item, "sys_metadata");
+        const result = await repo.put(ref, request.item, {
+          parentVersion,
+          actor: request.actor ?? "system",
+          source: "protocol.saveMetaItem"
+        });
+        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}]`
+        };
       } catch (err) {
-        console.warn(
-          `[Protocol] registerObject failed for ${request.name}: ${err?.message ?? err}`
-        );
+        if (err instanceof import_metadata_core2.ConflictError) {
+          const conflict = new Error(
+            `[metadata_conflict] ${request.type}/${request.name} has been modified since you loaded it. 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;
       }
     }
-    await this.ensureOverlayIndex();
+    this.applyObjectRegistryMutation(request);
     try {
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const orgId = request.organizationId ?? null;
@@ -2010,6 +2637,35 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       throw err;
     }
   }
+  /**
+   * Yield the durable change-log for a single metadata item — every
+   * put/delete recorded in `sys_metadata_history` for `(org, type, name)`,
+   * in event_seq order. Powers the Studio "History" tab and any
+   * client-side audit timeline.
+   *
+   * Returns `[]` for non-overlay-allowed types (the legacy raw-engine
+   * path doesn't record history) instead of throwing — callers can treat
+   * "no history" uniformly.
+   */
+  async historyMetaItem(request) {
+    const singularType = import_shared.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    if (!_ObjectStackProtocolImplementation.isOverlayAllowed(singularType)) {
+      return { events: [] };
+    }
+    const orgId = request.organizationId ?? null;
+    const repo = this.getOverlayRepo(orgId);
+    const ref = {
+      type: singularType,
+      name: request.name,
+      org: orgId ?? "env"
+    };
+    const events = [];
+    const opts = {};
+    if (request.sinceSeq !== void 0) opts.sinceSeq = request.sinceSeq;
+    if (request.limit !== void 0) opts.limit = request.limit;
+    for await (const ev of repo.history(ref, opts)) events.push(ev);
+    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
@@ -2025,6 +2681,66 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       err.status = 403;
       throw err;
     }
+    const singularTypeForRepo = import_shared.PLURAL_TO_SINGULAR[request.type] ?? request.type;
+    const useRepoPath = _ObjectStackProtocolImplementation.isOverlayAllowed(singularTypeForRepo);
+    if (useRepoPath) {
+      const orgId = request.organizationId ?? null;
+      const repo = this.getOverlayRepo(orgId);
+      const ref = {
+        type: singularTypeForRepo,
+        name: request.name,
+        org: orgId ?? "env"
+      };
+      try {
+        const current = await repo.get(ref);
+        if (!current) {
+          return {
+            success: true,
+            reset: false,
+            message: `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"
+        });
+        if (this.projectId === void 0) {
+          try {
+            const services = this.getServicesRegistry?.();
+            const metadataService = services?.get("metadata");
+            if (metadataService && typeof metadataService.get === "function") {
+              const artifactItem = await metadataService.get(request.type, request.name);
+              if (artifactItem !== void 0) {
+                this.engine.registry.registerItem(request.type, artifactItem, "name");
+              }
+            }
+          } catch {
+          }
+        }
+        return {
+          success: true,
+          reset: true,
+          seq: result.seq,
+          message: `Customization overlay deleted \u2014 ${request.type}/${request.name} reset to artifact default. [seq=${result.seq}]`
+        };
+      } catch (err) {
+        if (err instanceof import_metadata_core2.ConflictError) {
+          const conflict = new Error(
+            `[metadata_conflict] ${request.type}/${request.name} has been modified since you loaded it. 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;
+        }
+        const e = new Error(`Failed to delete customization overlay: ${err.message ?? err}`);
+        e.status = err?.status ?? 500;
+        throw e;
+      }
+    }
     const scopedWhere = {
       type: request.type,
       name: request.name,
@@ -2248,7 +2964,7 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
  */
 _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES = (() => {
   const out = /* @__PURE__ */ new Set();
-  for (const entry of import_kernel2.DEFAULT_METADATA_TYPE_REGISTRY) {
+  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];
@@ -2259,7 +2975,7 @@ _ObjectStackProtocolImplementation.OVERLAY_ALLOWED_TYPES = (() => {
 var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
 
 // src/engine.ts
-var import_kernel3 = require("@objectstack/spec/kernel");
+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");
@@ -4547,7 +5263,7 @@ var _ObjectQL = class _ObjectQL {
    */
   createContext(ctx) {
     return new ScopedContext(
-      import_kernel3.ExecutionContextSchema.parse(ctx),
+      import_kernel4.ExecutionContextSchema.parse(ctx),
       this
     );
   }
@@ -4835,6 +5551,8 @@ var ObjectQLPlugin = class {
      */
     this.startupTimeout = 12e4;
     this.skipSchemaSync = false;
+    /** Unsubscribe handles for metadata-event subscriptions (ADR-0008 PR-7). */
+    this.metadataUnsubscribes = [];
     this.init = async (ctx) => {
       if (!this.ql) {
         const hostCtx = { ...this.hostContext, logger: ctx.logger };
@@ -4881,6 +5599,9 @@ var ObjectQLPlugin = class {
         if (metadataService && typeof metadataService.loadMany === "function" && this.ql) {
           await this.loadMetadataFromService(metadataService, ctx);
         }
+        if (metadataService && typeof metadataService.subscribe === "function" && this.ql) {
+          this.subscribeToMetadataEvents(metadataService, ctx);
+        }
       } catch (e) {
         ctx.logger.debug("No external metadata service to sync from");
       }
@@ -4934,6 +5655,16 @@ var ObjectQLPlugin = class {
         objectsRegistered: this.ql?.registry?.getAllObjects?.()?.length || 0
       });
     };
+    this.stop = async (ctx) => {
+      for (const unsub of this.metadataUnsubscribes) {
+        try {
+          unsub();
+        } catch (e) {
+          ctx.logger.debug("[ObjectQLPlugin] metadata-event unsubscribe failed", { error: e?.message });
+        }
+      }
+      this.metadataUnsubscribes = [];
+    };
     if (qlOrOptions instanceof ObjectQL) {
       this.ql = qlOrOptions;
       this.hostContext = hostContext;
@@ -4950,6 +5681,62 @@ var ObjectQLPlugin = class {
     }
     this.skipSchemaSync = typeof opts.skipSchemaSync === "boolean" ? opts.skipSchemaSync : process.env.OS_SKIP_SCHEMA_SYNC === "1";
   }
+  /**
+   * Subscribe to `object` metadata events from the metadata service and
+   * invalidate the SchemaRegistry merge cache on each event (ADR-0008
+   * PR-7). For create/update we also re-load the affected object from
+   * the metadata service so subsequent reads see the new definition;
+   * for delete we unregister it from every contributing package.
+   *
+   * Events are filtered to the canonical `object` type — view/dashboard
+   * /flow edits go through their own consumers (Studio SSE, REST cache).
+   *
+   * Stored unsubscribe handle is invoked from {@link stop}.
+   */
+  subscribeToMetadataEvents(metadataService, ctx) {
+    const handler = async (evt) => {
+      if (!this.ql) return;
+      const name = evt?.name ?? "";
+      if (!name) return;
+      const eventType = evt?.type === "added" || evt?.type === "changed" || evt?.type === "deleted" ? evt.type : "changed";
+      try {
+        this.ql.registry.invalidate(name);
+        if (eventType === "deleted") {
+          ctx.logger.info("[ObjectQLPlugin] object metadata deleted \u2014 registry invalidated", { name });
+          return;
+        }
+        const fresh = typeof metadataService.get === "function" ? await metadataService.get("object", name) : void 0;
+        if (fresh && typeof fresh === "object") {
+          const packageId = fresh._packageId ?? "metadata-service";
+          const namespace = fresh.namespace;
+          this.ql.registry.registerObject(
+            fresh,
+            packageId,
+            namespace,
+            "own"
+          );
+          ctx.logger.info("[ObjectQLPlugin] object metadata updated \u2014 registry refreshed", {
+            name,
+            packageId
+          });
+        } else {
+          ctx.logger.debug("[ObjectQLPlugin] object event received but metadata service has no fresh body", { name });
+        }
+      } catch (e) {
+        ctx.logger.warn("[ObjectQLPlugin] metadata event handler failed", {
+          name,
+          error: e?.message
+        });
+      }
+    };
+    const unsub = metadataService.subscribe("object", handler);
+    if (typeof unsub === "function") {
+      this.metadataUnsubscribes.push(unsub);
+    } else if (unsub && typeof unsub.unsubscribe === "function") {
+      this.metadataUnsubscribes.push(() => unsub.unsubscribe());
+    }
+    ctx.logger.info("[ObjectQLPlugin] subscribed to object metadata events (ADR-0008 PR-7)");
+  }
   /**
    * Register built-in audit hooks for auto-stamping created_by/updated_by
    * and fetching previousData for update/delete operations. These are
@@ -5448,6 +6235,7 @@ function convertIntrospectedSchemaToObjects(introspectedSchema, options) {
   RESERVED_NAMESPACES,
   SchemaRegistry,
   ScopedContext,
+  SysMetadataRepository,
   ValidationError,
   applyInMemoryAggregation,
   applySystemFields,