feat: add package artifact, platform compatibility, artifact distribution, upgrade migration protocols

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

Author: Copilot

packages/spec/src/cloud/marketplace.test.ts

@@ -11,6 +11,8 @@ import {
   MarketplaceSearchResponseSchema,
   MarketplaceInstallRequestSchema,
   MarketplaceInstallResponseSchema,
+  ArtifactReferenceSchema,
+  ArtifactDownloadResponseSchema,
 } from './marketplace.zod';
 
 describe('PublisherVerificationSchema', () => {
@@ -340,3 +342,116 @@ describe('MarketplaceInstallResponseSchema', () => {
     expect(parsed.success).toBe(false);
   });
 });
+
+describe('ArtifactReferenceSchema', () => {
+  it('should accept valid artifact reference', () => {
+    const ref = {
+      url: 'https://registry.objectstack.io/packages/com.acme.crm-2.0.0.tgz',
+      sha256: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2',
+      size: 1048576,
+      uploadedAt: '2025-06-01T12:00:00Z',
+    };
+    const parsed = ArtifactReferenceSchema.parse(ref);
+    expect(parsed.format).toBe('tgz');
+    expect(parsed.size).toBe(1048576);
+  });
+
+  it('should accept zip format', () => {
+    const ref = {
+      url: 'https://registry.objectstack.io/packages/com.acme.crm-2.0.0.zip',
+      sha256: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2',
+      size: 2048576,
+      format: 'zip' as const,
+      uploadedAt: '2025-06-01T12:00:00Z',
+    };
+    const parsed = ArtifactReferenceSchema.parse(ref);
+    expect(parsed.format).toBe('zip');
+  });
+
+  it('should reject invalid SHA256', () => {
+    expect(() => ArtifactReferenceSchema.parse({
+      url: 'https://registry.objectstack.io/pkg.tgz',
+      sha256: 'invalid-hash',
+      size: 1024,
+      uploadedAt: '2025-06-01T12:00:00Z',
+    })).toThrow();
+  });
+
+  it('should reject non-positive size', () => {
+    expect(() => ArtifactReferenceSchema.parse({
+      url: 'https://registry.objectstack.io/pkg.tgz',
+      sha256: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2',
+      size: 0,
+      uploadedAt: '2025-06-01T12:00:00Z',
+    })).toThrow();
+  });
+});
+
+describe('ArtifactDownloadResponseSchema', () => {
+  it('should accept valid download response', () => {
+    const response = {
+      downloadUrl: 'https://cdn.objectstack.io/artifacts/com.acme.crm-2.0.0.tgz?token=abc',
+      sha256: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2',
+      size: 1048576,
+      format: 'tgz' as const,
+      expiresAt: '2025-06-01T13:00:00Z',
+    };
+    const parsed = ArtifactDownloadResponseSchema.parse(response);
+    expect(parsed.expiresAt).toBe('2025-06-01T13:00:00Z');
+  });
+
+  it('should accept response without expiration', () => {
+    const response = {
+      downloadUrl: 'https://cdn.objectstack.io/artifacts/com.acme.crm-2.0.0.tgz',
+      sha256: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2',
+      size: 1048576,
+      format: 'tgz' as const,
+    };
+    const parsed = ArtifactDownloadResponseSchema.parse(response);
+    expect(parsed.expiresAt).toBeUndefined();
+  });
+});
+
+describe('MarketplaceListingSchema - Artifact References', () => {
+  it('should accept listing with artifact references in versions', () => {
+    const listing = {
+      id: 'listing-001',
+      packageId: 'com.acme.crm',
+      publisherId: 'pub-001',
+      name: 'Acme CRM',
+      category: 'crm' as const,
+      latestVersion: '2.0.0',
+      versions: [
+        {
+          version: '2.0.0',
+          releaseDate: '2025-06-01T00:00:00Z',
+          artifact: {
+            url: 'https://registry.objectstack.io/packages/com.acme.crm-2.0.0.tgz',
+            sha256: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2',
+            size: 1048576,
+            uploadedAt: '2025-06-01T00:00:00Z',
+          },
+        },
+      ],
+    };
+    const parsed = MarketplaceListingSchema.parse(listing);
+    expect(parsed.versions![0].artifact?.sha256).toBe('a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2');
+  });
+});
+
+describe('MarketplaceInstallRequestSchema - Artifact Reference', () => {
+  it('should accept install request with artifact reference', () => {
+    const request = {
+      listingId: 'listing-001',
+      version: '2.0.0',
+      artifactRef: {
+        url: 'https://registry.objectstack.io/packages/com.acme.crm-2.0.0.tgz',
+        sha256: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2',
+        size: 1048576,
+        uploadedAt: '2025-06-01T00:00:00Z',
+      },
+    };
+    const parsed = MarketplaceInstallRequestSchema.parse(request);
+    expect(parsed.artifactRef?.url).toContain('com.acme.crm');
+  });
+});

packages/spec/src/cloud/marketplace.zod.ts

@@ -86,6 +86,61 @@ export const PublisherSchema = z.object({
   registeredAt: z.string().datetime().optional(),
 });
 
+// ==========================================
+// Artifact Reference & Distribution
+// ==========================================
+
+/**
+ * Artifact Reference Schema
+ *
+ * Points to a downloadable package artifact with integrity verification.
+ * Used in marketplace listings and install workflows.
+ */
+export const ArtifactReferenceSchema = z.object({
+  /** Artifact download URL */
+  url: z.string().url().describe('Artifact download URL'),
+
+  /** SHA256 integrity checksum */
+  sha256: z.string().regex(/^[a-f0-9]{64}$/).describe('SHA256 checksum'),
+
+  /** File size in bytes */
+  size: z.number().int().positive().describe('Artifact size in bytes'),
+
+  /** Artifact format */
+  format: z.enum(['tgz', 'zip']).default('tgz').describe('Artifact format'),
+
+  /** Upload timestamp */
+  uploadedAt: z.string().datetime().describe('Upload timestamp'),
+}).describe('Reference to a downloadable package artifact');
+
+export type ArtifactReference = z.infer<typeof ArtifactReferenceSchema>;
+
+/**
+ * Artifact Download Response Schema
+ *
+ * Response from the artifact download API endpoint.
+ * Provides a time-limited download URL with integrity metadata.
+ */
+export const ArtifactDownloadResponseSchema = z.object({
+  /** Pre-signed or direct download URL */
+  downloadUrl: z.string().url().describe('Artifact download URL (may be pre-signed)'),
+
+  /** SHA256 checksum for download verification */
+  sha256: z.string().regex(/^[a-f0-9]{64}$/).describe('SHA256 checksum for verification'),
+
+  /** File size in bytes */
+  size: z.number().int().positive().describe('Artifact size in bytes'),
+
+  /** Artifact format */
+  format: z.enum(['tgz', 'zip']).describe('Artifact format'),
+
+  /** URL expiration time (for pre-signed URLs) */
+  expiresAt: z.string().datetime().optional()
+    .describe('URL expiration timestamp for pre-signed URLs'),
+}).describe('Artifact download response with integrity metadata');
+
+export type ArtifactDownloadResponse = z.infer<typeof ArtifactDownloadResponseSchema>;
+
 // ==========================================
 // Marketplace Listing
 // ==========================================
@@ -211,6 +266,9 @@ export const MarketplaceListingSchema = z.object({
     releaseNotes: z.string().optional(),
     minPlatformVersion: z.string().optional(),
     deprecated: z.boolean().default(false),
+    /** Artifact reference for this version */
+    artifact: ArtifactReferenceSchema.optional()
+      .describe('Downloadable artifact for this version'),
   })).optional().describe('Published versions'),
 
   /** Aggregate statistics */
@@ -399,6 +457,10 @@ export const MarketplaceInstallRequestSchema = z.object({
   /** Whether to enable immediately after install */
   enableOnInstall: z.boolean().default(true),
 
+  /** Artifact reference (resolved from listing version, or provided directly) */
+  artifactRef: ArtifactReferenceSchema.optional()
+    .describe('Artifact reference for direct installation'),
+
   /** Tenant ID */
   tenantId: z.string().optional(),
 });
@@ -435,3 +497,5 @@ export type MarketplaceSearchRequest = z.infer<typeof MarketplaceSearchRequestSc
 export type MarketplaceSearchResponse = z.infer<typeof MarketplaceSearchResponseSchema>;
 export type MarketplaceInstallRequest = z.infer<typeof MarketplaceInstallRequestSchema>;
 export type MarketplaceInstallResponse = z.infer<typeof MarketplaceInstallResponseSchema>;
+export type ArtifactReference = z.infer<typeof ArtifactReferenceSchema>;
+export type ArtifactDownloadResponse = z.infer<typeof ArtifactDownloadResponseSchema>;

packages/spec/src/kernel/index.ts

@@ -9,6 +9,7 @@ export * from './manifest.zod';
 export * from './metadata-customization.zod';
 export * from './metadata-loader.zod';
 export * from './metadata-plugin.zod';
+export * from './package-artifact.zod';
 export * from './package-registry.zod';
 export * from './package-upgrade.zod';
 export * from './plugin-capability.zod';

packages/spec/src/kernel/manifest.test.ts

@@ -382,6 +382,58 @@ describe('ManifestSchema', () => {
     });
   });
 
+  describe('Platform Compatibility (engine)', () => {
+    it('should accept manifest with engine requirements', () => {
+      const manifest = {
+        id: 'com.acme.crm',
+        version: '1.0.0',
+        type: 'app' as const,
+        name: 'Acme CRM',
+        engine: {
+          objectstack: '>=3.0.0',
+        },
+      };
+      const parsed = ManifestSchema.parse(manifest);
+      expect(parsed.engine?.objectstack).toBe('>=3.0.0');
+    });
+
+    it('should accept various semver range formats', () => {
+      const ranges = ['>=3.0.0', '^2.1.0', '~1.5.0', '>=1.0.0', '3.0.0'];
+      ranges.forEach(range => {
+        const manifest = {
+          id: 'com.test.app',
+          version: '1.0.0',
+          type: 'app' as const,
+          name: 'Test',
+          engine: { objectstack: range },
+        };
+        expect(() => ManifestSchema.parse(manifest)).not.toThrow();
+      });
+    });
+
+    it('should reject invalid engine version format', () => {
+      const manifest = {
+        id: 'com.test.app',
+        version: '1.0.0',
+        type: 'app' as const,
+        name: 'Test',
+        engine: { objectstack: 'latest' },
+      };
+      expect(() => ManifestSchema.parse(manifest)).toThrow();
+    });
+
+    it('should accept manifest without engine (backward compatible)', () => {
+      const manifest = {
+        id: 'com.test.app',
+        version: '1.0.0',
+        type: 'app' as const,
+        name: 'Test',
+      };
+      const parsed = ManifestSchema.parse(manifest);
+      expect(parsed.engine).toBeUndefined();
+    });
+  });
+
   describe('Reverse Domain Notation', () => {
     it('should accept various reverse domain notation formats', () => {
       const validIds = [

packages/spec/src/kernel/manifest.zod.ts

@@ -339,6 +339,24 @@ export const ManifestSchema = z.object({
    */
   loading: PluginLoadingConfigSchema.optional()
     .describe('Plugin loading and runtime behavior configuration'),
+
+  /**
+   * Platform Compatibility Requirements.
+   * Specifies the minimum ObjectStack platform version required to run this package.
+   * Used at install time to prevent incompatible packages from being installed.
+   *
+   * @example
+   * ```yaml
+   * engine:
+   *   objectstack: ">=3.0.0"
+   * ```
+   */
+  engine: z.object({
+    /** ObjectStack platform version requirement (SemVer range) */
+    objectstack: z.string()
+      .regex(/^[><=~^]*\d+\.\d+\.\d+/)
+      .describe('ObjectStack platform version requirement (SemVer range, e.g. ">=3.0.0")'),
+  }).optional().describe('Platform compatibility requirements'),
 });
 
 /**