@objectstack/metadata 4.0.4 → 4.1.0

package/dist/node.js

@@ -174,277 +174,8 @@ export default metadata;
   }
 };
 
-// src/objects/sys-metadata.object.ts
-import { ObjectSchema, Field } from "@objectstack/spec/data";
-var SysMetadataObject = ObjectSchema.create({
-  namespace: "sys",
-  name: "metadata",
-  label: "System Metadata",
-  pluralLabel: "System Metadata",
-  icon: "settings",
-  isSystem: true,
-  description: "Stores platform and user-scope metadata records (objects, views, flows, etc.)",
-  fields: {
-    /** Primary Key (UUID) */
-    id: Field.text({
-      label: "ID",
-      required: true,
-      readonly: true
-    }),
-    /** Machine name — unique identifier used in code references */
-    name: Field.text({
-      label: "Name",
-      required: true,
-      searchable: true,
-      maxLength: 255
-    }),
-    /** Metadata type (e.g. "object", "view", "flow") */
-    type: Field.text({
-      label: "Metadata Type",
-      required: true,
-      searchable: true,
-      maxLength: 100
-    }),
-    /** Namespace / module grouping (e.g. "crm", "core") */
-    namespace: Field.text({
-      label: "Namespace",
-      required: false,
-      defaultValue: "default",
-      maxLength: 100
-    }),
-    /** Package that owns/delivered this metadata */
-    package_id: Field.text({
-      label: "Package ID",
-      required: false,
-      maxLength: 255
-    }),
-    /** Who manages this record: package, platform, or user */
-    managed_by: Field.select(["package", "platform", "user"], {
-      label: "Managed By",
-      required: false
-    }),
-    /** Scope: system (code), platform (admin DB), user (personal DB) */
-    scope: Field.select(["system", "platform", "user"], {
-      label: "Scope",
-      required: true,
-      defaultValue: "platform"
-    }),
-    /** JSON payload — the actual metadata configuration */
-    metadata: Field.textarea({
-      label: "Metadata",
-      required: true,
-      description: "JSON-serialized metadata payload"
-    }),
-    /** Parent metadata name for extension/override */
-    extends: Field.text({
-      label: "Extends",
-      required: false,
-      maxLength: 255
-    }),
-    /** Merge strategy when extending parent metadata */
-    strategy: Field.select(["merge", "replace"], {
-      label: "Strategy",
-      required: false,
-      defaultValue: "merge"
-    }),
-    /** Owner user ID (for user-scope items) */
-    owner: Field.text({
-      label: "Owner",
-      required: false,
-      maxLength: 255
-    }),
-    /** Lifecycle state */
-    state: Field.select(["draft", "active", "archived", "deprecated"], {
-      label: "State",
-      required: false,
-      defaultValue: "active"
-    }),
-    /** Tenant ID for multi-tenant isolation */
-    tenant_id: Field.text({
-      label: "Tenant ID",
-      required: false,
-      maxLength: 255
-    }),
-    /** Version number for optimistic concurrency */
-    version: Field.number({
-      label: "Version",
-      required: false,
-      defaultValue: 1
-    }),
-    /** Content checksum for change detection */
-    checksum: Field.text({
-      label: "Checksum",
-      required: false,
-      maxLength: 64
-    }),
-    /** Origin of this metadata record */
-    source: Field.select(["filesystem", "database", "api", "migration"], {
-      label: "Source",
-      required: false
-    }),
-    /** Classification tags (JSON array) */
-    tags: Field.textarea({
-      label: "Tags",
-      required: false,
-      description: "JSON-serialized array of classification tags"
-    }),
-    /** Audit fields */
-    created_by: Field.text({
-      label: "Created By",
-      required: false,
-      readonly: true,
-      maxLength: 255
-    }),
-    created_at: Field.datetime({
-      label: "Created At",
-      required: false,
-      readonly: true
-    }),
-    updated_by: Field.text({
-      label: "Updated By",
-      required: false,
-      maxLength: 255
-    }),
-    updated_at: Field.datetime({
-      label: "Updated At",
-      required: false
-    })
-  },
-  indexes: [
-    { fields: ["type", "name"], unique: true },
-    { fields: ["type", "scope"] },
-    { fields: ["tenant_id"] },
-    { fields: ["state"] },
-    { fields: ["namespace"] }
-  ],
-  enable: {
-    trackHistory: true,
-    searchable: false,
-    apiEnabled: true,
-    apiMethods: ["get", "list", "create", "update", "delete"],
-    trash: false
-  }
-});
-
-// src/objects/sys-metadata-history.object.ts
-import { ObjectSchema as ObjectSchema2, Field as Field2 } from "@objectstack/spec/data";
-var SysMetadataHistoryObject = ObjectSchema2.create({
-  namespace: "sys",
-  name: "metadata_history",
-  label: "Metadata History",
-  pluralLabel: "Metadata History",
-  icon: "history",
-  isSystem: true,
-  description: "Version history and audit trail for metadata changes",
-  fields: {
-    /** Primary Key (UUID) */
-    id: Field2.text({
-      label: "ID",
-      required: true,
-      readonly: true
-    }),
-    /** Foreign key to sys_metadata.id */
-    metadata_id: Field2.text({
-      label: "Metadata ID",
-      required: true,
-      readonly: true,
-      maxLength: 255
-    }),
-    /** Machine name (denormalized for easier querying) */
-    name: Field2.text({
-      label: "Name",
-      required: true,
-      searchable: true,
-      readonly: true,
-      maxLength: 255
-    }),
-    /** Metadata type (denormalized for easier querying) */
-    type: Field2.text({
-      label: "Metadata Type",
-      required: true,
-      searchable: true,
-      readonly: true,
-      maxLength: 100
-    }),
-    /** Version number at this snapshot */
-    version: Field2.number({
-      label: "Version",
-      required: true,
-      readonly: true
-    }),
-    /** Type of operation that created this history entry */
-    operation_type: Field2.select(["create", "update", "publish", "revert", "delete"], {
-      label: "Operation Type",
-      required: true,
-      readonly: true
-    }),
-    /** Historical metadata snapshot (JSON payload) */
-    metadata: Field2.textarea({
-      label: "Metadata",
-      required: true,
-      readonly: true,
-      description: "JSON-serialized metadata snapshot at this version"
-    }),
-    /** SHA-256 checksum of metadata content */
-    checksum: Field2.text({
-      label: "Checksum",
-      required: true,
-      readonly: true,
-      maxLength: 64
-    }),
-    /** Checksum of the previous version */
-    previous_checksum: Field2.text({
-      label: "Previous Checksum",
-      required: false,
-      readonly: true,
-      maxLength: 64
-    }),
-    /** Human-readable description of changes */
-    change_note: Field2.textarea({
-      label: "Change Note",
-      required: false,
-      readonly: true,
-      description: "Description of what changed in this version"
-    }),
-    /** Tenant ID for multi-tenant isolation */
-    tenant_id: Field2.text({
-      label: "Tenant ID",
-      required: false,
-      readonly: true,
-      maxLength: 255
-    }),
-    /** User who made this change */
-    recorded_by: Field2.text({
-      label: "Recorded By",
-      required: false,
-      readonly: true,
-      maxLength: 255
-    }),
-    /** When was this version recorded */
-    recorded_at: Field2.datetime({
-      label: "Recorded At",
-      required: true,
-      readonly: true
-    })
-  },
-  indexes: [
-    { fields: ["metadata_id", "version"], unique: true },
-    { fields: ["metadata_id", "recorded_at"] },
-    { fields: ["type", "name"] },
-    { fields: ["recorded_at"] },
-    { fields: ["operation_type"] },
-    { fields: ["tenant_id"] }
-  ],
-  enable: {
-    trackHistory: false,
-    // Don't track history of history records
-    searchable: false,
-    apiEnabled: true,
-    apiMethods: ["get", "list"],
-    // Read-only via API
-    trash: false
-  }
-});
+// src/loaders/database-loader.ts
+import { SysMetadataObject, SysMetadataHistoryObject } from "@objectstack/platform-objects/metadata";
 
 // src/utils/metadata-history-utils.ts
 async function calculateChecksum(metadata) {
@@ -544,6 +275,114 @@ function generateDiffSummary(diff) {
   return summary.join(", ");
 }
 
+// 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
+    });
+  }
+  has(key) {
+    return this.get(key) !== void 0;
+  }
+  delete(key) {
+    return this.map.delete(key);
+  }
+  clear() {
+    this.map.clear();
+  }
+  get size() {
+    return this.map.size;
+  }
+  /** Diagnostic counters — useful for `metrics` endpoints. */
+  stats() {
+    const total = this.hits + this.misses;
+    return {
+      size: this.map.size,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total === 0 ? 0 : this.hits / total
+    };
+  }
+  /** Resets hit/miss counters without dropping cached entries. */
+  resetStats() {
+    this.hits = 0;
+    this.misses = 0;
+  }
+};
+
+// 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)
+        };
+      }
+    }
+    if (/already exists/i.test(msg)) {
+      return { index: INDEX_NAME, status: "already_exists" };
+    }
+    return { index: INDEX_NAME, status: "error", error: msg };
+  }
+}
+
 // src/loaders/database-loader.ts
 var DatabaseLoader = class {
   constructor(options) {
@@ -559,11 +398,103 @@ var DatabaseLoader = class {
     };
     this.schemaReady = false;
     this.historySchemaReady = false;
+    if (!options.driver && !options.engine) {
+      throw new Error("DatabaseLoader requires either a driver or engine");
+    }
     this.driver = options.driver;
+    this.engine = options.engine;
     this.tableName = options.tableName ?? "sys_metadata";
     this.historyTableName = options.historyTableName ?? "sys_metadata_history";
-    this.tenantId = options.tenantId;
+    this.organizationId = options.organizationId;
+    this.projectId = options.projectId;
     this.trackHistory = options.trackHistory !== false;
+    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) {
+    if (this.engine) {
+      return this.engine.find(table, query);
+    }
+    return this.driver.find(table, { object: table, ...query });
+  }
+  async _findOne(table, query) {
+    if (this.engine) {
+      return this.engine.findOne(table, query);
+    }
+    return this.driver.findOne(table, { object: table, ...query });
+  }
+  async _count(table, query) {
+    if (this.engine) {
+      return this.engine.count(table, query);
+    }
+    return this.driver.count(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 });
+    }
+    return this.driver.update(table, id, data);
+  }
+  async _delete(table, id) {
+    if (this.engine) {
+      return this.engine.delete(table, { where: { id } });
+    }
+    return this.driver.delete(table, id);
   }
   /**
    * Ensure the metadata table exists.
@@ -572,12 +503,37 @@ var DatabaseLoader = class {
    */
   async ensureSchema() {
     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 {
       await this.driver.syncSchema(this.tableName, {
         ...SysMetadataObject,
         name: this.tableName
       });
       this.schemaReady = true;
+      try {
+        await addSysMetadataOverlayIndex(this.driver);
+      } catch {
+      }
     } catch {
       this.schemaReady = true;
     }
@@ -588,6 +544,10 @@ var DatabaseLoader = class {
    */
   async ensureHistorySchema() {
     if (!this.trackHistory || this.historySchemaReady) return;
+    if (this.engine) {
+      this.historySchemaReady = true;
+      return;
+    }
     try {
       await this.driver.syncSchema(this.historyTableName, {
         ...SysMetadataHistoryObject,
@@ -600,16 +560,18 @@ var DatabaseLoader = class {
   }
   /**
    * Build base filter conditions for queries.
-   * Always includes tenantId when configured.
+   * Filters by organizationId when configured; project_id when projectId is set,
+   * or null (platform-global) when not set.
    */
   baseFilter(type, name) {
     const filter = { type };
     if (name !== void 0) {
       filter.name = name;
     }
-    if (this.tenantId) {
-      filter.tenant_id = this.tenantId;
+    if (this.organizationId) {
+      filter.organization_id = this.organizationId;
     }
+    filter.project_id = this.projectId ?? null;
     return filter;
   }
   /**
@@ -648,10 +610,11 @@ var DatabaseLoader = class {
       changeNote,
       recordedBy,
       recordedAt: now,
-      ...this.tenantId ? { tenantId: this.tenantId } : {}
+      ...this.organizationId ? { organizationId: this.organizationId } : {},
+      ...this.projectId !== void 0 ? { projectId: this.projectId } : {}
     };
     try {
-      await this.driver.create(this.historyTableName, {
+      await this._create(this.historyTableName, {
         id: historyRecord.id,
         metadata_id: historyRecord.metadataId,
         name: historyRecord.name,
@@ -664,7 +627,8 @@ var DatabaseLoader = class {
         change_note: historyRecord.changeNote,
         recorded_by: historyRecord.recordedBy,
         recorded_at: historyRecord.recordedAt,
-        ...this.tenantId ? { tenant_id: this.tenantId } : {}
+        ...this.organizationId ? { organization_id: this.organizationId } : {},
+        ...this.projectId !== void 0 ? { project_id: this.projectId } : {}
       });
     } catch (error) {
       console.error(`Failed to create history record for ${type}/${name}:`, error);
@@ -696,7 +660,8 @@ var DatabaseLoader = class {
       strategy: row.strategy ?? "merge",
       owner: row.owner,
       state: row.state ?? "active",
-      tenantId: row.tenant_id,
+      organizationId: row.organization_id,
+      projectId: row.project_id,
       version: row.version ?? 1,
       checksum: row.checksum,
       source: row.source,
@@ -713,12 +678,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.driver.findOne(this.tableName, {
-        object: this.tableName,
+      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
@@ -726,6 +703,7 @@ var DatabaseLoader = class {
       }
       const data = this.rowToData(row);
       const record = this.rowToRecord(row);
+      this.loadCache?.set(key, data);
       return {
         data,
         source: "database",
@@ -742,21 +720,29 @@ 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.driver.find(this.tableName, {
-        object: this.tableName,
+      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.driver.count(this.tableName, {
-        object: this.tableName,
+      const count = await this._count(this.tableName, {
         where: this.baseFilter(type, name)
       });
       return count > 0;
@@ -766,33 +752,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.driver.findOne(this.tableName, {
-        object: this.tableName,
+      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.driver.find(this.tableName, {
-        object: this.tableName,
+      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 [];
     }
@@ -804,8 +804,7 @@ var DatabaseLoader = class {
   async getHistoryRecord(type, name, version) {
     if (!this.trackHistory) return null;
     await this.ensureHistorySchema();
-    const metadataRow = await this.driver.findOne(this.tableName, {
-      object: this.tableName,
+    const metadataRow = await this._findOne(this.tableName, {
       where: this.baseFilter(type, name)
     });
     if (!metadataRow) return null;
@@ -813,11 +812,11 @@ var DatabaseLoader = class {
       metadata_id: metadataRow.id,
       version
     };
-    if (this.tenantId) {
-      filter.tenant_id = this.tenantId;
+    if (this.organizationId) {
+      filter.organization_id = this.organizationId;
     }
-    const row = await this.driver.findOne(this.historyTableName, {
-      object: this.historyTableName,
+    filter.project_id = this.projectId ?? null;
+    const row = await this._findOne(this.historyTableName, {
       where: filter
     });
     if (!row) return null;
@@ -832,11 +831,80 @@ var DatabaseLoader = class {
       checksum: row.checksum,
       previousChecksum: row.previous_checksum,
       changeNote: row.change_note,
-      tenantId: row.tenant_id,
+      organizationId: row.organization_id,
+      projectId: row.project_id,
       recordedBy: row.recorded_by,
       recordedAt: row.recorded_at
     };
   }
+  /**
+   * Query history records with pagination and filtering.
+   * Encapsulates history table queries so MetadataManager doesn't need
+   * direct driver access.
+   */
+  async queryHistory(type, name, options) {
+    if (!this.trackHistory) {
+      return { records: [], total: 0, hasMore: false };
+    }
+    await this.ensureSchema();
+    await this.ensureHistorySchema();
+    const filter = { type, name };
+    if (this.organizationId) filter.organization_id = this.organizationId;
+    filter.project_id = this.projectId ?? null;
+    const metadataRecord = await this._findOne(this.tableName, { where: filter });
+    if (!metadataRecord) {
+      return { records: [], total: 0, hasMore: false };
+    }
+    const historyFilter = {
+      metadata_id: metadataRecord.id
+    };
+    if (this.organizationId) historyFilter.organization_id = this.organizationId;
+    historyFilter.project_id = this.projectId ?? null;
+    if (options?.operationType) historyFilter.operation_type = options.operationType;
+    if (options?.since) historyFilter.recorded_at = { $gte: options.since };
+    if (options?.until) {
+      if (historyFilter.recorded_at) {
+        historyFilter.recorded_at.$lte = options.until;
+      } else {
+        historyFilter.recorded_at = { $lte: options.until };
+      }
+    }
+    const limit = options?.limit ?? 50;
+    const offset = options?.offset ?? 0;
+    const historyRecords = await this._find(this.historyTableName, {
+      where: historyFilter,
+      orderBy: [
+        { field: "recorded_at", order: "desc" },
+        { field: "version", order: "desc" }
+      ],
+      limit: limit + 1,
+      offset
+    });
+    const hasMore = historyRecords.length > limit;
+    const records = historyRecords.slice(0, limit);
+    const total = await this._count(this.historyTableName, { where: historyFilter });
+    const includeMetadata = options?.includeMetadata !== false;
+    const result = records.map((row) => {
+      const parsedMetadata = typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata;
+      return {
+        id: row.id,
+        metadataId: row.metadata_id,
+        name: row.name,
+        type: row.type,
+        version: row.version,
+        operationType: row.operation_type,
+        metadata: includeMetadata ? parsedMetadata : null,
+        checksum: row.checksum,
+        previousChecksum: row.previous_checksum,
+        changeNote: row.change_note,
+        organizationId: row.organization_id,
+        projectId: row.project_id,
+        recordedBy: row.recorded_by,
+        recordedAt: row.recorded_at
+      };
+    });
+    return { records: result, total, hasMore };
+  }
   /**
    * Perform a rollback: persist `restoredData` as the new current state and record a
    * single 'revert' history entry (instead of the usual 'update' entry that `save()`
@@ -849,8 +917,7 @@ var DatabaseLoader = class {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const metadataJson = JSON.stringify(restoredData);
     const newChecksum = await calculateChecksum(restoredData);
-    const existing = await this.driver.findOne(this.tableName, {
-      object: this.tableName,
+    const existing = await this._findOne(this.tableName, {
       where: this.baseFilter(type, name)
     });
     if (!existing) {
@@ -858,13 +925,14 @@ var DatabaseLoader = class {
     }
     const previousChecksum = existing.checksum;
     const newVersion = (existing.version ?? 0) + 1;
-    await this.driver.update(this.tableName, existing.id, {
+    await this._update(this.tableName, existing.id, {
       metadata: metadataJson,
       version: newVersion,
       checksum: newChecksum,
       updated_at: now,
       state: "active"
     });
+    this.invalidate(type, name);
     await this.createHistoryRecord(
       existing.id,
       type,
@@ -884,13 +952,13 @@ var DatabaseLoader = class {
     const metadataJson = JSON.stringify(data);
     const newChecksum = await calculateChecksum(data);
     try {
-      const existing = await this.driver.findOne(this.tableName, {
-        object: this.tableName,
+      const existing = await this._findOne(this.tableName, {
         where: this.baseFilter(type, name)
       });
       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}`,
@@ -899,13 +967,14 @@ var DatabaseLoader = class {
           };
         }
         const version = (existing.version ?? 0) + 1;
-        await this.driver.update(this.tableName, existing.id, {
+        await this._update(this.tableName, existing.id, {
           metadata: metadataJson,
           version,
           checksum: newChecksum,
           updated_at: now,
           state: "active"
         });
+        this.invalidate(type, name);
         await this.createHistoryRecord(
           existing.id,
           type,
@@ -923,7 +992,7 @@ var DatabaseLoader = class {
         };
       } else {
         const id = generateId();
-        await this.driver.create(this.tableName, {
+        await this._create(this.tableName, {
           id,
           name,
           type,
@@ -935,10 +1004,12 @@ var DatabaseLoader = class {
           state: "active",
           version: 1,
           source: "database",
-          ...this.tenantId ? { tenant_id: this.tenantId } : {},
+          ...this.organizationId ? { organization_id: this.organizationId } : {},
+          ...this.projectId !== void 0 ? { project_id: this.projectId } : { project_id: null },
           created_at: now,
           updated_at: now
         });
+        this.invalidate(type, name);
         await this.createHistoryRecord(
           id,
           type,
@@ -965,14 +1036,14 @@ var DatabaseLoader = class {
    */
   async delete(type, name) {
     await this.ensureSchema();
-    const existing = await this.driver.findOne(this.tableName, {
-      object: this.tableName,
+    const existing = await this._findOne(this.tableName, {
       where: this.baseFilter(type, name)
     });
     if (!existing) {
       return;
     }
-    await this.driver.delete(this.tableName, existing.id);
+    await this._delete(this.tableName, existing.id);
+    this.invalidate(type, name);
   }
 };
 function generateId() {
@@ -983,7 +1054,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();
@@ -995,6 +1066,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 = createLogger({ level: "info", format: "pretty" });
     this.serializers = /* @__PURE__ */ new Map();
@@ -1029,16 +1112,57 @@ var MetadataManager = class {
    * Can be called at any time to enable database storage (e.g. after kernel resolves the driver).
    *
    * @param driver - An IDataDriver instance for database operations
-   */
-  setDatabaseDriver(driver) {
+   * @param organizationId - Organization ID for multi-tenant isolation
+   * @param projectId - Project ID (undefined = platform-global)
+   */
+  setDatabaseDriver(driver, organizationId, projectId) {
+    if (projectId !== void 0) {
+      this.logger.info("Project kernel \u2014 skipping DatabaseLoader for sys_metadata (control-plane only)", {
+        organizationId,
+        projectId
+      });
+      return;
+    }
     const tableName = this.config.tableName ?? "sys_metadata";
     const dbLoader = new DatabaseLoader({
       driver,
-      tableName
+      tableName,
+      organizationId,
+      projectId,
+      cache: this.config.cache?.databaseLoader
     });
     this.registerLoader(dbLoader);
     this.logger.info("DatabaseLoader configured", { datasource: this.config.datasource, tableName });
   }
+  /**
+   * Configure and register a DatabaseLoader backed by an IDataEngine (ObjectQL).
+   * The engine handles datasource routing automatically — sys_metadata will
+   * be routed to the correct driver via the standard namespace mapping.
+   * No manual driver resolution needed.
+   *
+   * @param engine - An IDataEngine instance (typically the ObjectQL service)
+   * @param organizationId - Organization ID for multi-tenant isolation
+   * @param projectId - Project ID (undefined = platform-global)
+   */
+  setDataEngine(engine, organizationId, projectId) {
+    if (projectId !== void 0) {
+      this.logger.info("Project kernel \u2014 skipping DatabaseLoader for sys_metadata (control-plane only)", {
+        organizationId,
+        projectId
+      });
+      return;
+    }
+    const tableName = this.config.tableName ?? "sys_metadata";
+    const dbLoader = new DatabaseLoader({
+      engine,
+      tableName,
+      organizationId,
+      projectId,
+      cache: this.config.cache?.databaseLoader
+    });
+    this.registerLoader(dbLoader);
+    this.logger.info("DatabaseLoader configured via DataEngine", { tableName });
+  }
   /**
    * Set the realtime service for publishing metadata change events.
    * Should be called after kernel resolves the realtime service.
@@ -1066,10 +1190,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);
@@ -1111,6 +1244,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) {
@@ -1131,7 +1268,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.
@@ -1145,6 +1291,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") {
@@ -1559,6 +1706,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);
   }
@@ -1952,84 +2107,14 @@ var MetadataManager = class {
     if (!dbLoader) {
       throw new Error("History tracking requires a database loader to be configured");
     }
-    const driver = dbLoader.driver;
-    const tableName = dbLoader.tableName;
-    const historyTableName = dbLoader.historyTableName;
-    const tenantId = dbLoader.tenantId;
-    const filter = { type, name };
-    if (tenantId) {
-      filter.tenant_id = tenantId;
-    }
-    const metadataRecord = await driver.findOne(tableName, {
-      object: tableName,
-      where: filter
-    });
-    if (!metadataRecord) {
-      return {
-        records: [],
-        total: 0,
-        hasMore: false
-      };
-    }
-    const historyFilter = {
-      metadata_id: metadataRecord.id
-    };
-    if (tenantId) {
-      historyFilter.tenant_id = tenantId;
-    }
-    if (options?.operationType) {
-      historyFilter.operation_type = options.operationType;
-    }
-    if (options?.since) {
-      historyFilter.recorded_at = { $gte: options.since };
-    }
-    if (options?.until) {
-      if (historyFilter.recorded_at) {
-        historyFilter.recorded_at.$lte = options.until;
-      } else {
-        historyFilter.recorded_at = { $lte: options.until };
-      }
-    }
-    const limit = options?.limit ?? 50;
-    const offset = options?.offset ?? 0;
-    const historyRecords = await driver.find(historyTableName, {
-      object: historyTableName,
-      where: historyFilter,
-      orderBy: [{ field: "recorded_at", order: "desc" }],
-      limit: limit + 1,
-      // Fetch one extra to determine hasMore
-      offset
-    });
-    const hasMore = historyRecords.length > limit;
-    const records = historyRecords.slice(0, limit);
-    const total = await driver.count(historyTableName, {
-      object: historyTableName,
-      where: historyFilter
-    });
-    const includeMetadata = options?.includeMetadata !== false;
-    const historyResult = records.map((row) => {
-      const parsedMetadata = typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata;
-      return {
-        id: row.id,
-        metadataId: row.metadata_id,
-        name: row.name,
-        type: row.type,
-        version: row.version,
-        operationType: row.operation_type,
-        metadata: includeMetadata ? parsedMetadata : null,
-        checksum: row.checksum,
-        previousChecksum: row.previous_checksum,
-        changeNote: row.change_note,
-        tenantId: row.tenant_id,
-        recordedBy: row.recorded_by,
-        recordedAt: row.recorded_at
-      };
+    return dbLoader.queryHistory(type, name, {
+      operationType: options?.operationType,
+      since: options?.since,
+      until: options?.until,
+      limit: options?.limit,
+      offset: options?.offset,
+      includeMetadata: options?.includeMetadata
     });
-    return {
-      records: historyResult,
-      total,
-      hasMore
-    };
   }
   /**
    * Rollback a metadata item to a specific version.
@@ -2098,6 +2183,12 @@ var MetadataManager = class {
     };
   }
 };
+_MetadataManager.LIST_CACHE_TTL_MS = 3e4;
+var MetadataManager = _MetadataManager;
+
+// src/plugin.ts
+import { readFile as readFile2 } from "fs/promises";
+import { createHash as createHash2 } from "crypto";
 
 // src/node-metadata-manager.ts
 import * as path2 from "path";
@@ -2215,7 +2306,7 @@ var FilesystemLoader = class {
       );
       for (const pattern of globPatterns) {
         const files = await glob(pattern, {
-          ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*"],
+          ignore: ["**/node_modules/**", "**/*.test.*", "**/*.spec.*", "**/*[*]*"],
           nodir: true
         });
         for (const file of files) {
@@ -2504,124 +2595,6 @@ var NodeMetadataManager = class extends MetadataManager {
   }
 };
 
-// src/plugin.ts
-import { DEFAULT_METADATA_TYPE_REGISTRY } from "@objectstack/spec/kernel";
-var MetadataPlugin = class {
-  constructor(options = {}) {
-    this.name = "com.objectstack.metadata";
-    this.type = "standard";
-    this.version = "1.0.0";
-    this.init = async (ctx) => {
-      ctx.logger.info("Initializing Metadata Manager", {
-        root: this.options.rootDir || process.cwd(),
-        watch: this.options.watch
-      });
-      ctx.registerService("metadata", this.manager);
-      console.log("[MetadataPlugin] Registered metadata service, has getRegisteredTypes:", typeof this.manager.getRegisteredTypes);
-      try {
-        ctx.getService("manifest").register({
-          id: "com.objectstack.metadata",
-          name: "Metadata",
-          version: "1.0.0",
-          type: "plugin",
-          namespace: "sys",
-          objects: [SysMetadataObject]
-        });
-      } catch {
-      }
-      ctx.logger.info("MetadataPlugin providing metadata service (primary mode)", {
-        mode: "file-system",
-        features: ["watch", "persistence", "multi-format", "query", "overlay", "type-registry"]
-      });
-    };
-    this.start = async (ctx) => {
-      ctx.logger.info("Loading metadata from file system...");
-      const sortedTypes = [...DEFAULT_METADATA_TYPE_REGISTRY].sort((a, b) => a.loadOrder - b.loadOrder);
-      let totalLoaded = 0;
-      for (const entry of sortedTypes) {
-        try {
-          const items = await this.manager.loadMany(entry.type, {
-            recursive: true
-          });
-          if (items.length > 0) {
-            for (const item of items) {
-              const meta = item;
-              if (meta?.name) {
-                await this.manager.register(entry.type, meta.name, item);
-              }
-            }
-            ctx.logger.info(`Loaded ${items.length} ${entry.type} from file system`);
-            totalLoaded += items.length;
-          }
-        } catch (e) {
-          ctx.logger.debug(`No ${entry.type} metadata found`, { error: e.message });
-        }
-      }
-      ctx.logger.info("Metadata loading complete", {
-        totalItems: totalLoaded,
-        registeredTypes: sortedTypes.length
-      });
-      let driverBridged = false;
-      try {
-        const ql = ctx.getService("objectql");
-        if (ql) {
-          const tableName = this.manager["config"]?.tableName ?? "sys_metadata";
-          const driver = ql.getDriverForObject?.(tableName);
-          if (driver) {
-            ctx.logger.info("[MetadataPlugin] Bridging driver to MetadataManager via ObjectQL routing", {
-              tableName,
-              driver: driver.name
-            });
-            this.manager.setDatabaseDriver(driver);
-            driverBridged = true;
-          } else {
-            ctx.logger.debug("[MetadataPlugin] ObjectQL could not resolve driver for metadata table", { tableName });
-          }
-        }
-      } catch {
-      }
-      if (!driverBridged) {
-        try {
-          const services = ctx.getServices();
-          for (const [serviceName, service] of services) {
-            if (serviceName.startsWith("driver.") && service) {
-              ctx.logger.info("[MetadataPlugin] Bridging driver to MetadataManager (fallback: first driver)", {
-                driverService: serviceName
-              });
-              this.manager.setDatabaseDriver(service);
-              break;
-            }
-          }
-        } catch (e) {
-          ctx.logger.debug("[MetadataPlugin] No driver service found", { error: e.message });
-        }
-      }
-      try {
-        const realtimeService = ctx.getService("realtime");
-        if (realtimeService && typeof realtimeService === "object" && "publish" in realtimeService) {
-          ctx.logger.info("[MetadataPlugin] Bridging realtime service to MetadataManager for event publishing");
-          this.manager.setRealtimeService(realtimeService);
-        }
-      } catch (e) {
-        ctx.logger.debug("[MetadataPlugin] No realtime service found \u2014 metadata events will not be published", {
-          error: e.message
-        });
-      }
-    };
-    this.options = {
-      watch: true,
-      ...options
-    };
-    const rootDir = this.options.rootDir || process.cwd();
-    this.manager = new NodeMetadataManager({
-      rootDir,
-      watch: this.options.watch ?? true,
-      formats: ["yaml", "json", "typescript", "javascript"]
-    });
-    this.manager.setTypeRegistry(DEFAULT_METADATA_TYPE_REGISTRY);
-  }
-};
-
 // src/loaders/memory-loader.ts
 var MemoryLoader = class {
   constructor() {
@@ -2700,6 +2673,289 @@ var MemoryLoader = class {
   }
 };
 
+// src/plugin.ts
+import { DEFAULT_METADATA_TYPE_REGISTRY } from "@objectstack/spec/kernel";
+import {
+  SysMetadataObject as SysMetadataObject2,
+  SysMetadataHistoryObject as SysMetadataHistoryObject2
+} from "@objectstack/platform-objects/metadata";
+var queryableMetadataObjects = [
+  SysMetadataObject2,
+  SysMetadataHistoryObject2
+];
+var ARTIFACT_FIELD_TO_TYPE = {
+  objects: "object",
+  objectExtensions: "object_extension",
+  apps: "app",
+  views: "view",
+  pages: "page",
+  dashboards: "dashboard",
+  reports: "report",
+  actions: "action",
+  themes: "theme",
+  workflows: "workflow",
+  approvals: "approval",
+  flows: "flow",
+  roles: "role",
+  permissions: "permission",
+  sharingRules: "sharing_rule",
+  policies: "policy",
+  apis: "api",
+  webhooks: "webhook",
+  agents: "agent",
+  skills: "skill",
+  ragPipelines: "rag_pipeline",
+  hooks: "hook",
+  mappings: "mapping",
+  analyticsCubes: "analytics_cube",
+  connectors: "connector",
+  data: "dataset"
+};
+var MetadataPlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.metadata";
+    this.type = "standard";
+    this.version = "1.0.0";
+    this.init = async (ctx) => {
+      ctx.logger.info("Initializing Metadata Manager", {
+        root: this.options.rootDir || process.cwd(),
+        watch: this.options.watch,
+        artifactSource: this.options.artifactSource?.mode
+      });
+      ctx.registerService("metadata", this.manager);
+      console.log("[MetadataPlugin] Registered metadata service, has getRegisteredTypes:", typeof this.manager.getRegisteredTypes);
+      const registerSysObjects = this.options.registerSystemObjects !== false;
+      if (registerSysObjects) {
+        try {
+          const manifestService = ctx.getService("manifest");
+          manifestService.register({
+            id: "com.objectstack.metadata-objects",
+            name: "Metadata Platform Objects",
+            version: "1.0.0",
+            type: "plugin",
+            scope: "system",
+            defaultDatasource: "cloud",
+            objects: queryableMetadataObjects
+          });
+          ctx.logger.info("Registered system metadata objects", {
+            queryable: queryableMetadataObjects.map((object) => object.name)
+          });
+        } catch {
+        }
+      }
+      ctx.logger.info("MetadataPlugin providing metadata service (primary mode)", {
+        mode: this.options.artifactSource?.mode ?? "file-system",
+        features: ["watch", "multi-format", "query", "overlay", "type-registry"]
+      });
+    };
+    this.start = async (ctx) => {
+      const src = this.options.artifactSource;
+      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 {
+        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");
+        if (realtimeService && typeof realtimeService === "object" && "publish" in realtimeService) {
+          ctx.logger.info("[MetadataPlugin] Bridging realtime service to MetadataManager for event publishing");
+          this.manager.setRealtimeService(realtimeService);
+        }
+      } catch (e) {
+        ctx.logger.debug("[MetadataPlugin] No realtime service found \u2014 metadata events will not be published", {
+          error: e.message
+        });
+      }
+    };
+    this.options = {
+      watch: true,
+      ...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: effectiveWatch,
+      formats: ["yaml", "json", "typescript", "javascript"]
+    });
+    this.manager.setTypeRegistry(DEFAULT_METADATA_TYPE_REGISTRY);
+  }
+  /**
+   * 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 {
+      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) {
+      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;
+    const obj = raw;
+    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());
+      const checksum = createHash2("sha256").update(canonical).digest("hex");
+      const projectId = this.options.projectId ?? "proj_local";
+      ProjectArtifactSchema.parse({
+        schemaVersion: "0.1",
+        projectId,
+        commitId: "local-dev",
+        checksum,
+        metadata: def
+      });
+      metadata = def;
+    }
+    const memLoader = new MemoryLoader();
+    const manifestPackageId = metadata?.manifest?.id ?? metadata?.id ?? void 0;
+    let totalRegistered = 0;
+    for (const [field, metaType] of Object.entries(ARTIFACT_FIELD_TO_TYPE)) {
+      const items = metadata[field];
+      if (!Array.isArray(items) || items.length === 0) continue;
+      for (const item of items) {
+        const name = item?.name;
+        if (!name) continue;
+        if (manifestPackageId && item._packageId === void 0) {
+          item._packageId = manifestPackageId;
+        }
+        await memLoader.save(metaType, name, item);
+        await this.manager.register(metaType, name, item);
+        totalRegistered++;
+      }
+    }
+    this.manager.registerLoader(memLoader);
+    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 readFile2(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...");
+    const sortedTypes = [...DEFAULT_METADATA_TYPE_REGISTRY].sort((a, b) => a.loadOrder - b.loadOrder);
+    let totalLoaded = 0;
+    for (const entry of sortedTypes) {
+      try {
+        const items = await this.manager.loadMany(entry.type, {
+          recursive: true,
+          patterns: entry.filePatterns
+        });
+        if (items.length > 0) {
+          for (const item of items) {
+            const meta = item;
+            if (meta?.name) {
+              await this.manager.register(entry.type, meta.name, item);
+            }
+          }
+          ctx.logger.info(`Loaded ${items.length} ${entry.type} from file system`);
+          totalLoaded += items.length;
+        }
+      } catch (e) {
+        ctx.logger.debug(`No ${entry.type} metadata found`, { error: e.message });
+      }
+    }
+    ctx.logger.info("Metadata loading complete", {
+      totalItems: totalLoaded,
+      registeredTypes: sortedTypes.length
+    });
+  }
+};
+
 // src/loaders/remote-loader.ts
 var RemoteLoader = class {
   constructor(baseUrl, authToken) {
@@ -2797,6 +3053,9 @@ var RemoteLoader = class {
   }
 };
 
+// src/index.ts
+import { SysMetadataObject as SysMetadataObject3, SysMetadataHistoryObject as SysMetadataHistoryObject3 } from "@objectstack/platform-objects/metadata";
+
 // src/routes/history-routes.ts
 function registerMetadataHistoryRoutes(app, metadataService) {
   app.get("/api/v1/metadata/:type/:name/history", async (c) => {
@@ -2952,7 +3211,8 @@ var HistoryCleanupManager = class {
   async runCleanup() {
     const driver = this.dbLoader.driver;
     const historyTableName = this.dbLoader.historyTableName;
-    const tenantId = this.dbLoader.tenantId;
+    const organizationId = this.dbLoader.organizationId;
+    const projectId = this.dbLoader.projectId;
     let deleted = 0;
     let errors = 0;
     try {
@@ -2963,8 +3223,11 @@ var HistoryCleanupManager = class {
         const filter = {
           recorded_at: { $lt: cutoffISO }
         };
-        if (tenantId) {
-          filter.tenant_id = tenantId;
+        if (organizationId) {
+          filter.organization_id = organizationId;
+        }
+        if (projectId !== void 0) {
+          filter.project_id = projectId;
         }
         try {
           const result = await this.bulkDeleteByFilter(driver, historyTableName, filter);
@@ -2976,9 +3239,12 @@ var HistoryCleanupManager = class {
       }
       if (this.policy.maxVersions) {
         try {
+          const baseWhere = {};
+          if (organizationId) baseWhere.organization_id = organizationId;
+          if (projectId !== void 0) baseWhere.project_id = projectId;
           const metadataIds = await driver.find(historyTableName, {
             object: historyTableName,
-            where: tenantId ? { tenant_id: tenantId } : {},
+            where: baseWhere,
             fields: ["metadata_id"]
           });
           const uniqueIds = /* @__PURE__ */ new Set();
@@ -2988,10 +3254,7 @@ var HistoryCleanupManager = class {
             }
           }
           for (const metadataId of uniqueIds) {
-            const filter = { metadata_id: metadataId };
-            if (tenantId) {
-              filter.tenant_id = tenantId;
-            }
+            const filter = { metadata_id: metadataId, ...baseWhere };
             try {
               const historyRecords = await driver.find(historyTableName, {
                 object: historyTableName,
@@ -3065,20 +3328,22 @@ var HistoryCleanupManager = class {
   async getCleanupStats() {
     const driver = this.dbLoader.driver;
     const historyTableName = this.dbLoader.historyTableName;
-    const tenantId = this.dbLoader.tenantId;
+    const organizationId = this.dbLoader.organizationId;
+    const projectId = this.dbLoader.projectId;
     let recordsByAge = 0;
     let recordsByCount = 0;
     try {
+      const baseWhere = {};
+      if (organizationId) baseWhere.organization_id = organizationId;
+      if (projectId !== void 0) baseWhere.project_id = projectId;
       if (this.policy.maxAgeDays) {
         const cutoffDate = /* @__PURE__ */ new Date();
         cutoffDate.setDate(cutoffDate.getDate() - this.policy.maxAgeDays);
         const cutoffISO = cutoffDate.toISOString();
         const filter = {
-          recorded_at: { $lt: cutoffISO }
+          recorded_at: { $lt: cutoffISO },
+          ...baseWhere
         };
-        if (tenantId) {
-          filter.tenant_id = tenantId;
-        }
         recordsByAge = await driver.count(historyTableName, {
           object: historyTableName,
           where: filter
@@ -3087,7 +3352,7 @@ var HistoryCleanupManager = class {
       if (this.policy.maxVersions) {
         const metadataIds = await driver.find(historyTableName, {
           object: historyTableName,
-          where: tenantId ? { tenant_id: tenantId } : {},
+          where: baseWhere,
           fields: ["metadata_id"]
         });
         const uniqueIds = /* @__PURE__ */ new Set();
@@ -3097,10 +3362,7 @@ var HistoryCleanupManager = class {
           }
         }
         for (const metadataId of uniqueIds) {
-          const filter = { metadata_id: metadataId };
-          if (tenantId) {
-            filter.tenant_id = tenantId;
-          }
+          const filter = { metadata_id: metadataId, ...baseWhere };
           const count = await driver.count(historyTableName, {
             object: historyTableName,
             where: filter
@@ -3187,8 +3449,8 @@ export {
   migration_exports as Migration,
   NodeMetadataManager,
   RemoteLoader,
-  SysMetadataHistoryObject,
-  SysMetadataObject,
+  SysMetadataHistoryObject3 as SysMetadataHistoryObject,
+  SysMetadataObject3 as SysMetadataObject,
   TypeScriptSerializer,
   YAMLSerializer,
   calculateChecksum,