BPOS-TMP-REPO/apps/api/src/modules/activity-registry/contract.ts

/**
 * module: activity-registry —— 对外类型(编码规范 §10.1;语义出处 OS 11,AM 11)。
 *
 * 活动库:**独立的安装与卸载入口** —— 不在编排中发生。
 * 安装恒为新增、版本并存;在途任务按其启动时版本跑完,切换零丢单。
 */
import type { ActivityManifest, InstallVerdict, StaticAuditFinding } from '@contracts';
import type {
  AssetKind,
  AssetVersion,
  IncrementState,
  LoadEnvelope,
  PackageVersion,
  ReplayCase,
  ReplayVerdict,
} from './internal/domain/versioning.ts';
import type { ExternalChecks } from './internal/domain/static-audit.ts';

export type {
  ActivityManifest,
  AssetKind,
  AssetVersion,
  ExternalChecks,
  IncrementState,
  InstallVerdict,
  LoadEnvelope,
  PackageVersion,
  ReplayCase,
  ReplayVerdict,
  StaticAuditFinding,
};

export class InstallRejectedError extends Error {
  constructor(readonly verdict: InstallVerdict) {
    super(`活动包未过安装两审:${verdict.staticFindings.map((f) => f.message).join('; ')}`);
    this.name = 'InstallRejectedError';
  }
}

export class ActivityNotInstalledError extends Error {
  constructor(readonly activityId: string) {
    super(`活动未安装:${activityId}`);
    this.name = 'ActivityNotInstalledError';
  }
}

export class ToolNotDeclaredError extends Error {
  constructor(readonly missing: readonly string[]) {
    super(`装不齐不上架:缺工具调用契约 ${missing.join('、')}`);
    this.name = 'ToolNotDeclaredError';
  }
}

/** 库内两维管理:业务分类(一级,组织自定)× 活动类型(标准 / 案例)—— 两维平级、相互独立 */
export type ActivityCard = {
  readonly activityId: string;
  readonly name: string;
  readonly category: string;
  readonly packageVersions: readonly PackageVersion[];
  readonly assetVersions: readonly AssetVersion[];
  readonly enabled: boolean;
};

/** 编排导出的依赖文件 —— 清单骨架:契约区 + 声明区(OS 11.1 第 2 步) */
export type DependencyFile = {
  readonly activityId: string;
  readonly contract: ActivityManifest['contract'];
  readonly declarations: ActivityManifest['declarations'];
  readonly compileOptions: { readonly sdkVersion: string; readonly format: 'esm'; readonly single: true };
};

export type ActivityRegistryService = {
  /** 安装两审:静态审读清单,回放审重演历史 */
  install(manifest: ActivityManifest, artifact: string): Promise<InstallVerdict>;
  list(): Promise<ActivityCard[]>;
  get(activityId: string): Promise<ActivityCard | undefined>;
  setEnabled(activityId: string, enabled: boolean): Promise<void>;
  uninstall(activityId: string): Promise<void>;

  /** 任务装载 = 包版本 + 各资产当前生效版,全部入信封 */
  loadEnvelope(activityId: string): Promise<LoadEnvelope>;
  manifestOf(activityId: string, packageVersion?: string): Promise<ActivityManifest>;

  /** 进化管线:候选 → 回放 → 人放行 → 生效;可回退 */
  proposeIncrement(input: {
    activityId: string;
    kind: AssetKind;
    diff: string;
    evidenceEntryIds: readonly string[];
  }): Promise<{ incrementId: string; state: IncrementState }>;
  replayIncrement(incrementId: string, cases: readonly ReplayCase[]): Promise<ReplayVerdict>;
  releaseIncrement(incrementId: string, by: string): Promise<AssetVersion>;
  rejectIncrement(incrementId: string, reason: string): Promise<void>;
  /** 行为回退 = 版本回退(显式治理动作) */
  rollbackAsset(activityId: string, kind: AssetKind, toVersion: number): Promise<AssetVersion>;
};