feat: Package-level unified metadata publishing mechanism (publishPackage)

ROADMAP.md

@@ -398,6 +398,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 - [x] **In-Memory Driver** — Full CRUD, bulk ops, transactions, aggregation pipeline (Mingo), streaming
 - [x] **In-Memory Driver Persistence** — File-system (Node.js) and localStorage (Browser) persistence adapters with auto-save, custom adapter support
 - [x] **Metadata Service** — CRUD, query, bulk ops, overlay system, dependency tracking, import/export, file watching
+- [x] **Metadata Package Publishing** — `publishPackage`, `revertPackage`, `getPublished` for atomic package-level metadata publishing with version snapshots
 - [x] **Serializers** — JSON, YAML, TypeScript format support
 - [x] **Loaders** — Memory, Filesystem, Remote (HTTP) loaders
 - [x] **REST API** — Auto-generated CRUD/Metadata/Batch/Discovery endpoints
@@ -452,6 +453,7 @@ business/custom objects, aligning with industry best practices (e.g., ServiceNow
 - User overlay persistence across sessions
 - Multi-instance metadata synchronization
 - Production-grade metadata storage
+- Package-level metadata publishing (publishPackage / revertPackage / getPublished)
 
 ### Phase 4b: Infrastructure Service Upgrades (P1 — Weeks 3-4)
 

content/docs/guides/contracts/metadata-service.mdx

@@ -352,3 +352,59 @@ const filteredViews = views.filter(view => {
   return !v.requiredPermission || userPermissions.includes(v.requiredPermission);
 });
 ```
+
+---
+
+## Package Publishing
+
+ObjectStack uses **package-level publishing** to ensure metadata consistency. All metadata items within a package are published atomically — either everything goes live, or nothing does.
+
+### publishPackage
+
+Publishes all metadata items in a package:
+1. Validates all items (optional)
+2. Snapshots each item's definition into `publishedDefinition`
+3. Increments the package version
+4. Sets all items to `active` state
+
+```typescript
+const result = await metadataService.publishPackage('com.acme.crm', {
+  publishedBy: 'admin-user',
+  validate: true,        // default: true
+  changeNote: 'Added opportunity fields',
+});
+
+console.log(result.success);         // true
+console.log(result.version);         // 2
+console.log(result.itemsPublished);  // 5
+console.log(result.publishedAt);     // "2025-06-01T12:00:00Z"
+```
+
+### revertPackage
+
+Reverts all metadata items in a package to their last published state. Discards any unpublished changes.
+
+```typescript
+await metadataService.revertPackage('com.acme.crm');
+// All items restored to their publishedDefinition snapshots
+```
+
+### getPublished
+
+Returns the published version of a metadata item (for runtime/end-user serving). Falls back to the current definition if the item has never been published.
+
+```typescript
+// End user sees the published version
+const published = await metadataService.getPublished('object', 'opportunity');
+
+// Designer sees the draft version (via regular get)
+const draft = await metadataService.get('object', 'opportunity');
+```
+
+### REST Endpoints
+
+| Method | Path | Description |
+|:---|:---|:---|
+| `POST` | `/packages/:id/publish` | Publish a package |
+| `POST` | `/packages/:id/revert` | Revert a package to last published state |
+| `GET` | `/metadata/:type/:name/published` | Get published version of a metadata item |

packages/metadata/README.md

@@ -86,6 +86,7 @@ The `MetadataManager` is the main orchestrator. It provides:
 - **Core CRUD**: `register`, `get`, `list`, `unregister`, `exists`, `listNames`
 - **Convenience**: `getObject`, `listObjects`
 - **Package Management**: `unregisterPackage` — unload all metadata from a package
+- **Package Publishing**: `publishPackage`, `revertPackage`, `getPublished` — atomic package-level metadata publishing
 - **Query / Search**: `query` with filtering, pagination, sorting by type/scope/state/tags
 - **Bulk Operations**: `bulkRegister`, `bulkUnregister` with error handling
 - **Import / Export**: `exportMetadata`, `importMetadata` with conflict resolution (skip/overwrite/merge)
@@ -201,6 +202,34 @@ const plugin = MetadataPlugin({
 kernel.use(plugin);
 ```
 
+## Package Publishing
+
+ObjectStack supports **package-level metadata publishing** — all metadata items within a package are published atomically.
+
+### Publish a Package
+
+```typescript
+const result = await manager.publishPackage('com.acme.crm', {
+  publishedBy: 'admin',
+  validate: true,
+});
+// result: { success: true, version: 2, itemsPublished: 5, publishedAt: '...' }
+```
+
+### Revert to Last Published State
+
+```typescript
+await manager.revertPackage('com.acme.crm');
+// All items restored to their publishedDefinition snapshots
+```
+
+### Get Published Version (Runtime Serving)
+
+```typescript
+const published = await manager.getPublished('object', 'opportunity');
+// Returns publishedDefinition if exists, else current definition
+```
+
 ## Package Structure
 
 ```

packages/metadata/src/metadata-manager.ts

@@ -15,6 +15,7 @@ import type {
   MetadataSaveResult,
   MetadataWatchEvent,
   MetadataFormat,
+  PackagePublishResult,
 } from '@objectstack/spec/system';
 import type {
   IMetadataService,
@@ -333,6 +334,187 @@ export class MetadataManager implements IMetadataService {
     }
   }
 
+  /**
+   * Publish an entire package:
+   * 1. Validate all draft items
+   * 2. Snapshot all items in the package (publishedDefinition = clone(metadata))
+   * 3. Increment version
+   * 4. Set all items state → active
+   */
+  async publishPackage(packageId: string, options?: {
+    changeNote?: string;
+    publishedBy?: string;
+    validate?: boolean;
+  }): Promise<PackagePublishResult> {
+    const now = new Date().toISOString();
+    const shouldValidate = options?.validate !== false;
+    const publishedBy = options?.publishedBy;
+
+    // Collect all items belonging to this package
+    const packageItems: Array<{ type: string; name: string; data: any }> = [];
+    for (const [type, typeStore] of this.registry) {
+      for (const [name, data] of typeStore) {
+        const meta = data as any;
+        if (meta?.packageId === packageId || meta?.package === packageId) {
+          packageItems.push({ type, name, data: meta });
+        }
+      }
+    }
+
+    if (packageItems.length === 0) {
+      return {
+        success: false,
+        packageId,
+        version: 0,
+        publishedAt: now,
+        itemsPublished: 0,
+        validationErrors: [{ type: '', name: '', message: `No metadata items found for package '${packageId}'` }],
+      };
+    }
+
+    // Validation pass
+    if (shouldValidate) {
+      const validationErrors: Array<{ type: string; name: string; message: string }> = [];
+
+      // Schema validation
+      for (const item of packageItems) {
+        const result = await this.validate(item.type, item.data);
+        if (!result.valid && result.errors) {
+          for (const err of result.errors) {
+            validationErrors.push({
+              type: item.type,
+              name: item.name,
+              message: err.message,
+            });
+          }
+        }
+      }
+
+      // Dependency validation: referenced items must be in the same package or already published
+      const packageItemKeys = new Set(packageItems.map(i => `${i.type}:${i.name}`));
+      for (const item of packageItems) {
+        const deps = await this.getDependencies(item.type, item.name);
+        for (const dep of deps) {
+          const depKey = `${dep.targetType}:${dep.targetName}`;
+          // Skip if the dependency is within this package
+          if (packageItemKeys.has(depKey)) continue;
+          // Check if the dependency exists and has been published
+          const depItem = await this.get(dep.targetType, dep.targetName);
+          if (!depItem) {
+            validationErrors.push({
+              type: item.type,
+              name: item.name,
+              message: `Dependency '${dep.targetType}:${dep.targetName}' not found`,
+            });
+          } else {
+            const depMeta = depItem as any;
+            if (depMeta.publishedDefinition === undefined && depMeta.state !== 'active') {
+              validationErrors.push({
+                type: item.type,
+                name: item.name,
+                message: `Dependency '${dep.targetType}:${dep.targetName}' is not published`,
+              });
+            }
+          }
+        }
+      }
+
+      if (validationErrors.length > 0) {
+        return {
+          success: false,
+          packageId,
+          version: 0,
+          publishedAt: now,
+          itemsPublished: 0,
+          validationErrors,
+        };
+      }
+    }
+
+    // Determine the next version by finding the max current version across items
+    let maxVersion = 0;
+    for (const item of packageItems) {
+      const v = typeof item.data.version === 'number' ? item.data.version : 0;
+      if (v > maxVersion) maxVersion = v;
+    }
+    const newVersion = maxVersion + 1;
+
+    // Snapshot and update all items
+    for (const item of packageItems) {
+      const updated = {
+        ...item.data,
+        publishedDefinition: structuredClone(item.data.metadata ?? item.data),
+        publishedAt: now,
+        publishedBy: publishedBy ?? item.data.publishedBy,
+        version: newVersion,
+        state: 'active',
+      };
+      await this.register(item.type, item.name, updated);
+    }
+
+    return {
+      success: true,
+      packageId,
+      version: newVersion,
+      publishedAt: now,
+      itemsPublished: packageItems.length,
+    };
+  }
+
+  /**
+   * Revert entire package to last published state.
+   * Restores all metadata definitions from their published snapshots.
+   */
+  async revertPackage(packageId: string): Promise<void> {
+    const packageItems: Array<{ type: string; name: string; data: any }> = [];
+    for (const [type, typeStore] of this.registry) {
+      for (const [name, data] of typeStore) {
+        const meta = data as any;
+        if (meta?.packageId === packageId || meta?.package === packageId) {
+          packageItems.push({ type, name, data: meta });
+        }
+      }
+    }
+
+    if (packageItems.length === 0) {
+      throw new Error(`No metadata items found for package '${packageId}'`);
+    }
+
+    // Check that at least one item has a published snapshot
+    const hasPublished = packageItems.some(item => item.data.publishedDefinition !== undefined);
+    if (!hasPublished) {
+      throw new Error(`Package '${packageId}' has never been published`);
+    }
+
+    for (const item of packageItems) {
+      if (item.data.publishedDefinition !== undefined) {
+        const reverted = {
+          ...item.data,
+          metadata: structuredClone(item.data.publishedDefinition),
+          state: 'active',
+        };
+        await this.register(item.type, item.name, reverted);
+      }
+    }
+  }
+
+  /**
+   * Get the published version of any metadata item (for runtime serving).
+   * Returns publishedDefinition if exists, else current definition.
+   */
+  async getPublished(type: string, name: string): Promise<unknown | undefined> {
+    const item = await this.get(type, name);
+    if (!item) return undefined;
+
+    const meta = item as any;
+    if (meta.publishedDefinition !== undefined) {
+      return meta.publishedDefinition;
+    }
+
+    // Fall back to current definition (metadata field or the item itself)
+    return meta.metadata ?? item;
+  }
+
   // ==========================================
   // Query / Search
   // ==========================================