@objectstack/metadata 4.0.1 → 4.0.3

package/dist/node.js

@@ -326,6 +326,224 @@ var SysMetadataObject = ObjectSchema.create({
   }
 });
 
+// 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/utils/metadata-history-utils.ts
+async function calculateChecksum(metadata) {
+  const normalized = normalizeJSON(metadata);
+  const jsonString = JSON.stringify(normalized);
+  if (typeof globalThis.crypto !== "undefined" && globalThis.crypto.subtle) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(jsonString);
+    const hashBuffer = await globalThis.crypto.subtle.digest("SHA-256", data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  return simpleHash(jsonString);
+}
+function normalizeJSON(value) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(normalizeJSON);
+  }
+  if (typeof value === "object") {
+    const sorted = {};
+    const keys = Object.keys(value).sort();
+    for (const key of keys) {
+      sorted[key] = normalizeJSON(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+function simpleHash(str) {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash << 5) + hash + str.charCodeAt(i);
+    hash = hash & hash;
+  }
+  const hexHash = Math.abs(hash).toString(16);
+  return hexHash.padStart(64, "0");
+}
+function generateSimpleDiff(oldObj, newObj, path3 = "") {
+  const changes = [];
+  if (typeof oldObj !== "object" || oldObj === null || typeof newObj !== "object" || newObj === null) {
+    if (oldObj !== newObj) {
+      changes.push({ op: "replace", path: path3 || "/", value: newObj, oldValue: oldObj });
+    }
+    return changes;
+  }
+  if (Array.isArray(oldObj) || Array.isArray(newObj)) {
+    if (!Array.isArray(oldObj) || !Array.isArray(newObj) || oldObj.length !== newObj.length) {
+      changes.push({ op: "replace", path: path3 || "/", value: newObj, oldValue: oldObj });
+    } else {
+      for (let i = 0; i < oldObj.length; i++) {
+        const subPath = `${path3}/${i}`;
+        changes.push(...generateSimpleDiff(oldObj[i], newObj[i], subPath));
+      }
+    }
+    return changes;
+  }
+  const oldKeys = new Set(Object.keys(oldObj));
+  const newKeys = new Set(Object.keys(newObj));
+  for (const key of newKeys) {
+    if (!oldKeys.has(key)) {
+      const subPath = path3 ? `${path3}/${key}` : `/${key}`;
+      changes.push({ op: "add", path: subPath, value: newObj[key] });
+    }
+  }
+  for (const key of oldKeys) {
+    if (!newKeys.has(key)) {
+      const subPath = path3 ? `${path3}/${key}` : `/${key}`;
+      changes.push({ op: "remove", path: subPath, oldValue: oldObj[key] });
+    }
+  }
+  for (const key of oldKeys) {
+    if (newKeys.has(key)) {
+      const subPath = path3 ? `${path3}/${key}` : `/${key}`;
+      changes.push(...generateSimpleDiff(
+        oldObj[key],
+        newObj[key],
+        subPath
+      ));
+    }
+  }
+  return changes;
+}
+function generateDiffSummary(diff) {
+  if (diff.length === 0) {
+    return "No changes";
+  }
+  const summary = [];
+  const addCount = diff.filter((d) => d.op === "add").length;
+  const removeCount = diff.filter((d) => d.op === "remove").length;
+  const replaceCount = diff.filter((d) => d.op === "replace").length;
+  if (addCount > 0) summary.push(`${addCount} field${addCount > 1 ? "s" : ""} added`);
+  if (removeCount > 0) summary.push(`${removeCount} field${removeCount > 1 ? "s" : ""} removed`);
+  if (replaceCount > 0) summary.push(`${replaceCount} field${replaceCount > 1 ? "s" : ""} modified`);
+  return summary.join(", ");
+}
+
 // src/loaders/database-loader.ts
 var DatabaseLoader = class {
   constructor(options) {
@@ -340,9 +558,12 @@ var DatabaseLoader = class {
       }
     };
     this.schemaReady = false;
+    this.historySchemaReady = false;
     this.driver = options.driver;
     this.tableName = options.tableName ?? "sys_metadata";
+    this.historyTableName = options.historyTableName ?? "sys_metadata_history";
     this.tenantId = options.tenantId;
+    this.trackHistory = options.trackHistory !== false;
   }
   /**
    * Ensure the metadata table exists.
@@ -361,6 +582,22 @@ var DatabaseLoader = class {
       this.schemaReady = true;
     }
   }
+  /**
+   * Ensure the history table exists.
+   * Uses IDataDriver.syncSchema with the SysMetadataHistoryObject definition.
+   */
+  async ensureHistorySchema() {
+    if (!this.trackHistory || this.historySchemaReady) return;
+    try {
+      await this.driver.syncSchema(this.historyTableName, {
+        ...SysMetadataHistoryObject,
+        name: this.historyTableName
+      });
+      this.historySchemaReady = true;
+    } catch (error) {
+      console.error("Failed to ensure history schema, will retry on next operation:", error);
+    }
+  }
   /**
    * Build base filter conditions for queries.
    * Always includes tenantId when configured.
@@ -375,6 +612,64 @@ var DatabaseLoader = class {
     }
     return filter;
   }
+  /**
+   * Create a history record for a metadata change.
+   *
+   * @param metadataId - The metadata record ID
+   * @param type - Metadata type
+   * @param name - Metadata name
+   * @param version - Version number
+   * @param metadata - The metadata payload
+   * @param operationType - Type of operation
+   * @param previousChecksum - Checksum of previous version (if any)
+   * @param changeNote - Optional change description
+   * @param recordedBy - Optional user who made the change
+   */
+  async createHistoryRecord(metadataId, type, name, version, metadata, operationType, previousChecksum, changeNote, recordedBy) {
+    if (!this.trackHistory) return;
+    await this.ensureHistorySchema();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const checksum = await calculateChecksum(metadata);
+    if (previousChecksum && checksum === previousChecksum && operationType === "update") {
+      return;
+    }
+    const historyId = generateId();
+    const metadataJson = JSON.stringify(metadata);
+    const historyRecord = {
+      id: historyId,
+      metadataId,
+      name,
+      type,
+      version,
+      operationType,
+      metadata: metadataJson,
+      checksum,
+      previousChecksum,
+      changeNote,
+      recordedBy,
+      recordedAt: now,
+      ...this.tenantId ? { tenantId: this.tenantId } : {}
+    };
+    try {
+      await this.driver.create(this.historyTableName, {
+        id: historyRecord.id,
+        metadata_id: historyRecord.metadataId,
+        name: historyRecord.name,
+        type: historyRecord.type,
+        version: historyRecord.version,
+        operation_type: historyRecord.operationType,
+        metadata: historyRecord.metadata,
+        checksum: historyRecord.checksum,
+        previous_checksum: historyRecord.previousChecksum,
+        change_note: historyRecord.changeNote,
+        recorded_by: historyRecord.recordedBy,
+        recorded_at: historyRecord.recordedAt,
+        ...this.tenantId ? { tenant_id: this.tenantId } : {}
+      });
+    } catch (error) {
+      console.error(`Failed to create history record for ${type}/${name}:`, error);
+    }
+  }
   /**
    * Convert a database row to a metadata payload.
    * Parses the JSON `metadata` column back into an object.
@@ -502,24 +797,124 @@ var DatabaseLoader = class {
       return [];
     }
   }
+  /**
+   * Fetch a single history snapshot by (type, name, version).
+   * Returns null when the record does not exist.
+   */
+  async getHistoryRecord(type, name, version) {
+    if (!this.trackHistory) return null;
+    await this.ensureHistorySchema();
+    const metadataRow = await this.driver.findOne(this.tableName, {
+      object: this.tableName,
+      where: this.baseFilter(type, name)
+    });
+    if (!metadataRow) return null;
+    const filter = {
+      metadata_id: metadataRow.id,
+      version
+    };
+    if (this.tenantId) {
+      filter.tenant_id = this.tenantId;
+    }
+    const row = await this.driver.findOne(this.historyTableName, {
+      object: this.historyTableName,
+      where: filter
+    });
+    if (!row) return null;
+    return {
+      id: row.id,
+      metadataId: row.metadata_id,
+      name: row.name,
+      type: row.type,
+      version: row.version,
+      operationType: row.operation_type,
+      metadata: typeof row.metadata === "string" ? JSON.parse(row.metadata) : row.metadata,
+      checksum: row.checksum,
+      previousChecksum: row.previous_checksum,
+      changeNote: row.change_note,
+      tenantId: row.tenant_id,
+      recordedBy: row.recorded_by,
+      recordedAt: row.recorded_at
+    };
+  }
+  /**
+   * 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()`
+   * would produce). This avoids the duplicate-version problem that arises when
+   * `register()` → `save()` writes an 'update' entry followed by an additional
+   * 'revert' entry for the same version number.
+   */
+  async registerRollback(type, name, restoredData, targetVersion, changeNote, recordedBy) {
+    await this.ensureSchema();
+    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,
+      where: this.baseFilter(type, name)
+    });
+    if (!existing) {
+      throw new Error(`Metadata ${type}/${name} not found for rollback`);
+    }
+    const previousChecksum = existing.checksum;
+    const newVersion = (existing.version ?? 0) + 1;
+    await this.driver.update(this.tableName, existing.id, {
+      metadata: metadataJson,
+      version: newVersion,
+      checksum: newChecksum,
+      updated_at: now,
+      state: "active"
+    });
+    await this.createHistoryRecord(
+      existing.id,
+      type,
+      name,
+      newVersion,
+      restoredData,
+      "revert",
+      previousChecksum,
+      changeNote ?? `Rolled back to version ${targetVersion}`,
+      recordedBy
+    );
+  }
   async save(type, name, data, _options) {
     const startTime = Date.now();
     await this.ensureSchema();
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const metadataJson = JSON.stringify(data);
+    const newChecksum = await calculateChecksum(data);
     try {
       const existing = await this.driver.findOne(this.tableName, {
         object: this.tableName,
         where: this.baseFilter(type, name)
       });
       if (existing) {
+        const previousChecksum = existing.checksum;
+        if (newChecksum === previousChecksum) {
+          return {
+            success: true,
+            path: `datasource://${this.tableName}/${type}/${name}`,
+            size: metadataJson.length,
+            saveTime: Date.now() - startTime
+          };
+        }
         const version = (existing.version ?? 0) + 1;
         await this.driver.update(this.tableName, existing.id, {
           metadata: metadataJson,
           version,
+          checksum: newChecksum,
           updated_at: now,
           state: "active"
         });
+        await this.createHistoryRecord(
+          existing.id,
+          type,
+          name,
+          version,
+          data,
+          "update",
+          previousChecksum
+        );
         return {
           success: true,
           path: `datasource://${this.tableName}/${type}/${name}`,
@@ -535,6 +930,7 @@ var DatabaseLoader = class {
           namespace: "default",
           scope: data?.scope ?? "platform",
           metadata: metadataJson,
+          checksum: newChecksum,
           strategy: "merge",
           state: "active",
           version: 1,
@@ -543,6 +939,14 @@ var DatabaseLoader = class {
           created_at: now,
           updated_at: now
         });
+        await this.createHistoryRecord(
+          id,
+          type,
+          name,
+          1,
+          data,
+          "create"
+        );
         return {
           success: true,
           path: `datasource://${this.tableName}/${type}/${name}`,
@@ -556,6 +960,20 @@ var DatabaseLoader = class {
       );
     }
   }
+  /**
+   * Delete a metadata item from the database
+   */
+  async delete(type, name) {
+    await this.ensureSchema();
+    const existing = await this.driver.findOne(this.tableName, {
+      object: this.tableName,
+      where: this.baseFilter(type, name)
+    });
+    if (!existing) {
+      return;
+    }
+    await this.driver.delete(this.tableName, existing.id);
+  }
 };
 function generateId() {
   if (typeof globalThis.crypto !== "undefined" && typeof globalThis.crypto.randomUUID === "function") {
@@ -621,6 +1039,16 @@ var MetadataManager = class {
     this.registerLoader(dbLoader);
     this.logger.info("DatabaseLoader configured", { datasource: this.config.datasource, tableName });
   }
+  /**
+   * Set the realtime service for publishing metadata change events.
+   * Should be called after kernel resolves the realtime service.
+   *
+   * @param service - An IRealtimeService instance for event publishing
+   */
+  setRealtimeService(service) {
+    this.realtimeService = service;
+    this.logger.info("RealtimeService configured for metadata events");
+  }
   /**
    * Register a new metadata loader (data source)
    */
@@ -633,12 +1061,39 @@ var MetadataManager = class {
   // ==========================================
   /**
    * Register/save a metadata item by type
+   * Stores in-memory registry and persists to database-backed loaders only.
+   * FilesystemLoader (protocol 'file:') is read-only for static metadata and
+   * should not be written to during runtime registration.
    */
   async register(type, name, data) {
     if (!this.registry.has(type)) {
       this.registry.set(type, /* @__PURE__ */ new Map());
     }
     this.registry.get(type).set(name, data);
+    for (const loader of this.loaders.values()) {
+      if (loader.save && loader.contract.protocol === "datasource:" && loader.contract.capabilities.write) {
+        await loader.save(type, name, data);
+      }
+    }
+    if (this.realtimeService) {
+      const event = {
+        type: `metadata.${type}.created`,
+        object: type,
+        payload: {
+          metadataType: type,
+          name,
+          definition: data,
+          packageId: data?.packageId
+        },
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      try {
+        await this.realtimeService.publish(event);
+        this.logger.debug(`Published metadata.${type}.created event`, { name });
+      } catch (error) {
+        this.logger.warn(`Failed to publish metadata event`, { type, name, error });
+      }
+    }
   }
   /**
    * Get a metadata item by type and name.
@@ -679,7 +1134,8 @@ var MetadataManager = class {
     return Array.from(items.values());
   }
   /**
-   * Unregister/remove a metadata item by type and name
+   * Unregister/remove a metadata item by type and name.
+   * Deletes from database-backed loaders only (same rationale as register()).
    */
   async unregister(type, name) {
     const typeStore = this.registry.get(type);
@@ -689,6 +1145,33 @@ var MetadataManager = class {
         this.registry.delete(type);
       }
     }
+    for (const loader of this.loaders.values()) {
+      if (loader.contract.protocol !== "datasource:" || !loader.contract.capabilities.write) continue;
+      if (typeof loader.delete === "function") {
+        try {
+          await loader.delete(type, name);
+        } catch (error) {
+          this.logger.warn(`Failed to delete ${type}/${name} from loader ${loader.contract.name}`, { error });
+        }
+      }
+    }
+    if (this.realtimeService) {
+      const event = {
+        type: `metadata.${type}.deleted`,
+        object: type,
+        payload: {
+          metadataType: type,
+          name
+        },
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      try {
+        await this.realtimeService.publish(event);
+        this.logger.debug(`Published metadata.${type}.deleted event`, { name });
+      } catch (error) {
+        this.logger.warn(`Failed to publish metadata event`, { type, name, error });
+      }
+    }
   }
   /**
    * Check if a metadata item exists
@@ -771,20 +1254,17 @@ var MetadataManager = class {
    * Unregister all metadata items from a specific package
    */
   async unregisterPackage(packageName) {
+    const itemsToDelete = [];
     for (const [type, typeStore] of this.registry) {
-      const toDelete = [];
       for (const [name, data] of typeStore) {
         const meta = data;
         if (meta?.packageId === packageName || meta?.package === packageName) {
-          toDelete.push(name);
+          itemsToDelete.push({ type, name });
         }
       }
-      for (const name of toDelete) {
-        typeStore.delete(name);
-      }
-      if (typeStore.size === 0) {
-        this.registry.delete(type);
-      }
+    }
+    for (const { type, name } of itemsToDelete) {
+      await this.unregister(type, name);
     }
   }
   /**
@@ -1449,6 +1929,174 @@ var MetadataManager = class {
       }
     }
   }
+  // ==========================================
+  // Version History & Rollback
+  // ==========================================
+  /**
+   * Get the database loader for history operations.
+   * Returns undefined if no database loader is configured.
+   */
+  getDatabaseLoader() {
+    const dbLoader = this.loaders.get("database");
+    if (dbLoader && dbLoader instanceof DatabaseLoader) {
+      return dbLoader;
+    }
+    return void 0;
+  }
+  /**
+   * Get version history for a metadata item.
+   * Returns a timeline of all changes made to the item.
+   */
+  async getHistory(type, name, options) {
+    const dbLoader = this.getDatabaseLoader();
+    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 {
+      records: historyResult,
+      total,
+      hasMore
+    };
+  }
+  /**
+   * Rollback a metadata item to a specific version.
+   * Restores the metadata definition from the history snapshot.
+   */
+  async rollback(type, name, version, options) {
+    const dbLoader = this.getDatabaseLoader();
+    if (!dbLoader) {
+      throw new Error("Rollback requires a database loader to be configured");
+    }
+    const targetVersion = await dbLoader.getHistoryRecord(type, name, version);
+    if (!targetVersion) {
+      throw new Error(`Version ${version} not found in history for ${type}/${name}`);
+    }
+    if (!targetVersion.metadata) {
+      throw new Error(`Version ${version} metadata snapshot not available`);
+    }
+    const restoredMetadata = targetVersion.metadata;
+    await dbLoader.registerRollback(
+      type,
+      name,
+      restoredMetadata,
+      version,
+      options?.changeNote,
+      options?.recordedBy
+    );
+    if (!this.registry.has(type)) {
+      this.registry.set(type, /* @__PURE__ */ new Map());
+    }
+    this.registry.get(type).set(name, restoredMetadata);
+    return restoredMetadata;
+  }
+  /**
+   * Compare two versions of a metadata item.
+   * Returns a diff showing what changed between versions.
+   */
+  async diff(type, name, version1, version2) {
+    const dbLoader = this.getDatabaseLoader();
+    if (!dbLoader) {
+      throw new Error("Diff requires a database loader to be configured");
+    }
+    const v1 = await dbLoader.getHistoryRecord(type, name, version1);
+    const v2 = await dbLoader.getHistoryRecord(type, name, version2);
+    if (!v1) {
+      throw new Error(`Version ${version1} not found in history for ${type}/${name}`);
+    }
+    if (!v2) {
+      throw new Error(`Version ${version2} not found in history for ${type}/${name}`);
+    }
+    if (!v1.metadata || !v2.metadata) {
+      throw new Error("Version metadata snapshots not available");
+    }
+    const patch = generateSimpleDiff(v1.metadata, v2.metadata);
+    const identical = patch.length === 0;
+    const summary = generateDiffSummary(patch);
+    return {
+      type,
+      name,
+      version1,
+      version2,
+      checksum1: v1.checksum,
+      checksum2: v2.checksum,
+      identical,
+      patch,
+      summary
+    };
+  }
 };
 
 // src/node-metadata-manager.ts
@@ -1869,14 +2517,18 @@ var MetadataPlugin = class {
         watch: this.options.watch
       });
       ctx.registerService("metadata", this.manager);
-      ctx.registerService("app.com.objectstack.metadata", {
-        id: "com.objectstack.metadata",
-        name: "Metadata",
-        version: "1.0.0",
-        type: "plugin",
-        namespace: "sys",
-        objects: [SysMetadataObject]
-      });
+      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"]
@@ -1909,6 +2561,33 @@ var MetadataPlugin = class {
         totalItems: totalLoaded,
         registeredTypes: sortedTypes.length
       });
+      try {
+        const services = ctx.getServices();
+        for (const [serviceName, service] of services) {
+          if (serviceName.startsWith("driver.") && service) {
+            ctx.logger.info("[MetadataPlugin] Bridging driver to MetadataManager for database-backed persistence", {
+              driverService: serviceName
+            });
+            this.manager.setDatabaseDriver(service);
+            break;
+          }
+        }
+      } catch (e) {
+        ctx.logger.debug("[MetadataPlugin] No driver service found \u2014 database metadata persistence not available", {
+          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,
@@ -1988,6 +2667,18 @@ var MemoryLoader = class {
       saveTime: 0
     };
   }
+  /**
+   * Delete a metadata item from memory storage
+   */
+  async delete(type, name) {
+    const typeStore = this.storage.get(type);
+    if (typeStore) {
+      typeStore.delete(name);
+      if (typeStore.size === 0) {
+        this.storage.delete(type);
+      }
+    }
+  }
 };
 
 // src/loaders/remote-loader.ts
@@ -2087,6 +2778,330 @@ var RemoteLoader = class {
   }
 };
 
+// src/routes/history-routes.ts
+function registerMetadataHistoryRoutes(app, metadataService) {
+  app.get("/api/v1/metadata/:type/:name/history", async (c) => {
+    if (!metadataService.getHistory) {
+      return c.json({ error: "History tracking not enabled" }, 501);
+    }
+    const { type, name } = c.req.param();
+    const query = c.req.query();
+    try {
+      const options = {};
+      if (query.limit !== void 0) {
+        const limit = parseInt(query.limit, 10);
+        if (!Number.isFinite(limit) || limit < 1) {
+          return c.json({ success: false, error: "limit must be a positive integer" }, 400);
+        }
+        options.limit = limit;
+      }
+      if (query.offset !== void 0) {
+        const offset = parseInt(query.offset, 10);
+        if (!Number.isFinite(offset) || offset < 0) {
+          return c.json({ success: false, error: "offset must be a non-negative integer" }, 400);
+        }
+        options.offset = offset;
+      }
+      if (query.since) options.since = query.since;
+      if (query.until) options.until = query.until;
+      if (query.operationType) options.operationType = query.operationType;
+      if (query.includeMetadata !== void 0) {
+        options.includeMetadata = query.includeMetadata === "true";
+      }
+      const result = await metadataService.getHistory(type, name, options);
+      return c.json({
+        success: true,
+        data: result
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : "Failed to retrieve history"
+        },
+        500
+      );
+    }
+  });
+  app.post("/api/v1/metadata/:type/:name/rollback", async (c) => {
+    if (!metadataService.rollback) {
+      return c.json({ error: "Rollback not supported" }, 501);
+    }
+    const { type, name } = c.req.param();
+    try {
+      const body = await c.req.json();
+      const { version, changeNote, recordedBy } = body;
+      if (typeof version !== "number") {
+        return c.json(
+          {
+            success: false,
+            error: "Version number is required"
+          },
+          400
+        );
+      }
+      const restoredMetadata = await metadataService.rollback(type, name, version, {
+        changeNote,
+        recordedBy
+      });
+      return c.json({
+        success: true,
+        data: {
+          type,
+          name,
+          version,
+          metadata: restoredMetadata
+        }
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : "Rollback failed"
+        },
+        500
+      );
+    }
+  });
+  app.get("/api/v1/metadata/:type/:name/diff", async (c) => {
+    if (!metadataService.diff) {
+      return c.json({ error: "Diff not supported" }, 501);
+    }
+    const { type, name } = c.req.param();
+    const query = c.req.query();
+    try {
+      const version1 = parseInt(query.version1, 10);
+      const version2 = parseInt(query.version2, 10);
+      if (isNaN(version1) || isNaN(version2)) {
+        return c.json(
+          {
+            success: false,
+            error: "Both version1 and version2 query parameters are required"
+          },
+          400
+        );
+      }
+      const diffResult = await metadataService.diff(type, name, version1, version2);
+      return c.json({
+        success: true,
+        data: diffResult
+      });
+    } catch (error) {
+      return c.json(
+        {
+          success: false,
+          error: error instanceof Error ? error.message : "Diff failed"
+        },
+        500
+      );
+    }
+  });
+}
+
+// src/utils/history-cleanup.ts
+var HistoryCleanupManager = class {
+  constructor(policy, dbLoader) {
+    this.policy = policy;
+    this.dbLoader = dbLoader;
+  }
+  /**
+   * Start automatic cleanup if enabled in the policy.
+   */
+  start() {
+    if (!this.policy.autoCleanup) {
+      return;
+    }
+    const intervalMs = (this.policy.cleanupIntervalHours ?? 24) * 60 * 60 * 1e3;
+    void this.runCleanup();
+    this.cleanupTimer = setInterval(() => {
+      void this.runCleanup();
+    }, intervalMs);
+  }
+  /**
+   * Stop automatic cleanup.
+   */
+  stop() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = void 0;
+    }
+  }
+  /**
+   * Run cleanup based on the retention policy.
+   * Removes history records that exceed the configured limits.
+   */
+  async runCleanup() {
+    const driver = this.dbLoader.driver;
+    const historyTableName = this.dbLoader.historyTableName;
+    const tenantId = this.dbLoader.tenantId;
+    let deleted = 0;
+    let errors = 0;
+    try {
+      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 }
+        };
+        if (tenantId) {
+          filter.tenant_id = tenantId;
+        }
+        try {
+          const result = await this.bulkDeleteByFilter(driver, historyTableName, filter);
+          deleted += result.deleted;
+          errors += result.errors;
+        } catch {
+          errors++;
+        }
+      }
+      if (this.policy.maxVersions) {
+        try {
+          const metadataIds = await driver.find(historyTableName, {
+            object: historyTableName,
+            where: tenantId ? { tenant_id: tenantId } : {},
+            fields: ["metadata_id"]
+          });
+          const uniqueIds = /* @__PURE__ */ new Set();
+          for (const record of metadataIds) {
+            if (record.metadata_id) {
+              uniqueIds.add(record.metadata_id);
+            }
+          }
+          for (const metadataId of uniqueIds) {
+            const filter = { metadata_id: metadataId };
+            if (tenantId) {
+              filter.tenant_id = tenantId;
+            }
+            try {
+              const historyRecords = await driver.find(historyTableName, {
+                object: historyTableName,
+                where: filter,
+                orderBy: [{ field: "version", order: "desc" }],
+                fields: ["id"]
+              });
+              if (historyRecords.length > this.policy.maxVersions) {
+                const toDelete = historyRecords.slice(this.policy.maxVersions);
+                const ids = toDelete.map((r) => r.id).filter(Boolean);
+                const result = await this.bulkDeleteByIds(driver, historyTableName, ids);
+                deleted += result.deleted;
+                errors += result.errors;
+              }
+            } catch {
+              errors++;
+            }
+          }
+        } catch {
+          errors++;
+        }
+      }
+    } catch (error) {
+      console.error("History cleanup failed:", error);
+      errors++;
+    }
+    return { deleted, errors };
+  }
+  /**
+   * Delete records matching a filter using the most efficient method available on the driver.
+   */
+  async bulkDeleteByFilter(driver, table, filter) {
+    const driverAny = driver;
+    if (typeof driverAny.deleteMany === "function") {
+      const count = await driverAny.deleteMany(table, filter);
+      return { deleted: typeof count === "number" ? count : 0, errors: 0 };
+    }
+    const records = await driver.find(table, { object: table, where: filter, fields: ["id"] });
+    const ids = records.map((r) => r.id).filter(Boolean);
+    return this.bulkDeleteByIds(driver, table, ids);
+  }
+  /**
+   * Delete records by IDs using bulkDelete when available, otherwise one-by-one.
+   */
+  async bulkDeleteByIds(driver, table, ids) {
+    if (ids.length === 0) return { deleted: 0, errors: 0 };
+    const driverAny = driver;
+    if (typeof driverAny.bulkDelete === "function") {
+      const result = await driverAny.bulkDelete(table, ids);
+      return {
+        deleted: typeof result === "number" ? result : ids.length,
+        errors: 0
+      };
+    }
+    let deleted = 0;
+    let errors = 0;
+    for (const id of ids) {
+      try {
+        await driver.delete(table, id);
+        deleted++;
+      } catch {
+        errors++;
+      }
+    }
+    return { deleted, errors };
+  }
+  /**
+   * Get cleanup statistics without actually deleting anything.
+   * Useful for previewing what would be cleaned up.
+   */
+  async getCleanupStats() {
+    const driver = this.dbLoader.driver;
+    const historyTableName = this.dbLoader.historyTableName;
+    const tenantId = this.dbLoader.tenantId;
+    let recordsByAge = 0;
+    let recordsByCount = 0;
+    try {
+      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 }
+        };
+        if (tenantId) {
+          filter.tenant_id = tenantId;
+        }
+        recordsByAge = await driver.count(historyTableName, {
+          object: historyTableName,
+          where: filter
+        });
+      }
+      if (this.policy.maxVersions) {
+        const metadataIds = await driver.find(historyTableName, {
+          object: historyTableName,
+          where: tenantId ? { tenant_id: tenantId } : {},
+          fields: ["metadata_id"]
+        });
+        const uniqueIds = /* @__PURE__ */ new Set();
+        for (const record of metadataIds) {
+          if (record.metadata_id) {
+            uniqueIds.add(record.metadata_id);
+          }
+        }
+        for (const metadataId of uniqueIds) {
+          const filter = { metadata_id: metadataId };
+          if (tenantId) {
+            filter.tenant_id = tenantId;
+          }
+          const count = await driver.count(historyTableName, {
+            object: historyTableName,
+            where: filter
+          });
+          if (count > this.policy.maxVersions) {
+            recordsByCount += count - this.policy.maxVersions;
+          }
+        }
+      }
+    } catch (error) {
+      console.error("Failed to get cleanup stats:", error);
+    }
+    return {
+      recordsByAge,
+      recordsByCount,
+      total: recordsByAge + recordsByCount
+    };
+  }
+};
+
 // src/migration/index.ts
 var migration_exports = {};
 __export(migration_exports, {
@@ -2145,6 +3160,7 @@ var MigrationExecutor = class {
 export {
   DatabaseLoader,
   FilesystemLoader,
+  HistoryCleanupManager,
   JSONSerializer,
   MemoryLoader,
   MetadataManager,
@@ -2152,8 +3168,13 @@ export {
   migration_exports as Migration,
   NodeMetadataManager,
   RemoteLoader,
+  SysMetadataHistoryObject,
   SysMetadataObject,
   TypeScriptSerializer,
-  YAMLSerializer
+  YAMLSerializer,
+  calculateChecksum,
+  generateDiffSummary,
+  generateSimpleDiff,
+  registerMetadataHistoryRoutes
 };
 //# sourceMappingURL=node.js.map