@objectstack/metadata 5.0.0 → 5.2.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as System from '@objectstack/spec/system';
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataDiffResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
-import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ISchemaDriver } from '@objectstack/spec/contracts';
+import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
 export { IMetadataService, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
 import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
@@ -161,6 +161,10 @@ declare class MetadataManager implements IMetadataService {
     private listCache;
     private static readonly LIST_CACHE_TTL_MS;
     private realtimeService?;
+    private clusterPubSub?;
+    private clusterNodeId?;
+    private clusterUnsubscribe?;
+    private static readonly CLUSTER_CHANNEL;
     protected repository?: MetadataRepository;
     private repoWatchIter?;
     private repoWatchClosed;
@@ -434,6 +438,24 @@ declare class MetadataManager implements IMetadataService {
     /** Translate a repo event to the legacy MetadataWatchEvent + invalidate caches. */
     private applyRepoEvent;
     protected notifyWatchers(type: string, event: MetadataWatchEvent): void;
+    private notifyWatchersLocal;
+    /**
+     * Attach a cluster pub/sub transport so metadata-change events fan
+     * out to peer nodes and remote events replay into local watchers.
+     *
+     * The bridge plugin in @objectstack/service-cluster calls this once
+     * per kernel boot after both cluster and metadata services are
+     * registered. Passing the same MetadataManager twice no-ops; passing
+     * a different transport replaces the prior subscription.
+     *
+     * Pass `nodeId` matching the local cluster's nodeId so loopback
+     * suppression works.
+     *
+     * @returns disposer that unsubscribes from cluster events.
+     */
+    attachClusterPubSub(pubsub: IPubSub, nodeId: string): () => void;
+    /** Tear down cluster wiring. Safe to call multiple times. */
+    detachClusterPubSub(): void;
     /**
      * Get the database loader for history operations.
      * Returns undefined if no database loader is configured.
@@ -780,7 +802,6 @@ declare class DatabaseLoader implements MetadataLoader {
     /**
      * 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

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as System from '@objectstack/spec/system';
 import { MetadataFormat, MetadataLoaderContract, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult, MetadataWatchEvent, MetadataManagerConfig, PackagePublishResult, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataDiffResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataDiffResult, MetadataExportOptions, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataImportOptions, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
-import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, ISchemaDriver } from '@objectstack/spec/contracts';
+import { IMetadataService, IDataDriver, IDataEngine, IRealtimeService, MetadataWatchCallback, MetadataWatchHandle, MetadataExportOptions, MetadataImportOptions, MetadataImportResult, MetadataTypeInfo, IPubSub, ISchemaDriver } from '@objectstack/spec/contracts';
 export { IMetadataService, MetadataImportResult, MetadataTypeInfo, MetadataWatchCallback, MetadataWatchHandle } from '@objectstack/spec/contracts';
 import { MetadataTypeRegistryEntry, MetadataQuery, MetadataQueryResult, MetadataBulkResult, MetadataOverlay, MetadataValidationResult, MetadataDependency, MetadataPluginConfig } from '@objectstack/spec/kernel';
 export { MetadataBulkResult, MetadataDependency, MetadataPluginConfig, MetadataPluginManifest, MetadataQuery, MetadataQueryResult, MetadataType, MetadataTypeRegistryEntry, MetadataValidationResult } from '@objectstack/spec/kernel';
@@ -161,6 +161,10 @@ declare class MetadataManager implements IMetadataService {
     private listCache;
     private static readonly LIST_CACHE_TTL_MS;
     private realtimeService?;
+    private clusterPubSub?;
+    private clusterNodeId?;
+    private clusterUnsubscribe?;
+    private static readonly CLUSTER_CHANNEL;
     protected repository?: MetadataRepository;
     private repoWatchIter?;
     private repoWatchClosed;
@@ -434,6 +438,24 @@ declare class MetadataManager implements IMetadataService {
     /** Translate a repo event to the legacy MetadataWatchEvent + invalidate caches. */
     private applyRepoEvent;
     protected notifyWatchers(type: string, event: MetadataWatchEvent): void;
+    private notifyWatchersLocal;
+    /**
+     * Attach a cluster pub/sub transport so metadata-change events fan
+     * out to peer nodes and remote events replay into local watchers.
+     *
+     * The bridge plugin in @objectstack/service-cluster calls this once
+     * per kernel boot after both cluster and metadata services are
+     * registered. Passing the same MetadataManager twice no-ops; passing
+     * a different transport replaces the prior subscription.
+     *
+     * Pass `nodeId` matching the local cluster's nodeId so loopback
+     * suppression works.
+     *
+     * @returns disposer that unsubscribes from cluster events.
+     */
+    attachClusterPubSub(pubsub: IPubSub, nodeId: string): () => void;
+    /** Tear down cluster wiring. Safe to call multiple times. */
+    detachClusterPubSub(): void;
     /**
      * Get the database loader for history operations.
      * Returns undefined if no database loader is configured.
@@ -780,7 +802,6 @@ declare class DatabaseLoader implements MetadataLoader {
     /**
      * 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

package/dist/index.js

@@ -755,7 +755,6 @@ var DatabaseLoader = class {
   /**
    * 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
@@ -765,7 +764,7 @@ var DatabaseLoader = class {
    * @param changeNote - Optional change description
    * @param recordedBy - Optional user who made the change
    */
-  async createHistoryRecord(metadataId, type, name, version, metadata, operationType, previousChecksum, changeNote, recordedBy) {
+  async createHistoryRecord(type, name, version, metadata, operationType, previousChecksum, changeNote, recordedBy) {
     if (!this.trackHistory) return;
     await this.ensureHistorySchema();
     const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -778,7 +777,6 @@ var DatabaseLoader = class {
     const eventSeq = await this.nextEventSeq();
     const historyRecord = {
       id: historyId,
-      metadataId,
       name,
       type,
       version,
@@ -795,7 +793,6 @@ var DatabaseLoader = class {
       await this._create(this.historyTableName, {
         id: historyRecord.id,
         event_seq: eventSeq,
-        metadata_id: historyRecord.metadataId,
         name: historyRecord.name,
         type: historyRecord.type,
         version: historyRecord.version,
@@ -983,12 +980,9 @@ var DatabaseLoader = class {
   async getHistoryRecord(type, name, version) {
     if (!this.trackHistory) return null;
     await this.ensureHistorySchema();
-    const metadataRow = await this._findOne(this.tableName, {
-      where: this.baseFilter(type, name)
-    });
-    if (!metadataRow) return null;
     const filter = {
-      metadata_id: metadataRow.id,
+      type,
+      name,
       version
     };
     if (this.organizationId) {
@@ -1000,7 +994,6 @@ var DatabaseLoader = class {
     if (!row) return null;
     return {
       id: row.id,
-      metadataId: row.metadata_id,
       name: row.name,
       type: row.type,
       version: row.version,
@@ -1025,14 +1018,9 @@ var DatabaseLoader = class {
     }
     await this.ensureSchema();
     await this.ensureHistorySchema();
-    const filter = { type, name };
-    if (this.organizationId) filter.organization_id = this.organizationId;
-    const metadataRecord = await this._findOne(this.tableName, { where: filter });
-    if (!metadataRecord) {
-      return { records: [], total: 0, hasMore: false };
-    }
     const historyFilter = {
-      metadata_id: metadataRecord.id
+      type,
+      name
     };
     if (this.organizationId) historyFilter.organization_id = this.organizationId;
     if (options?.operationType) historyFilter.operation_type = options.operationType;
@@ -1063,7 +1051,6 @@ var DatabaseLoader = class {
       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,
@@ -1108,7 +1095,6 @@ var DatabaseLoader = class {
     });
     this.invalidate(type, name);
     await this.createHistoryRecord(
-      existing.id,
       type,
       name,
       newVersion,
@@ -1150,7 +1136,6 @@ var DatabaseLoader = class {
         });
         this.invalidate(type, name);
         await this.createHistoryRecord(
-          existing.id,
           type,
           name,
           version,
@@ -1184,7 +1169,6 @@ var DatabaseLoader = class {
         });
         this.invalidate(type, name);
         await this.createHistoryRecord(
-          id,
           type,
           name,
           1,
@@ -2364,6 +2348,23 @@ var _MetadataManager = class _MetadataManager {
     this.notifyWatchers(type, legacyEvent);
   }
   notifyWatchers(type, event) {
+    this.notifyWatchersLocal(type, event);
+    if (this.clusterPubSub) {
+      const payload = {
+        originNode: this.clusterNodeId,
+        type,
+        event
+      };
+      const key = `${type}:${event.name ?? ""}`;
+      void this.clusterPubSub.publish(_MetadataManager.CLUSTER_CHANNEL, payload, { partitionKey: key }).catch((err) => {
+        this.logger.error("Cluster metadata publish failed", void 0, {
+          type,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      });
+    }
+  }
+  notifyWatchersLocal(type, event) {
     const callbacks = this.watchCallbacks.get(type);
     if (!callbacks) return;
     for (const callback of callbacks) {
@@ -2377,6 +2378,63 @@ var _MetadataManager = class _MetadataManager {
       }
     }
   }
+  /**
+   * Attach a cluster pub/sub transport so metadata-change events fan
+   * out to peer nodes and remote events replay into local watchers.
+   *
+   * The bridge plugin in @objectstack/service-cluster calls this once
+   * per kernel boot after both cluster and metadata services are
+   * registered. Passing the same MetadataManager twice no-ops; passing
+   * a different transport replaces the prior subscription.
+   *
+   * Pass `nodeId` matching the local cluster's nodeId so loopback
+   * suppression works.
+   *
+   * @returns disposer that unsubscribes from cluster events.
+   */
+  attachClusterPubSub(pubsub, nodeId) {
+    if (this.clusterPubSub === pubsub && this.clusterNodeId === nodeId) {
+      return () => this.detachClusterPubSub();
+    }
+    this.detachClusterPubSub();
+    this.clusterPubSub = pubsub;
+    this.clusterNodeId = nodeId;
+    this.clusterUnsubscribe = pubsub.subscribe(
+      _MetadataManager.CLUSTER_CHANNEL,
+      (msg) => {
+        const p = msg.payload;
+        if (p?.originNode && p.originNode === this.clusterNodeId) return;
+        if (!p?.type || !p.event) return;
+        setImmediate(() => {
+          try {
+            this.notifyWatchersLocal(p.type, p.event);
+          } catch (err) {
+            this.logger.error("Cluster remote replay failed", void 0, {
+              type: p.type,
+              error: err instanceof Error ? err.message : String(err)
+            });
+          }
+        });
+      }
+    );
+    this.logger.info("MetadataManager attached to cluster pubsub", {
+      nodeId,
+      channel: _MetadataManager.CLUSTER_CHANNEL
+    });
+    return () => this.detachClusterPubSub();
+  }
+  /** Tear down cluster wiring. Safe to call multiple times. */
+  detachClusterPubSub() {
+    if (this.clusterUnsubscribe) {
+      try {
+        this.clusterUnsubscribe();
+      } catch {
+      }
+      this.clusterUnsubscribe = void 0;
+    }
+    this.clusterPubSub = void 0;
+    this.clusterNodeId = void 0;
+  }
   // ==========================================
   // Version History & Rollback
   // ==========================================
@@ -2477,6 +2535,7 @@ var _MetadataManager = class _MetadataManager {
   }
 };
 _MetadataManager.LIST_CACHE_TTL_MS = 3e4;
+_MetadataManager.CLUSTER_CHANNEL = "metadata.changed";
 var MetadataManager = _MetadataManager;
 
 // src/plugin.ts
@@ -3603,6 +3662,10 @@ function registerMetadataHistoryRoutes(app, metadataService) {
 }
 
 // src/utils/history-cleanup.ts
+import { DEFAULT_METADATA_TYPE_REGISTRY as DEFAULT_METADATA_TYPE_REGISTRY2 } from "@objectstack/spec/kernel";
+function executionPinnedTypes() {
+  return DEFAULT_METADATA_TYPE_REGISTRY2.filter((entry) => entry.executionPinned).map((entry) => entry.type);
+}
 var HistoryCleanupManager = class {
   constructor(policy, dbLoader) {
     this.policy = policy;
@@ -3640,6 +3703,8 @@ var HistoryCleanupManager = class {
     const organizationId = this.dbLoader.organizationId;
     let deleted = 0;
     let errors = 0;
+    const pinnedTypes = executionPinnedTypes();
+    const isPinned = (t) => !!t && pinnedTypes.includes(t);
     try {
       if (this.policy.maxAgeDays) {
         const cutoffDate = /* @__PURE__ */ new Date();
@@ -3651,6 +3716,9 @@ var HistoryCleanupManager = class {
         if (organizationId) {
           filter.organization_id = organizationId;
         }
+        if (pinnedTypes.length > 0) {
+          filter.type = { $nin: pinnedTypes };
+        }
         try {
           const result = await this.bulkDeleteByFilter(driver, historyTableName, filter);
           deleted += result.deleted;
@@ -3663,19 +3731,22 @@ var HistoryCleanupManager = class {
         try {
           const baseWhere = {};
           if (organizationId) baseWhere.organization_id = organizationId;
-          const metadataIds = await driver.find(historyTableName, {
+          const metaItems = await driver.find(historyTableName, {
             object: historyTableName,
             where: baseWhere,
-            fields: ["metadata_id"]
+            fields: ["type", "name"]
           });
-          const uniqueIds = /* @__PURE__ */ new Set();
-          for (const record of metadataIds) {
-            if (record.metadata_id) {
-              uniqueIds.add(record.metadata_id);
+          const uniqueKeys = /* @__PURE__ */ new Set();
+          for (const record of metaItems) {
+            const t = record.type;
+            const n = record.name;
+            if (t && n && !isPinned(t)) {
+              uniqueKeys.add(`${t}${n}`);
             }
           }
-          for (const metadataId of uniqueIds) {
-            const filter = { metadata_id: metadataId, ...baseWhere };
+          for (const key of uniqueKeys) {
+            const [type, name] = key.split("");
+            const filter = { type, name, ...baseWhere };
             try {
               const historyRecords = await driver.find(historyTableName, {
                 object: historyTableName,
@@ -3752,6 +3823,8 @@ var HistoryCleanupManager = class {
     const organizationId = this.dbLoader.organizationId;
     let recordsByAge = 0;
     let recordsByCount = 0;
+    const pinnedTypes = executionPinnedTypes();
+    const isPinned = (t) => !!t && pinnedTypes.includes(t);
     try {
       const baseWhere = {};
       if (organizationId) baseWhere.organization_id = organizationId;
@@ -3763,25 +3836,31 @@ var HistoryCleanupManager = class {
           recorded_at: { $lt: cutoffISO },
           ...baseWhere
         };
+        if (pinnedTypes.length > 0) {
+          filter.type = { $nin: pinnedTypes };
+        }
         recordsByAge = await driver.count(historyTableName, {
           object: historyTableName,
           where: filter
         });
       }
       if (this.policy.maxVersions) {
-        const metadataIds = await driver.find(historyTableName, {
+        const metaItems = await driver.find(historyTableName, {
           object: historyTableName,
           where: baseWhere,
-          fields: ["metadata_id"]
+          fields: ["type", "name"]
         });
-        const uniqueIds = /* @__PURE__ */ new Set();
-        for (const record of metadataIds) {
-          if (record.metadata_id) {
-            uniqueIds.add(record.metadata_id);
+        const uniqueKeys = /* @__PURE__ */ new Set();
+        for (const record of metaItems) {
+          const t = record.type;
+          const n = record.name;
+          if (t && n && !isPinned(t)) {
+            uniqueKeys.add(`${t}${n}`);
           }
         }
-        for (const metadataId of uniqueIds) {
-          const filter = { metadata_id: metadataId, ...baseWhere };
+        for (const key of uniqueKeys) {
+          const [type, name] = key.split("");
+          const filter = { type, name, ...baseWhere };
           const count = await driver.count(historyTableName, {
             object: historyTableName,
             where: filter