feat: Marketplace Package Lifecycle — 6 protocol specifications

[Copilot]

The package distribution pipeline (git dev → build → marketplace → install/upgrade/uninstall) had 6 protocol gaps blocking end-to-end operation. This PR adds the missing schemas across P0 (blocking distribution) and P1 (blocking upgrades).

P0 — Distribution Pipeline

• Package Artifact Format (package-artifact.zod.ts) — Defines .tgz internal structure: PackageArtifactSchema, ArtifactChecksumSchema (file→SHA256 map), ArtifactSignatureSchema (RSA/ECDSA), MetadataCategoryEnum, ArtifactFileEntrySchema
• Platform Version Compatibility — ManifestSchema.engine field for semver range requirements (e.g. >=3.0.0), InstallPackageRequestSchema.platformVersion for install-time verification
• Artifact Storage & Distribution (marketplace.zod.ts) — ArtifactReferenceSchema (URL + SHA256 + size), ArtifactDownloadResponseSchema (pre-signed URLs), artifact refs linked into listing versions and install requests

P1 — Upgrade Scenarios

• Upgrade Migration Context (plugin.zod.ts) — UpgradeContextSchema with previousVersion/newVersion/isMajorUpgrade/previousMetadata; InstalledPackageSchema.upgradeHistory tracking migration outcomes
• Dependency Resolution (dependency-resolution.zod.ts) — ResolvedDependencySchema (satisfied/needs_install/needs_upgrade/conflict), DependencyResolutionResultSchema with topological install ordering and circular dependency detection; linked to InstallPackageResponseSchema
• Namespace Collision Detection (package-registry.zod.ts) — NamespaceRegistryEntrySchema, NamespaceConflictErrorSchema, InstalledPackageSchema.registeredNamespaces

// Platform compatibility in manifest
engine: z.object({
  objectstack: z.string().regex(/^[><=~^]*\d+\.\d+\.\d+/)
    .describe('SemVer range, e.g. ">=3.0.0"'),
}).optional()

// Dependency resolution result on install response
dependencyResolution: DependencyResolutionResultSchema.optional()
// → { dependencies, canProceed, requiredActions, installOrder, circularDependencies }

All new fields are .optional() for backward compatibility. 60 new tests (6056 total). Docs, ROADMAP.md, and ENTERPRISE_ASSESSMENT.md updated.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Marketplace Package Lifecycle: 必须开发的协议清单</issue_title>
<issue_description>

背景

基于 Git-based 开发模式，ObjectStack 的包分发链路为：

开发者本地 Git 开发 → 打包上传市场 → 用户在系统内下载安装/升级/卸载

经过与 Salesforce Packages 和 Power Apps Solutions 的深度对比分析，当前协议层（manifest.zod.ts、package-registry.zod.ts、marketplace.zod.ts）已经覆盖了包定义、命名空间、依赖声明、生命周期钩子、市场发布流程等核心能力。

但仍有 6 项关键缺失 阻塞整条链路的完整运行。以下按优先级分为 P0（阻塞链路）和 P1（阻塞升级场景）两组。

---

P0 — 阻塞整条链路（必须先完成）

任务 1: 包构建产物规范 (Package Artifact Format Spec)

问题: marketplace-publishing.md 提到 os plugin build 产生 .tgz，但没有定义产物内部结构的 Schema。市场无法校验、存储、分发一个没有标准格式的产物。

具体任务:

• 在 packages/spec/src/kernel/ 下创建 package-artifact.zod.ts
• 定义 PackageArtifactSchema，规范 .tgz 内部结构：

  ├── manifest.json          ← ManifestSchema 序列化
  ├── metadata/              ← 30+ metadata 类型的 JSON 序列化
  │   ├── objects/            ← *.object.json
  │   ├── views/              ← *.view.json
  │   ├── pages/              ← *.page.json
  │   ├── flows/              ← *.flow.json
  │   ├── dashboards/         ← *.dashboard.json
  │   ├── permissions/        ← *.permission.json
  │   ├── agents/             ← *.agent.json
  │   └── ...                 ← 其他 metadata 类型
  ├── assets/                ← 静态资源
  │   ├── icon.svg
  │   └── screenshots/
  ├── data/                  ← Seed data (DatasetSchema 序列化)
  ├── locales/               ← i18n 翻译文件
  ├── checksums.json         ← 每个文件的 SHA256 校验
  └── signature.sig          ← RSA-SHA256 包签名
  

• 定义 ArtifactChecksumSchema：文件路径 → SHA256 映射
• 定义 ArtifactSignatureSchema：签名算法、公钥引用、签名值
• 创建对应测试文件 package-artifact.test.ts
• 在 stack.zod.ts 的导出中注册

影响文件: 新建 packages/spec/src/kernel/package-artifact.zod.ts

---

任务 2: 平台版本兼容性声明 (Platform Version Compatibility)

问题: 当前 ManifestSchema 缺少平台最低版本要求字段。用户安装包时，系统无法判断"这个包能不能在当前版本的平台上运行"。

具体任务:

• 在 ManifestSchema（manifest.zod.ts）中增加字段：

  /** 最低平台版本要求 */
  engine: z.object({
    objectstack: z.string()
      .regex(/^[><=~^]*\d+\.\d+\.\d+/)
      .describe('ObjectStack platform version requirement (SemVer range, e.g. ">=3.0.0")'),
  }).optional().describe('Platform compatibility requirements'),

• 在 package-registry.zod.ts 的 InstallPackageRequestSchema 中增加兼容性校验逻辑的字段说明
• 更新现有测试 manifest.test.ts 增加新字段的测试用例
• 更新文档 content/docs/references/kernel/manifest.mdx

影响文件: 修改 packages/spec/src/kernel/manifest.zod.ts

---

任务 3: 产物存储与分发协议 (Artifact Storage & Distribution)

问题: 用户点击"安装"时，系统需要知道去哪里下载包产物。当前 MarketplaceListingSchema 没有定义产物的下载地址和完整性校验。

具体任务:

• 在 marketplace.zod.ts 中增加 ArtifactReferenceSchema：

  const ArtifactReferenceSchema = z.object({
    /** 产物下载 URL */
    url: z.string().url().describe('Artifact download URL'),
    /** SHA256 完整性校验 */
    sha256: z.string().regex(/^[a-f0-9]{64}$/).describe('SHA256 checksum'),
    /** 文件大小 (bytes) */
    size: z.number().int().positive().describe('Artifact size in bytes'),
    /** 产物格式 */
    format: z.enum(['tgz', 'zip']).default('tgz').describe('Artifact format'),
    /** 上传时间 */
    uploadedAt: z.string().datetime().describe('Upload timestamp'),
  });

• 在 MarketplaceListingSchema 的 version 记录中关联 ArtifactReferenceSchema
• 在 InstallPackageRequestSchema 中增加 artifactUrl 或 artifactRef 字段
• 定义 ArtifactDownloadResponseSchema（用于 REST API）
• 更新测试和文档

影响文件: 修改 packages/spec/src/cloud/marketplace.zod.ts

---

P1 — 阻塞升级场景（安装跑通后必须完成）

任务 4: 升级版本迁移上下文 (Upgrade Migration Context)

问题: PluginLifecycleSchema 中 onUpgrade 钩子存在，但缺少版本上下文参数。开发者无法在升级钩子中编写"从 v1 到 v2 需要做什么迁移"的逻辑。

具体任务:

• 在 plugin.zod.ts 中定义 UpgradeContextSchema：

  const UpgradeContextSchema = z.object({
    /** 升级前版本 */
    previousVersion: z.string().describe('Version before upgrade'),
    /** 升级后版本 */
    newVersion: z.string().describe('Version after upgrade'),
    /** 是否为大版本升级 */
    isMajorUpgrade: z.boolean().describe('Whether this is a major version bump'),
    /** 已注册的 metadata 快照 (升级前) */
    previousMetadata: z.record(z.string(), z.unknown()).optional()
      .describe('Metadata snapshot before upgrade'),
  });

• 修改 PluginLifecycleSchema 中 onUpgrade 的签名描述，明确接收 UpgradeContext
• 在 package-registry.zod.ts 的升级流程中增加版本迁移记录：

  upgradeHistory: z.array(z.object({
    fromVersion: z.string(),
    toVersion: z.string(),
    upgradedAt: z.string().datetime(),
    status: z.enum(['success', 'failed', 'rolled_back']),
    migrationLog: z.array(z.string()).optional(),
  })).optional(),

• 更新测试

影响文件: 修改 packages/spec/src/kernel/plugin.zod.ts, package-registry.zod.ts

---

任务 5: 运行时依赖解析协议 (Dependency Resolution Protocol)

问题: ManifestSchema 声明了 dependencies，但缺少运行时依赖解析的结果 Schema。当安装 A 需要 B@^2.0，但已安装的 B 是 1.x 时，系统需要标准化的方式表达冲突和解决方案。

具体任务:

• 在 `packages/...

• Fixes Marketplace Package Lifecycle: 必须开发的协议清单 #766

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Ready	Preview, Comment	Feb 21, 2026 11:46am
spec	Ready	Preview, Comment	Feb 21, 2026 11:46am

[Copilot]

Pull request overview

This PR implements the complete package distribution protocol for ObjectStack's marketplace, filling 6 critical protocol gaps that were blocking the end-to-end package lifecycle (git dev → build → marketplace → install/upgrade/uninstall). The implementation is comprehensive, well-tested, and properly documented.

Changes:

• P0 Distribution Pipeline: Added package artifact format specification (package-artifact.zod.ts) defining .tgz internal structure with checksums and digital signatures; added platform version compatibility via ManifestSchema.engine field for semver requirements; integrated artifact storage and distribution into marketplace.zod.ts with ArtifactReferenceSchema and ArtifactDownloadResponseSchema
• P1 Upgrade Scenarios: Added upgrade migration context (UpgradeContextSchema) for version-aware onUpgrade hooks; implemented dependency resolution protocol (dependency-resolution.zod.ts) with conflict detection and topological ordering; added namespace collision detection with NamespaceRegistryEntrySchema and NamespaceConflictErrorSchema
• Comprehensive Testing: Added 60 new tests across 4 test files providing thorough coverage of all new schemas and edge cases; all new fields are .optional() for backward compatibility

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/spec/src/kernel/package-artifact.zod.ts	New file defining package artifact format with checksums, signatures, and metadata categories
packages/spec/src/kernel/package-artifact.test.ts	New file with 17 test cases covering artifact validation scenarios
packages/spec/src/kernel/dependency-resolution.zod.ts	New file defining dependency resolution protocol with conflict detection and install ordering
packages/spec/src/kernel/dependency-resolution.test.ts	New file with 15 test cases covering resolution scenarios
packages/spec/src/kernel/plugin.zod.ts	Added UpgradeContextSchema for version migration context
packages/spec/src/kernel/plugin.test.ts	Added 3 test cases for upgrade context validation
packages/spec/src/kernel/package-registry.zod.ts	Added upgrade history, namespace registry, conflict detection, and dependency resolution integration
packages/spec/src/kernel/package-registry.test.ts	Added 7 test cases for new registry features
packages/spec/src/kernel/manifest.zod.ts	Added engine field for platform compatibility requirements
packages/spec/src/kernel/manifest.test.ts	Added 4 test cases for engine field validation
packages/spec/src/cloud/marketplace.zod.ts	Added artifact reference and download response schemas
packages/spec/src/cloud/marketplace.test.ts	Added 3 test cases for artifact distribution
packages/spec/src/kernel/index.ts	Registered exports for new protocol files
content/docs/references/kernel/package-artifact.mdx	New documentation file for package artifact protocol
content/docs/references/kernel/dependency-resolution.mdx	New documentation file for dependency resolution protocol
content/docs/references/kernel/package-registry.mdx	Updated with namespace registry and upgrade history documentation
content/docs/references/kernel/manifest.mdx	Updated with engine field documentation
content/docs/references/cloud/marketplace.mdx	Updated with artifact reference documentation
content/docs/references/kernel/meta.json	Added new protocol files to navigation
docs/ENTERPRISE_ASSESSMENT.md	Updated with comprehensive protocol implementation details
ROADMAP.md	Marked 5 protocol tasks as completed