@objectstack/metadata 4.0.5 → 4.1.0

package/dist/index.cjs

@@ -36,7 +36,6 @@ __export(index_exports, {
   MemoryLoader: () => MemoryLoader,
   MetadataManager: () => MetadataManager,
   MetadataPlugin: () => MetadataPlugin,
-  MetadataProjector: () => MetadataProjector,
   Migration: () => migration_exports,
   RemoteLoader: () => RemoteLoader,
   SysMetadataHistoryObject: () => import_metadata3.SysMetadataHistoryObject,
@@ -321,307 +320,113 @@ function generateDiffSummary(diff) {
   return summary.join(", ");
 }
 
-// src/projection/metadata-projector.ts
-var import_system = require("@objectstack/spec/system");
-var MetadataProjector = class {
-  constructor(options) {
-    // Map of metadata types to their target table names
-    this.typeTableMap = {
-      object: "sys_object",
-      view: "sys_view",
-      agent: "sys_agent",
-      tool: "sys_tool",
-      flow: "sys_flow"
-      // Add more as needed: dashboard, app, action, workflow, etc.
-    };
-    if (!options.driver && !options.engine) {
-      throw new Error("MetadataProjector requires either a driver or engine");
-    }
-    this.driver = options.driver;
-    this.engine = options.engine;
-    this.scope = {
-      organizationId: options.organizationId,
-      projectId: options.projectId
-    };
+// src/utils/lru-cache.ts
+var LRUCache = class {
+  constructor(options = {}) {
+    this.map = /* @__PURE__ */ new Map();
+    this.hits = 0;
+    this.misses = 0;
+    this.maxSize = options.maxSize && options.maxSize > 0 ? options.maxSize : 0;
+    this.ttl = options.ttl && options.ttl > 0 ? options.ttl : 0;
+  }
+  get(key) {
+    const entry = this.map.get(key);
+    if (!entry) {
+      this.misses++;
+      return void 0;
+    }
+    if (entry.expiresAt !== 0 && entry.expiresAt <= Date.now()) {
+      this.map.delete(key);
+      this.misses++;
+      return void 0;
+    }
+    this.map.delete(key);
+    this.map.set(key, entry);
+    this.hits++;
+    return entry.value;
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.maxSize > 0 && this.map.size >= this.maxSize) {
+      const oldest = this.map.keys().next();
+      if (!oldest.done) this.map.delete(oldest.value);
+    }
+    this.map.set(key, {
+      value,
+      expiresAt: this.ttl > 0 ? Date.now() + this.ttl : 0
+    });
   }
-  /**
-   * Project metadata to type-specific table
-   */
-  async project(type, name, data) {
-    const targetTable = this.typeTableMap[type];
-    if (!targetTable) {
-      return;
-    }
-    const projectedData = this.transformToProjection(type, name, data);
-    if (!projectedData) {
-      return;
-    }
-    try {
-      const projId = this.scope.projectId ?? null;
-      const existing = await this._findOne(targetTable, {
-        where: { name, project_id: projId }
-      });
-      if (existing) {
-        await this._update(targetTable, existing.id, projectedData);
-      } else {
-        const id = this.generateId();
-        await this._create(targetTable, {
-          id,
-          ...projectedData
-        });
-      }
-    } catch (error) {
-      console.error(`Failed to project ${type}/${name} to ${targetTable}:`, error);
-    }
+  has(key) {
+    return this.get(key) !== void 0;
   }
-  /**
-   * Delete projection from type-specific table
-   */
-  async deleteProjection(type, name) {
-    const targetTable = this.typeTableMap[type];
-    if (!targetTable) {
-      return;
-    }
-    try {
-      const projId = this.scope.projectId ?? null;
-      const existing = await this._findOne(targetTable, {
-        where: { name, project_id: projId }
-      });
-      if (existing) {
-        await this._delete(targetTable, existing.id);
-      }
-    } catch (error) {
-      console.error(`Failed to delete projection ${type}/${name} from ${targetTable}:`, error);
-    }
+  delete(key) {
+    return this.map.delete(key);
   }
-  /**
-   * Transform metadata into projection record
-   */
-  transformToProjection(type, name, data) {
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    switch (type) {
-      case "object":
-        return this.projectObject(name, data, now);
-      case "view":
-        return this.projectView(name, data, now);
-      case "agent":
-        return this.projectAgent(name, data, now);
-      case "tool":
-        return this.projectTool(name, data, now);
-      case "flow":
-        return this.projectFlow(name, data, now);
-      default:
-        return null;
-    }
+  clear() {
+    this.map.clear();
   }
-  /**
-   * Project object metadata to sys_object
-   */
-  projectObject(name, data, now) {
-    return {
-      name,
-      project_id: this.scope.projectId ?? null,
-      label: data.label || name,
-      plural_label: data.pluralLabel || data.label || name,
-      description: data.description || "",
-      icon: data.icon || "database",
-      namespace: data.namespace || "default",
-      tags: Array.isArray(data.tags) ? data.tags.join(",") : data.tags || "",
-      active: data.active !== false,
-      is_system: data.isSystem || false,
-      abstract: data.abstract || false,
-      datasource: data.datasource || "default",
-      table_name: data.name ? import_system.StorageNameMapping.resolveTableName({ name: data.name }) : name,
-      // Serialize complex structures as JSON
-      fields_json: data.fields ? JSON.stringify(data.fields) : null,
-      indexes_json: data.indexes ? JSON.stringify(data.indexes) : null,
-      validations_json: data.validations ? JSON.stringify(data.validations) : null,
-      state_machines_json: data.stateMachines ? JSON.stringify(data.stateMachines) : null,
-      capabilities_json: data.enable ? JSON.stringify(data.enable) : null,
-      // Denormalized fields
-      field_count: data.fields ? Object.keys(data.fields).length : 0,
-      display_name_field: data.displayNameField || null,
-      title_format: data.titleFormat || null,
-      compact_layout: Array.isArray(data.compactLayout) ? data.compactLayout.join(",") : data.compactLayout || null,
-      // Capabilities (denormalized for easier querying)
-      track_history: data.enable?.trackHistory || false,
-      searchable: data.enable?.searchable !== false,
-      api_enabled: data.enable?.apiEnabled !== false,
-      files: data.enable?.files || false,
-      feeds: data.enable?.feeds || false,
-      activities: data.enable?.activities || false,
-      trash: data.enable?.trash !== false,
-      mru: data.enable?.mru !== false,
-      clone: data.enable?.clone !== false,
-      // Package management
-      package_id: data.packageId || null,
-      managed_by: data.managedBy || "user",
-      // Audit
-      created_by: data.createdBy || null,
-      created_at: data.createdAt || now,
-      updated_by: data.updatedBy || null,
-      updated_at: now
-    };
+  get size() {
+    return this.map.size;
   }
-  /**
-   * Project view metadata to sys_view
-   */
-  projectView(name, data, now) {
+  /** Diagnostic counters — useful for `metrics` endpoints. */
+  stats() {
+    const total = this.hits + this.misses;
     return {
-      name,
-      project_id: this.scope.projectId ?? null,
-      label: data.label || name,
-      description: data.description || "",
-      object_name: data.object || "",
-      view_type: data.type || "grid",
-      // Serialize configurations as JSON
-      columns_json: data.columns ? JSON.stringify(data.columns) : null,
-      filters_json: data.filters ? JSON.stringify(data.filters) : null,
-      sort_json: data.sort ? JSON.stringify(data.sort) : null,
-      config_json: data.config ? JSON.stringify(data.config) : null,
-      // Display options
-      page_size: data.pageSize || 25,
-      show_search: data.showSearch !== false,
-      show_filters: data.showFilters !== false,
-      // Classification
-      namespace: data.namespace || "default",
-      // Package management
-      package_id: data.packageId || null,
-      managed_by: data.managedBy || "user",
-      // Audit
-      created_by: data.createdBy || null,
-      created_at: data.createdAt || now,
-      updated_by: data.updatedBy || null,
-      updated_at: now
+      size: this.map.size,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total === 0 ? 0 : this.hits / total
     };
   }
-  /**
-   * Project agent metadata to sys_agent
-   */
-  projectAgent(name, data, now) {
-    return {
-      name,
-      project_id: this.scope.projectId ?? null,
-      label: data.label || name,
-      description: data.description || "",
-      agent_type: data.type || "conversational",
-      // Model configuration
-      model: data.model || null,
-      temperature: data.temperature ?? 0.7,
-      max_tokens: data.maxTokens || null,
-      top_p: data.topP || null,
-      // System prompt
-      system_prompt: data.systemPrompt || null,
-      // Tools and skills as JSON
-      tools_json: data.tools ? JSON.stringify(data.tools) : null,
-      skills_json: data.skills ? JSON.stringify(data.skills) : null,
-      // Memory
-      memory_enabled: data.memoryEnabled || false,
-      memory_window: data.memoryWindow || 10,
-      // Classification
-      namespace: data.namespace || "default",
-      // Package management
-      package_id: data.packageId || null,
-      managed_by: data.managedBy || "user",
-      // Audit
-      created_by: data.createdBy || null,
-      created_at: data.createdAt || now,
-      updated_by: data.updatedBy || null,
-      updated_at: now
-    };
+  /** Resets hit/miss counters without dropping cached entries. */
+  resetStats() {
+    this.hits = 0;
+    this.misses = 0;
   }
-  /**
-   * Project tool metadata to sys_tool
-   */
-  projectTool(name, data, now) {
-    return {
-      name,
-      project_id: this.scope.projectId ?? null,
-      label: data.label || name,
-      description: data.description || "",
-      // Parameters and implementation
-      parameters_json: data.parameters ? JSON.stringify(data.parameters) : null,
-      handler_code: data.handler || null,
-      // Classification
-      namespace: data.namespace || "default",
-      // Package management
-      package_id: data.packageId || null,
-      managed_by: data.managedBy || "user",
-      // Audit
-      created_by: data.createdBy || null,
-      created_at: data.createdAt || now,
-      updated_by: data.updatedBy || null,
-      updated_at: now
-    };
-  }
-  /**
-   * Project flow metadata to sys_flow
-   */
-  projectFlow(name, data, now) {
-    return {
-      name,
-      project_id: this.scope.projectId ?? null,
-      label: data.label || name,
-      description: data.description || "",
-      flow_type: data.type || "autolaunched",
-      // Flow definition
-      nodes_json: data.nodes ? JSON.stringify(data.nodes) : null,
-      edges_json: data.edges ? JSON.stringify(data.edges) : null,
-      variables_json: data.variables ? JSON.stringify(data.variables) : null,
-      // Trigger configuration
-      trigger_type: data.triggerType || null,
-      trigger_object: data.triggerObject || null,
-      // Status
-      active: data.active || false,
-      // Classification
-      namespace: data.namespace || "default",
-      // Package management
-      package_id: data.packageId || null,
-      managed_by: data.managedBy || "user",
-      // Audit
-      created_by: data.createdBy || null,
-      created_at: data.createdAt || now,
-      updated_by: data.updatedBy || null,
-      updated_at: now
-    };
-  }
-  // ==========================================
-  // Internal CRUD helpers (driver vs engine)
-  // ==========================================
-  async _findOne(table, query) {
-    if (this.engine) {
-      return this.engine.findOne(table, query);
-    }
-    return this.driver.findOne(table, { object: table, ...query });
-  }
-  async _create(table, data) {
-    if (this.engine) {
-      return this.engine.insert(table, data);
-    }
-    return this.driver.create(table, data);
-  }
-  async _update(table, id, data) {
-    if (this.engine) {
-      return this.engine.update(table, { id, ...data });
+};
+
+// src/migrations/add-sys-metadata-overlay-index.ts
+var INDEX_NAME = "idx_sys_metadata_overlay_active";
+var TABLE = "sys_metadata";
+var COLUMNS = "(type, name, organization_id, project_id, scope)";
+var WHERE = "state = 'active'";
+async function addSysMetadataOverlayIndex(driver) {
+  const driverAny = driver;
+  const exec = async (sql) => {
+    if (typeof driverAny.raw === "function") {
+      await driverAny.raw(sql);
+    } else if (typeof driverAny.execute === "function") {
+      await driverAny.execute(sql);
+    } else {
+      throw new Error("driver has neither raw nor execute");
+    }
+  };
+  const partialSql = `CREATE UNIQUE INDEX IF NOT EXISTS ${INDEX_NAME} ON ${TABLE} ${COLUMNS} WHERE ${WHERE}`;
+  const fallbackSql = `CREATE INDEX IF NOT EXISTS ${INDEX_NAME} ON ${TABLE} ${COLUMNS}`;
+  try {
+    await exec(partialSql);
+    return { index: INDEX_NAME, status: "created" };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/partial|where clause|syntax/i.test(msg)) {
+      try {
+        await exec(fallbackSql);
+        return { index: INDEX_NAME, status: "fallback_non_unique" };
+      } catch (fallbackErr) {
+        return {
+          index: INDEX_NAME,
+          status: "error",
+          error: fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)
+        };
+      }
     }
-    return this.driver.update(table, id, data);
-  }
-  async _delete(table, id) {
-    if (this.engine) {
-      return this.engine.delete(table, { where: { id } });
+    if (/already exists/i.test(msg)) {
+      return { index: INDEX_NAME, status: "already_exists" };
     }
-    return this.driver.delete(table, id);
+    return { index: INDEX_NAME, status: "error", error: msg };
   }
-  /**
-   * Generate a simple unique ID
-   */
-  generateId() {
-    if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.randomUUID === "function") {
-      return globalThis.crypto.randomUUID();
-    }
-    return `proj_${Date.now()}_${Math.random().toString(36).substring(2, 10)}`;
-  }
-};
+}
 
 // src/loaders/database-loader.ts
 var DatabaseLoader = class {
@@ -648,17 +453,56 @@ var DatabaseLoader = class {
     this.organizationId = options.organizationId;
     this.projectId = options.projectId;
     this.trackHistory = options.trackHistory !== false;
-    this.enableProjection = options.enableProjection !== false;
-    if (this.enableProjection) {
-      this.projector = new MetadataProjector({
-        driver: this.driver,
-        engine: this.engine,
-        organizationId: this.organizationId,
-        projectId: this.projectId
-      });
+    const cacheOpts = options.cache;
+    const cacheEnabled = cacheOpts?.enabled !== false;
+    if (cacheEnabled) {
+      const lruOpts = {
+        maxSize: cacheOpts?.maxSize ?? 500,
+        ttl: cacheOpts?.ttl ?? 6e4
+      };
+      this.loadCache = new LRUCache(lruOpts);
+      this.loadManyCache = new LRUCache(lruOpts);
+      this.listCache = new LRUCache(lruOpts);
+      this.statCache = new LRUCache(lruOpts);
     }
   }
   // ==========================================
+  // Cache helpers
+  // ==========================================
+  cacheKey(type, name) {
+    return `${type}::${name}`;
+  }
+  /**
+   * Invalidate all cached entries for a specific (type, name) pair plus
+   * the type-level aggregates (`loadMany`, `list`). Called from every write
+   * path (`save`, `delete`, `registerRollback`).
+   */
+  invalidate(type, name) {
+    if (!this.loadCache) return;
+    const key = this.cacheKey(type, name);
+    this.loadCache.delete(key);
+    this.statCache?.delete(key);
+    this.loadManyCache?.delete(type);
+    this.listCache?.delete(type);
+  }
+  /** Drop the entire cache — useful after bulk imports or schema changes. */
+  invalidateAll() {
+    this.loadCache?.clear();
+    this.loadManyCache?.clear();
+    this.listCache?.clear();
+    this.statCache?.clear();
+  }
+  /** Diagnostic: aggregated cache statistics for `metrics` endpoints. */
+  getCacheStats() {
+    return {
+      enabled: this.loadCache !== void 0,
+      load: this.loadCache?.stats() ?? null,
+      loadMany: this.loadManyCache?.stats() ?? null,
+      list: this.listCache?.stats() ?? null,
+      stat: this.statCache?.stats() ?? null
+    };
+  }
+  // ==========================================
   // Internal CRUD helpers (driver vs engine)
   // ==========================================
   async _find(table, query) {
@@ -706,6 +550,23 @@ var DatabaseLoader = class {
     if (this.schemaReady) return;
     if (this.engine) {
       this.schemaReady = true;
+      try {
+        const engineAny = this.engine;
+        let driver = engineAny?.driver ?? engineAny?.getDriver?.();
+        if (!driver && engineAny?.drivers instanceof Map) {
+          for (const candidate of engineAny.drivers.values()) {
+            const c = candidate;
+            if (c && (typeof c.raw === "function" || typeof c.execute === "function")) {
+              driver = candidate;
+              break;
+            }
+          }
+        }
+        if (driver) {
+          await addSysMetadataOverlayIndex(driver);
+        }
+      } catch {
+      }
       return;
     }
     try {
@@ -714,6 +575,10 @@ var DatabaseLoader = class {
         name: this.tableName
       });
       this.schemaReady = true;
+      try {
+        await addSysMetadataOverlayIndex(this.driver);
+      } catch {
+      }
     } catch {
       this.schemaReady = true;
     }
@@ -858,11 +723,24 @@ var DatabaseLoader = class {
   async load(type, name, _options) {
     const startTime = Date.now();
     await this.ensureSchema();
+    const key = this.cacheKey(type, name);
+    if (this.loadCache) {
+      const cached = this.loadCache.get(key);
+      if (cached !== void 0) {
+        return {
+          data: cached,
+          source: "database",
+          format: "json",
+          loadTime: Date.now() - startTime
+        };
+      }
+    }
     try {
       const row = await this._findOne(this.tableName, {
         where: this.baseFilter(type, name)
       });
       if (!row) {
+        this.loadCache?.set(key, null);
         return {
           data: null,
           loadTime: Date.now() - startTime
@@ -870,6 +748,7 @@ var DatabaseLoader = class {
       }
       const data = this.rowToData(row);
       const record = this.rowToRecord(row);
+      this.loadCache?.set(key, data);
       return {
         data,
         source: "database",
@@ -886,17 +765,27 @@ var DatabaseLoader = class {
   }
   async loadMany(type, _options) {
     await this.ensureSchema();
+    if (this.loadManyCache) {
+      const cached = this.loadManyCache.get(type);
+      if (cached !== void 0) return cached;
+    }
     try {
       const rows = await this._find(this.tableName, {
         where: this.baseFilter(type)
       });
-      return rows.map((row) => this.rowToData(row)).filter((data) => data !== null);
+      const result = rows.map((row) => this.rowToData(row)).filter((data) => data !== null);
+      this.loadManyCache?.set(type, result);
+      return result;
     } catch {
       return [];
     }
   }
   async exists(type, name) {
     await this.ensureSchema();
+    if (this.loadCache) {
+      const cached = this.loadCache.get(this.cacheKey(type, name));
+      if (cached !== void 0) return cached !== null;
+    }
     try {
       const count = await this._count(this.tableName, {
         where: this.baseFilter(type, name)
@@ -908,31 +797,47 @@ var DatabaseLoader = class {
   }
   async stat(type, name) {
     await this.ensureSchema();
+    const key = this.cacheKey(type, name);
+    if (this.statCache) {
+      const cached = this.statCache.get(key);
+      if (cached !== void 0) return cached;
+    }
     try {
       const row = await this._findOne(this.tableName, {
         where: this.baseFilter(type, name)
       });
-      if (!row) return null;
+      if (!row) {
+        this.statCache?.set(key, null);
+        return null;
+      }
       const record = this.rowToRecord(row);
       const metadataStr = typeof row.metadata === "string" ? row.metadata : JSON.stringify(row.metadata);
-      return {
+      const stats = {
         size: metadataStr.length,
         mtime: record.updatedAt ?? record.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
         format: "json",
         etag: record.checksum
       };
+      this.statCache?.set(key, stats);
+      return stats;
     } catch {
       return null;
     }
   }
   async list(type) {
     await this.ensureSchema();
+    if (this.listCache) {
+      const cached = this.listCache.get(type);
+      if (cached !== void 0) return cached;
+    }
     try {
       const rows = await this._find(this.tableName, {
         where: this.baseFilter(type),
         fields: ["name"]
       });
-      return rows.map((row) => row.name).filter((name) => typeof name === "string");
+      const names = rows.map((row) => row.name).filter((name) => typeof name === "string");
+      this.listCache?.set(type, names);
+      return names;
     } catch {
       return [];
     }
@@ -1072,6 +977,7 @@ var DatabaseLoader = class {
       updated_at: now,
       state: "active"
     });
+    this.invalidate(type, name);
     await this.createHistoryRecord(
       existing.id,
       type,
@@ -1097,6 +1003,7 @@ var DatabaseLoader = class {
       if (existing) {
         const previousChecksum = existing.checksum;
         if (newChecksum === previousChecksum) {
+          this.loadCache?.set(this.cacheKey(type, name), data);
           return {
             success: true,
             path: `datasource://${this.tableName}/${type}/${name}`,
@@ -1112,6 +1019,7 @@ var DatabaseLoader = class {
           updated_at: now,
           state: "active"
         });
+        this.invalidate(type, name);
         await this.createHistoryRecord(
           existing.id,
           type,
@@ -1121,9 +1029,6 @@ var DatabaseLoader = class {
           "update",
           previousChecksum
         );
-        if (this.projector) {
-          await this.projector.project(type, name, data);
-        }
         return {
           success: true,
           path: `datasource://${this.tableName}/${type}/${name}`,
@@ -1149,6 +1054,7 @@ var DatabaseLoader = class {
           created_at: now,
           updated_at: now
         });
+        this.invalidate(type, name);
         await this.createHistoryRecord(
           id,
           type,
@@ -1157,9 +1063,6 @@ var DatabaseLoader = class {
           data,
           "create"
         );
-        if (this.projector) {
-          await this.projector.project(type, name, data);
-        }
         return {
           success: true,
           path: `datasource://${this.tableName}/${type}/${name}`,
@@ -1185,9 +1088,7 @@ var DatabaseLoader = class {
       return;
     }
     await this._delete(this.tableName, existing.id);
-    if (this.projector) {
-      await this.projector.deleteProjection(type, name);
-    }
+    this.invalidate(type, name);
   }
 };
 function generateId() {
@@ -1198,7 +1099,7 @@ function generateId() {
 }
 
 // src/metadata-manager.ts
-var MetadataManager = class {
+var _MetadataManager = class _MetadataManager {
   constructor(config) {
     this.loaders = /* @__PURE__ */ new Map();
     this.watchCallbacks = /* @__PURE__ */ new Map();
@@ -1210,6 +1111,18 @@ var MetadataManager = class {
     this.typeRegistry = [];
     // Dependency tracking: "type:name" -> dependencies
     this.dependencies = /* @__PURE__ */ new Map();
+    // Short-lived cache for list() results. Built primarily to break the
+    // deadlock that occurs when security/permission middleware calls
+    // `list('permission')` from inside a user-initiated DB transaction: the
+    // DatabaseLoader's `engine.find('sys_metadata', ...)` would then try to
+    // acquire a fresh knex connection while the transaction is still holding
+    // SQLite's single connection — knex waits the full `acquireConnectionTimeout`
+    // (60s) before returning []. The cache absorbs the repeated lookups so the
+    // loader is only hit once per TTL window.
+    //
+    // Invalidated on every `register()` / `unregister()` to keep CRUD writes
+    // visible to subsequent reads.
+    this.listCache = /* @__PURE__ */ new Map();
     this.config = config;
     this.logger = (0, import_core.createLogger)({ level: "info", format: "pretty" });
     this.serializers = /* @__PURE__ */ new Map();
@@ -1260,7 +1173,8 @@ var MetadataManager = class {
       driver,
       tableName,
       organizationId,
-      projectId
+      projectId,
+      cache: this.config.cache?.databaseLoader
     });
     this.registerLoader(dbLoader);
     this.logger.info("DatabaseLoader configured", { datasource: this.config.datasource, tableName });
@@ -1288,7 +1202,8 @@ var MetadataManager = class {
       engine,
       tableName,
       organizationId,
-      projectId
+      projectId,
+      cache: this.config.cache?.databaseLoader
     });
     this.registerLoader(dbLoader);
     this.logger.info("DatabaseLoader configured via DataEngine", { tableName });
@@ -1320,10 +1235,19 @@ var MetadataManager = class {
    * should not be written to during runtime registration.
    */
   async register(type, name, data) {
+    if (this.config.persistence?.writable === false) {
+      const msg = `MetadataManager is read-only (persistence.writable=false); refusing to register ${type}/${name}`;
+      if (this.config.validation?.throwOnError) {
+        throw new Error(msg);
+      }
+      this.logger.warn(msg);
+      return;
+    }
     if (!this.registry.has(type)) {
       this.registry.set(type, /* @__PURE__ */ new Map());
     }
     this.registry.get(type).set(name, data);
+    this.invalidateListCache(type);
     for (const loader of this.loaders.values()) {
       if (loader.save && loader.contract.protocol === "datasource:" && loader.contract.capabilities.write) {
         await loader.save(type, name, data);
@@ -1365,6 +1289,10 @@ var MetadataManager = class {
    * List all metadata items of a given type
    */
   async list(type) {
+    const cached = this.listCache.get(type);
+    if (cached && Date.now() - cached.ts < _MetadataManager.LIST_CACHE_TTL_MS) {
+      return cached.items;
+    }
     const items = /* @__PURE__ */ new Map();
     const typeStore = this.registry.get(type);
     if (typeStore) {
@@ -1385,7 +1313,16 @@ var MetadataManager = class {
         this.logger.warn(`Loader ${loader.contract.name} failed to loadMany ${type}`, { error: e });
       }
     }
-    return Array.from(items.values());
+    const result = Array.from(items.values());
+    this.cacheListResult(type, result);
+    return result;
+  }
+  cacheListResult(type, items) {
+    this.listCache.set(type, { ts: Date.now(), items });
+  }
+  /** Internal helper: drop the cached `list()` result for a type. */
+  invalidateListCache(type) {
+    this.listCache.delete(type);
   }
   /**
    * Unregister/remove a metadata item by type and name.
@@ -1399,6 +1336,7 @@ var MetadataManager = class {
         this.registry.delete(type);
       }
     }
+    this.invalidateListCache(type);
     for (const loader of this.loaders.values()) {
       if (loader.contract.protocol !== "datasource:" || !loader.contract.capabilities.write) continue;
       if (typeof loader.delete === "function") {
@@ -1813,6 +1751,14 @@ var MetadataManager = class {
    * Save/update an overlay for a metadata item
    */
   async saveOverlay(overlay) {
+    if (this.config.persistence?.overlayWritable === false) {
+      const msg = `MetadataManager overlays are read-only (persistence.overlayWritable=false); refusing to save overlay for ${overlay.baseType}/${overlay.baseName}`;
+      if (this.config.validation?.throwOnError) {
+        throw new Error(msg);
+      }
+      this.logger.warn(msg);
+      return;
+    }
     const key = this.overlayKey(overlay.baseType, overlay.baseName, overlay.scope);
     this.overlays.set(key, overlay);
   }
@@ -2282,6 +2228,8 @@ var MetadataManager = class {
     };
   }
 };
+_MetadataManager.LIST_CACHE_TTL_MS = 3e4;
+var MetadataManager = _MetadataManager;
 
 // src/plugin.ts
 var import_promises = require("fs/promises");
@@ -2773,7 +2721,10 @@ var MemoryLoader = class {
 // src/plugin.ts
 var import_kernel = require("@objectstack/spec/kernel");
 var import_metadata2 = require("@objectstack/platform-objects/metadata");
-var queryableMetadataObjects = [import_metadata2.SysObject, import_metadata2.SysView, import_metadata2.SysFlow, import_metadata2.SysAgent, import_metadata2.SysTool];
+var queryableMetadataObjects = [
+  import_metadata2.SysMetadataObject,
+  import_metadata2.SysMetadataHistoryObject
+];
 var ARTIFACT_FIELD_TO_TYPE = {
   objects: "object",
   objectExtensions: "object_extension",
@@ -2841,13 +2792,35 @@ var MetadataPlugin = class {
     };
     this.start = async (ctx) => {
       const src = this.options.artifactSource;
-      if (src?.mode === "local-file") {
-        await this._loadFromLocalFile(ctx, src.path);
-      } else if (src?.mode === "artifact-api") {
-        ctx.logger.warn("[MetadataPlugin] artifact-api source is not yet implemented; falling back to file-system scan");
-        await this._loadFromFileSystem(ctx);
+      const mode = this.options.config?.bootstrap ?? "eager";
+      ctx.logger.info("[MetadataPlugin] Bootstrapping metadata", {
+        bootstrap: mode,
+        artifactSource: src?.mode ?? "none"
+      });
+      if (mode === "artifact-only") {
+        if (src?.mode === "local-file") {
+          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
+        } else if (src?.mode === "artifact-api") {
+          await this._loadFromArtifactApi(ctx, src);
+        } else {
+          throw new Error("[MetadataPlugin] bootstrap=artifact-only requires options.artifactSource to be set");
+        }
+      } else if (mode === "lazy") {
+        if (src?.mode === "local-file") {
+          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
+        } else if (src?.mode === "artifact-api") {
+          await this._loadFromArtifactApi(ctx, src);
+        } else {
+          ctx.logger.info("[MetadataPlugin] lazy bootstrap \u2014 skipping filesystem priming; metadata loads on demand");
+        }
       } else {
-        await this._loadFromFileSystem(ctx);
+        if (src?.mode === "local-file") {
+          await this._loadFromLocalFile(ctx, src.path, src.fetchTimeoutMs);
+        } else if (src?.mode === "artifact-api") {
+          await this._loadFromArtifactApi(ctx, src);
+        } else {
+          await this._loadFromFileSystem(ctx);
+        }
       }
       try {
         const realtimeService = ctx.getService("realtime");
@@ -2866,45 +2839,46 @@ var MetadataPlugin = class {
       ...options
     };
     const rootDir = this.options.rootDir || process.cwd();
+    const bootstrapMode = this.options.config?.bootstrap ?? "eager";
+    const effectiveWatch = bootstrapMode === "artifact-only" ? false : this.options.watch ?? true;
     this.manager = new NodeMetadataManager({
       rootDir,
-      watch: this.options.watch ?? true,
+      watch: effectiveWatch,
       formats: ["yaml", "json", "typescript", "javascript"]
     });
     this.manager.setTypeRegistry(import_kernel.DEFAULT_METADATA_TYPE_REGISTRY);
   }
-  async _loadFromLocalFile(ctx, filePath) {
-    const isUrl = /^https?:\/\//i.test(filePath);
-    ctx.logger.info(
-      `[MetadataPlugin] Loading metadata from ${isUrl ? "remote URL" : "local artifact file"}`,
-      { path: filePath }
-    );
-    let raw;
+  /**
+   * Fetch JSON content from a URL with configurable timeout.
+   */
+  async _fetchJson(url, fetchTimeoutMs, token) {
+    const envTimeout = Number(process.env.OS_ARTIFACT_FETCH_TIMEOUT_MS);
+    const timeoutMs = fetchTimeoutMs ?? (Number.isFinite(envTimeout) && envTimeout > 0 ? envTimeout : void 0) ?? 6e4;
+    const controller = new AbortController();
+    const timer = timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
     try {
-      let content;
-      if (isUrl) {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 15e3);
-        try {
-          const res = await fetch(filePath, {
-            redirect: "follow",
-            signal: controller.signal,
-            headers: { Accept: "application/json, */*;q=0.5" }
-          });
-          if (!res.ok) {
-            throw new Error(`HTTP ${res.status} ${res.statusText}`);
-          }
-          content = await res.text();
-        } finally {
-          clearTimeout(timer);
-        }
-      } else {
-        content = await (0, import_promises.readFile)(filePath, "utf8");
-      }
-      raw = JSON.parse(content);
+      const headers = { Accept: "application/json, */*;q=0.5" };
+      if (token) headers.Authorization = `Bearer ${token}`;
+      const res = await fetch(url, { redirect: "follow", signal: controller.signal, headers });
+      if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+      const content = await res.text();
+      return JSON.parse(content);
     } catch (e) {
-      throw new Error(`[MetadataPlugin] Cannot read artifact ${isUrl ? "URL" : "file"} at "${filePath}": ${e.message}`);
+      if (e?.name === "AbortError") {
+        throw new Error(
+          `fetch timed out after ${timeoutMs}ms \u2014 set artifactSource.fetchTimeoutMs or OS_ARTIFACT_FETCH_TIMEOUT_MS to extend it (0 disables)`
+        );
+      }
+      throw e;
+    } finally {
+      if (timer) clearTimeout(timer);
     }
+  }
+  /**
+   * Parse raw artifact JSON (envelope or bare definition) and register all
+   * metadata items into the MetadataManager.
+   */
+  async _parseAndRegisterArtifact(ctx, raw, label) {
     const { ProjectArtifactSchema } = await import("@objectstack/spec/cloud");
     const { ObjectStackDefinitionSchema } = await import("@objectstack/spec");
     let metadata;
@@ -2912,6 +2886,9 @@ var MetadataPlugin = class {
     if (obj?.schemaVersion && obj?.commitId && obj?.metadata !== void 0) {
       const artifact = ProjectArtifactSchema.parse(obj);
       metadata = artifact.metadata;
+    } else if (obj?.success && obj?.data?.metadata) {
+      const artifact = ProjectArtifactSchema.parse(obj.data);
+      metadata = artifact.metadata;
     } else {
       const def = ObjectStackDefinitionSchema.parse(obj);
       const canonical = JSON.stringify(def, Object.keys(def).sort());
@@ -2944,10 +2921,51 @@ var MetadataPlugin = class {
       }
     }
     this.manager.registerLoader(memLoader);
-    ctx.logger.info("[MetadataPlugin] Artifact metadata loaded", {
-      path: filePath,
-      totalRegistered
-    });
+    ctx.logger.info("[MetadataPlugin] Artifact metadata loaded", { source: label, totalRegistered });
+    return totalRegistered;
+  }
+  async _loadFromLocalFile(ctx, filePath, fetchTimeoutMs) {
+    const isUrl = /^https?:\/\//i.test(filePath);
+    ctx.logger.info(
+      `[MetadataPlugin] Loading metadata from ${isUrl ? "remote URL" : "local artifact file"}`,
+      { path: filePath }
+    );
+    let raw;
+    try {
+      if (isUrl) {
+        raw = await this._fetchJson(filePath, fetchTimeoutMs);
+      } else {
+        const content = await (0, import_promises.readFile)(filePath, "utf8");
+        raw = JSON.parse(content);
+      }
+    } catch (e) {
+      throw new Error(`[MetadataPlugin] Cannot read artifact ${isUrl ? "URL" : "file"} at "${filePath}": ${e.message}`);
+    }
+    await this._parseAndRegisterArtifact(ctx, raw, filePath);
+  }
+  /**
+   * P2: Load metadata from the cloud artifact API endpoint.
+   */
+  async _loadFromArtifactApi(ctx, src) {
+    const projectId = this.options.projectId;
+    if (!projectId) {
+      throw new Error("[MetadataPlugin] artifact-api source requires options.projectId to be set");
+    }
+    let artifactUrl = src.url.replace(/\/+$/, "");
+    if (!/\/api\/v\d+\/cloud\/projects\//i.test(artifactUrl)) {
+      artifactUrl = `${artifactUrl}/api/v1/cloud/projects/${projectId}/artifact`;
+    }
+    if (src.commitId) {
+      artifactUrl += `${artifactUrl.includes("?") ? "&" : "?"}commit=${encodeURIComponent(src.commitId)}`;
+    }
+    ctx.logger.info("[MetadataPlugin] Loading metadata from artifact API", { url: artifactUrl });
+    let raw;
+    try {
+      raw = await this._fetchJson(artifactUrl, src.fetchTimeoutMs, src.token);
+    } catch (e) {
+      throw new Error(`[MetadataPlugin] Cannot load artifact from API "${artifactUrl}": ${e.message}`);
+    }
+    await this._parseAndRegisterArtifact(ctx, raw, artifactUrl);
   }
   async _loadFromFileSystem(ctx) {
     ctx.logger.info("Loading metadata from file system...");
@@ -3470,7 +3488,6 @@ var MigrationExecutor = class {
   MemoryLoader,
   MetadataManager,
   MetadataPlugin,
-  MetadataProjector,
   Migration,
   RemoteLoader,
   SysMetadataHistoryObject,