feat(spec): add package publish protocol - MetadataRecordSchema fields, PackagePublishResultSchema, IMetadataService methods

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/spec/src/contracts/metadata-service.test.ts

@@ -343,6 +343,15 @@ describe('Metadata Service Contract', () => {
       listObjects: async () => [],
       // Package
       unregisterPackage: async () => {},
+      publishPackage: async () => ({
+        success: true,
+        packageId: 'test',
+        version: 1,
+        publishedAt: new Date().toISOString(),
+        itemsPublished: 0,
+      }),
+      revertPackage: async () => {},
+      getPublished: async () => undefined,
       // Query
       query: async () => ({ items: [], total: 0, page: 1, pageSize: 50 }),
       // Bulk
@@ -378,5 +387,39 @@ describe('Metadata Service Contract', () => {
     expect(typeof service.validate).toBe('function');
     expect(typeof service.getRegisteredTypes).toBe('function');
     expect(typeof service.getDependencies).toBe('function');
+    expect(typeof service.publishPackage).toBe('function');
+    expect(typeof service.revertPackage).toBe('function');
+    expect(typeof service.getPublished).toBe('function');
+  });
+
+  it('should allow implementation with package publish support', async () => {
+    const service: IMetadataService = {
+      register: async () => {},
+      get: async () => undefined,
+      list: async () => [],
+      unregister: async () => {},
+      exists: async () => false,
+      listNames: async () => [],
+      getObject: async () => undefined,
+      listObjects: async () => [],
+      publishPackage: async (packageId, options) => ({
+        success: true,
+        packageId,
+        version: 2,
+        publishedAt: new Date().toISOString(),
+        itemsPublished: 3,
+      }),
+      revertPackage: async () => {},
+      getPublished: async (_type, _name) => ({ name: 'account', label: 'Account' }),
+    };
+
+    const result = await service.publishPackage!('com.acme.crm', { publishedBy: 'admin' });
+    expect(result.success).toBe(true);
+    expect(result.packageId).toBe('com.acme.crm');
+    expect(result.version).toBe(2);
+    expect(result.itemsPublished).toBe(3);
+
+    const published = await service.getPublished!('object', 'account');
+    expect(published).toEqual({ name: 'account', label: 'Account' });
   });
 });

packages/spec/src/contracts/metadata-service.ts

@@ -37,6 +37,7 @@
 
 import type { MetadataQuery, MetadataQueryResult, MetadataValidationResult, MetadataBulkResult, MetadataDependency } from '../kernel/metadata-plugin.zod';
 import type { MetadataOverlay } from '../kernel/metadata-customization.zod';
+import type { PackagePublishResult } from '../system/metadata-persistence.zod';
 
 /**
  * Metadata watch callback signature
@@ -213,6 +214,38 @@ export interface IMetadataService {
      */
     unregisterPackage?(packageName: string): Promise<void>;
 
+    /**
+     * Publish an entire package:
+     * 1. Validate all draft items (dependency check)
+     * 2. Snapshot all items in the package
+     * 3. Increment package version
+     * 4. Set all items state → active
+     * @param packageId - The package ID to publish
+     * @param options - Publish options
+     * @returns Publish result with version and item count
+     */
+    publishPackage?(packageId: string, options?: {
+        changeNote?: string;
+        publishedBy?: string;
+        validate?: boolean;
+    }): Promise<PackagePublishResult>;
+
+    /**
+     * Revert entire package to last published state.
+     * Restores all metadata definitions from their published snapshots.
+     * @param packageId - The package ID to revert
+     */
+    revertPackage?(packageId: string): Promise<void>;
+
+    /**
+     * Get the published version of any metadata item (for runtime serving).
+     * Returns published_definition if exists, else current definition.
+     * @param type - Metadata type
+     * @param name - Item name/identifier
+     * @returns The published definition, or current definition if never published
+     */
+    getPublished?(type: string, name: string): Promise<unknown | undefined>;
+
     // ==========================================
     // Query / Search
     // ==========================================

packages/spec/src/system/metadata-persistence.test.ts

@@ -17,6 +17,7 @@ import {
   MetadataManagerConfigSchema,
   MetadataFallbackStrategySchema,
   MetadataSourceSchema,
+  PackagePublishResultSchema,
 } from './metadata-persistence.zod';
 
 describe('MetadataScopeSchema', () => {
@@ -100,6 +101,35 @@ describe('MetadataRecordSchema', () => {
     expect(record.tags).toEqual(['crm', 'custom']);
   });
 
+  it('should accept publishing fields', () => {
+    const record = MetadataRecordSchema.parse({
+      id: 'abc-123',
+      name: 'account_list_view',
+      type: 'view',
+      metadata: { columns: ['name'] },
+      publishedDefinition: { columns: ['name', 'email'] },
+      publishedAt: '2025-06-01T12:00:00Z',
+      publishedBy: 'admin-user',
+    });
+
+    expect(record.publishedDefinition).toEqual({ columns: ['name', 'email'] });
+    expect(record.publishedAt).toBe('2025-06-01T12:00:00Z');
+    expect(record.publishedBy).toBe('admin-user');
+  });
+
+  it('should allow omitting publishing fields (backward compatible)', () => {
+    const record = MetadataRecordSchema.parse({
+      id: 'abc-123',
+      name: 'test',
+      type: 'object',
+      metadata: {},
+    });
+
+    expect(record.publishedDefinition).toBeUndefined();
+    expect(record.publishedAt).toBeUndefined();
+    expect(record.publishedBy).toBeUndefined();
+  });
+
   it('should default version to 1', () => {
     const record = MetadataRecordSchema.parse({
       id: 'x', name: 'y', type: 'z', metadata: {},
@@ -518,3 +548,44 @@ describe('MetadataSourceSchema', () => {
     expect(() => MetadataSourceSchema.parse('unknown')).toThrow();
   });
 });
+
+describe('PackagePublishResultSchema', () => {
+  it('should accept a successful publish result', () => {
+    const result = PackagePublishResultSchema.parse({
+      success: true,
+      packageId: 'com.acme.crm',
+      version: 2,
+      publishedAt: '2025-06-01T12:00:00Z',
+      itemsPublished: 5,
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.packageId).toBe('com.acme.crm');
+    expect(result.version).toBe(2);
+    expect(result.publishedAt).toBe('2025-06-01T12:00:00Z');
+    expect(result.itemsPublished).toBe(5);
+    expect(result.validationErrors).toBeUndefined();
+  });
+
+  it('should accept a failed publish result with validation errors', () => {
+    const result = PackagePublishResultSchema.parse({
+      success: false,
+      packageId: 'com.acme.crm',
+      version: 1,
+      publishedAt: '2025-06-01T12:00:00Z',
+      itemsPublished: 0,
+      validationErrors: [
+        { type: 'view', name: 'missing_view', message: 'Referenced object not found' },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.validationErrors).toHaveLength(1);
+    expect(result.validationErrors![0].type).toBe('view');
+  });
+
+  it('should reject missing required fields', () => {
+    expect(() => PackagePublishResultSchema.parse({})).toThrow();
+    expect(() => PackagePublishResultSchema.parse({ success: true })).toThrow();
+  });
+});

packages/spec/src/system/metadata-persistence.zod.ts

@@ -111,6 +111,14 @@ export const MetadataRecordSchema = z.object({
   /** Classification tags */
   tags: z.array(z.string()).optional().describe('Classification tags for filtering and grouping'),
 
+  /** Package Publishing */
+  publishedDefinition: z.unknown().optional()
+    .describe('Snapshot of the last published definition'),
+  publishedAt: z.string().datetime().optional()
+    .describe('When this metadata was last published'),
+  publishedBy: z.string().optional()
+    .describe('Who published this version'),
+
   /** Audit */
   createdBy: z.string().optional(),
   createdAt: z.string().datetime().optional().describe('Creation timestamp'),
@@ -121,6 +129,25 @@ export const MetadataRecordSchema = z.object({
 export type MetadataRecord = z.infer<typeof MetadataRecordSchema>;
 export type MetadataScope = z.infer<typeof MetadataScopeSchema>;
 
+/**
+ * Package Publish Result
+ * Returned by `publishPackage()` after a package-level metadata publish operation.
+ */
+export const PackagePublishResultSchema = z.object({
+  success: z.boolean().describe('Whether the publish succeeded'),
+  packageId: z.string().describe('The package ID that was published'),
+  version: z.number().int().describe('New version number after publish'),
+  publishedAt: z.string().datetime().describe('Publish timestamp'),
+  itemsPublished: z.number().int().describe('Total metadata items published'),
+  validationErrors: z.array(z.object({
+    type: z.string().describe('Metadata type that failed validation'),
+    name: z.string().describe('Item name that failed validation'),
+    message: z.string().describe('Validation error message'),
+  })).optional().describe('Validation errors if publish failed'),
+});
+
+export type PackagePublishResult = z.infer<typeof PackagePublishResultSchema>;
+
 /**
  * Metadata Format
  * Supported file formats for metadata serialization.