export type CourseStageId = string;
export type CourseDeliverableType = 'markdown' | 'html' | 'code' | 'report';

export const PROJECT_TEMPLATE_SCHEMA_VERSION = 1;
export const projectTemplateIds = ['standard-dev', 'youth-ai-course', 'web-mini-game-course'] as const;

export type ProjectTemplateId = (typeof projectTemplateIds)[number];
export type ProjectTemplateCapabilityKey = 'chat' | 'course' | 'publish' | 'gameDevelopment';
export type ProjectTemplateValidationResult =
  | { ok: true; snapshot: ProjectTemplateSnapshot }
  | { ok: false; error: string };

export const gameDevelopmentRoleIds = ['gameplay', 'game-dev', 'game-release'] as const;
export type GameDevelopmentRoleId = (typeof gameDevelopmentRoleIds)[number];

export type ProjectTemplateSnapshot = {
  schemaVersion: 1;
  template: {
    id: ProjectTemplateId;
    version: number;
    title: string;
    description: string;
    createdAt: string;
  };
  capabilities: {
    chat: ProjectTemplateChatCapability;
    course: ProjectTemplateCourseCapability;
    publish: ProjectTemplatePublishCapability;
    scaffold?: ProjectTemplateScaffoldCapability;
    gameDevelopment?: ProjectTemplateGameDevelopmentCapability;
  };
};

export type ProjectTemplateChatCapability = {
  enabled: boolean;
  defaultRoute: '/opencode-chat' | '/subagents';
};

export type ProjectTemplateCourseCapability =
  | { enabled: false }
  | {
      enabled: true;
      title: string;
      slots: ProjectTemplateCourseSlot[];
      stages: ProjectTemplateCourseStage[];
    };

export type ProjectTemplatePublishCapability =
  | { enabled: false }
  | {
      enabled: true;
      provider: 'works-square';
    };

export type ProjectTemplateScaffoldCapability =
  | { enabled: false }
  | {
      enabled: true;
      kind: 'phaser-2d-casual';
      entryFile: 'src/main.ts';
      startCommand: 'pnpm dev';
      packageManager: 'pnpm';
    };

export type ProjectTemplateGameDevelopmentCapability =
  | { enabled: false }
  | {
      enabled: true;
      engine: 'phaser3';
      requiredSkillIds: string[];
      requiredRoleIds: GameDevelopmentRoleId[];
      designDocument: 'GDD.md';
      taskDocument: 'TASKS.md';
      collaborationMode: 'pair';
    };

export type ProjectTemplateCourseSlot = {
  id: CourseStageId;
  title: string;
  agentName: string;
  agentRole: string;
  goal: string;
  recommendedAgentProfile: ProjectTemplateRecommendedAgentProfile;
};

export type ProjectTemplateCourseStage = {
  id: CourseStageId;
  order: number;
  title: string;
  agentName: string;
  agentRole: string;
  goal: string;
  task: string;
  deliverableTitle: string;
  deliverableType: CourseDeliverableType;
  deliverableSummary: string;
  acceptanceCriteria: string[];
  handoffTarget: CourseStageId | null;
};

export type ProjectTemplateRecommendedAgentProfile = {
  roleId: CourseStageId;
  displayName: string;
  notes: string[];
};

const youthCourseStages: ProjectTemplateCourseStage[] = [
  {
    id: 'pm',
    order: 1,
    title: '想法与计划',
    agentName: '项目经理',
    agentRole: '思路整理',
    goal: '把一个模糊想法收敛成可以执行的小项目。',
    task: '讨论项目目标、核心用户、第一版范围、任务清单和验收标准。',
    deliverableTitle: '项目计划.md',
    deliverableType: 'markdown',
    deliverableSummary: '项目目标、核心用户、第一版范围、任务清单、验收标准。',
    acceptanceCriteria: [
      '有明确项目目标',
      '有核心用户和使用场景',
      '有第一版范围',
      '有任务清单',
      '有验收标准',
    ],
    handoffTarget: 'product',
  },
  {
    id: 'product',
    order: 2,
    title: '原型 Demo',
    agentName: '产品经理',
    agentRole: '原型设计',
    goal: '把项目计划变成可以演示的产品流程。',
    task: '基于项目计划定义页面、按钮、交互、边界状态和 Demo 交付说明，不依赖最终视觉规范。',
    deliverableTitle: '原型Demo.html',
    deliverableType: 'html',
    deliverableSummary: '页面流程、关键交互、状态说明、基础可用性说明、可演示 Demo。',
    acceptanceCriteria: [
      '有完整用户流程',
      '有页面清单',
      '有关键交互',
      '有边界状态',
      '有基础可用性说明',
      '能在 1-3 分钟内演示',
    ],
    handoffTarget: 'designer',
  },
  {
    id: 'designer',
    order: 3,
    title: '视觉设计',
    agentName: '美术设计师',
    agentRole: '视觉设计',
    goal: '基于项目计划和原型 Demo，形成清楚、可实现的 UI/UX 视觉规范。',
    task: '基于项目计划和原型 Demo 明确风格、色彩、排版、布局、组件规则、响应式和可访问性要求。',
    deliverableTitle: '设计规范.md',
    deliverableType: 'markdown',
    deliverableSummary: '基于原型的设计方向、色彩规则、排版层级、页面布局、组件状态、UI/UX 质量检查。',
    acceptanceCriteria: [
      '有设计方向',
      '有色彩和排版规则',
      '有布局规则',
      '有组件状态',
      '有响应式和可访问性要求',
      '有 UI/UX 质量检查',
    ],
    handoffTarget: 'dev',
  },
  {
    id: 'dev',
    order: 4,
    title: '代码开发',
    agentName: '开发工程师',
    agentRole: '代码开发',
    goal: '把原型实现成可以运行和检查的软件作品。',
    task: '完成数据/接口设计、代码实现、测试验证和剩余风险说明。',
    deliverableTitle: '代码实现与测试报告.md',
    deliverableType: 'code',
    deliverableSummary: '实现文件、数据接口、测试命令、UI/UX 检查结果、风险说明。',
    acceptanceCriteria: [
      '有代码实现说明',
      '有数据或接口说明',
      '有测试或检查结果',
      '有 UI/UX 检查结果',
      '有剩余风险',
      '有给宣发和部署的事实说明',
    ],
    handoffTarget: 'marketing',
  },
  {
    id: 'marketing',
    order: 5,
    title: '宣传展示',
    agentName: '市场运营',
    agentRole: '宣传展示',
    goal: '把作品讲清楚，让别人理解它解决了什么问题。',
    task: '准备定位、一句话介绍、核心卖点、展示文案和讲解提纲。',
    deliverableTitle: '宣发材料.md',
    deliverableType: 'markdown',
    deliverableSummary: '宣传定位、目标受众、展示文案、宣讲提纲、证据清单。',
    acceptanceCriteria: [
      '有目标受众',
      '有一句话介绍',
      '有核心卖点',
      '文案不夸大',
      '有展示文案或讲解提纲',
      '有证据清单或需要补充的证据',
    ],
    handoffTarget: 'deploy',
  },
  {
    id: 'deploy',
    order: 6,
    title: '发布部署',
    agentName: '部署工程师',
    agentRole: '发布部署',
    goal: '确认作品可以通过 Docker 构建、启动、打包并通过作品广场上传接口提交。',
    task: '创建或维护 Dockerfile 和 docker-compose.yml，检查 Docker 构建状态，把当前项目打成 zip 包，通过作品广场上传接口提交，并记录发布目标、发布步骤、回滚说明和作品广场提交清单。',
    deliverableTitle: '部署报告.md',
    deliverableType: 'report',
    deliverableSummary: 'Dockerfile、docker-compose.yml、发布目标、准备情况、Docker 执行命令、zip 包路径、作品广场上传接口结果、发布步骤、回滚步骤。',
    acceptanceCriteria: [
      '有明确发布目标',
      '有 Dockerfile',
      '有 docker-compose.yml',
      '有 Docker 构建或检查结果',
      '有 zip 包路径',
      '有作品广场上传接口结果',
      '有发布步骤',
      '有回滚步骤',
      '没有隐私或密钥风险',
      '没有失败/阻塞或未验证的必需发布证据',
    ],
    handoffTarget: null,
  },
];

const youthCourseSlots: ProjectTemplateCourseSlot[] = youthCourseStages.map((stage) => ({
  id: stage.id,
  title: stage.title,
  agentName: stage.agentName,
  agentRole: stage.agentRole,
  goal: stage.goal,
  recommendedAgentProfile: {
    roleId: stage.id,
    displayName: stage.agentName,
    notes: [],
  },
}));

const webMiniGameCourseStages: ProjectTemplateCourseStage[] = [
  {
    id: 'gameplay',
    order: 1,
    title: '玩法规划',
    agentName: '玩法策划',
    agentRole: '玩法策划',
    goal: '把用户的游戏想法收敛成可验证、能持续维护的玩法设计。',
    task: '定义玩家、核心循环、胜负条件、关卡节奏和第一版范围，并写清当前可玩目标。',
    deliverableTitle: 'GDD.md',
    deliverableType: 'markdown',
    deliverableSummary: 'GDD.md 中的游戏目标、玩法循环、系统和第一版边界，以及 TASKS.md 中的当前可玩目标。',
    acceptanceCriteria: [
      '明确游戏目标',
      '说明目标玩家',
      '解释核心玩法循环',
      '列出胜利和失败条件',
      '描述关卡节奏',
      '收敛第一版范围',
      '把当前可玩目标和可观察验收写入 TASKS.md',
    ],
    handoffTarget: 'assets',
  },
  {
    id: 'assets',
    order: 2,
    title: '素材搜索',
    agentName: '素材规划师',
    agentRole: '素材规划师',
    goal: '搜索可复用的游戏素材，并记录仍然缺少的内容。',
    task: '列出视觉、音频、UI 和动画素材需求，记录来源、授权、尺寸和备用方案。',
    deliverableTitle: 'ASSET_PLAN.md',
    deliverableType: 'markdown',
    deliverableSummary: '素材清单、来源、授权、技术限制和备用方案。',
    acceptanceCriteria: [
      '列出必需素材',
      '记录用户明确确认选定或明确授权代选的原话',
      '当前目标必需素材全部为 selected 或 approved-placeholder',
      '确认清单没有 unresolved、candidate、missing 或 TODO 项',
      '记录来源或获取路径',
      '说明授权或使用限制',
      '包含技术要求',
      '覆盖视觉一致性',
      '包含备用方案',
    ],
    handoffTarget: 'game-dev',
  },
  {
    id: 'game-dev',
    order: 3,
    title: '游戏开发',
    agentName: '游戏开发师',
    agentRole: '游戏开发师',
    goal: '根据玩法设计和素材计划做出可在浏览器试玩的小游戏。',
    task: '一次推进一个玩家可感知的完整增量，实现核心玩法循环，接入计划素材，并在真实浏览器中试玩。',
    deliverableTitle: 'PLAYABLE_GAME.md',
    deliverableType: 'code',
    deliverableSummary: '可试玩实现、玩法说明、已接入素材和试玩结果。',
    acceptanceCriteria: [
      '做出可试玩的 2D 小游戏',
      '实现核心玩法循环',
      '使用计划素材或占位素材',
      '可以在浏览器运行',
      '包含来自真实浏览器的试玩证据',
      '说明剩余问题或下一步',
    ],
    handoffTarget: 'game-release',
  },
  {
    id: 'game-release',
    order: 4,
    title: '发布打包',
    agentName: '游戏发布官',
    agentRole: '游戏发布官',
    goal: '准备构建结果、试玩记录和发布检查清单。',
    task: '运行生产构建和预览，在真实浏览器中完成核心循环与重开检查；记录 Compose 配置、构建、启动、动态端口、HTTP 冒烟和清理结果，并说明发布与回滚。',
    deliverableTitle: 'RELEASE_CHECKLIST.md',
    deliverableType: 'report',
    deliverableSummary: '构建结果、试玩检查、运行说明、发布检查项和已知风险；包括 ZIP 根目录、大小、文件数、路径安全、重复项和符号链接、works-publish.json 以及发布与回滚。',
    acceptanceCriteria: [
      '包含 pnpm build 命令和成功结果',
      '包含真实浏览器试玩和重开记录',
      '包含运行说明',
      '包含发布检查项',
      '包含已知风险或问题',
      '没有失败/阻塞或未验证的必需发布证据',
    ],
    handoffTarget: 'game-showcase',
  },
  {
    id: 'game-showcase',
    order: 5,
    title: '宣传展示',
    agentName: '游戏宣传官',
    agentRole: '宣传展示',
    goal: '把完成的小游戏整理成可以给别人理解和试玩的展示材料。',
    task: '准备一句话介绍、核心亮点、试玩入口说明、截图/录屏建议、展示文案和推广发布建议。',
    deliverableTitle: 'SHOWCASE_PACKAGE.md',
    deliverableType: 'markdown',
    deliverableSummary: '小游戏定位、一句话介绍、核心亮点、试玩说明、展示文案、截图/录屏清单和推广建议。',
    acceptanceCriteria: [
      '包含目标受众',
      '包含一句话介绍',
      '列出核心亮点',
      '说明如何试玩',
      '包含截图或录屏建议',
      '包含可直接使用的展示文案',
    ],
    handoffTarget: null,
  },
];

const webMiniGameCourseSlots: ProjectTemplateCourseSlot[] = webMiniGameCourseStages.map((stage) => ({
  id: stage.id,
  title: stage.title,
  agentName: stage.agentName,
  agentRole: stage.agentRole,
  goal: stage.goal,
  recommendedAgentProfile: {
    roleId: stage.id,
    displayName: stage.agentName,
    notes: [],
  },
}));

export const builtInProjectTemplates: ProjectTemplateSnapshot[] = [
  {
    schemaVersion: 1,
    template: {
      id: 'standard-dev',
      version: 1,
      title: '普通开发项目',
      description: '用于日常代码开发和普通会话，不显示课程角色栏。',
      createdAt: '1970-01-01T00:00:00.000Z',
    },
    capabilities: {
      chat: { enabled: true, defaultRoute: '/opencode-chat' },
      course: { enabled: false },
      publish: { enabled: false },
      scaffold: { enabled: false },
    },
  },
  {
    schemaVersion: 1,
    template: {
      id: 'youth-ai-course',
      version: 1,
      title: 'AI 伙伴课程项目',
      description: '提供课程角色、阶段导航和作品发布信息，所有阶段均可随时进入。',
      createdAt: '1970-01-01T00:00:00.000Z',
    },
    capabilities: {
      chat: { enabled: true, defaultRoute: '/opencode-chat' },
      course: {
        enabled: true,
        title: 'AI 伙伴课程路径',
        slots: youthCourseSlots,
        stages: youthCourseStages,
      },
      publish: { enabled: true, provider: 'works-square' },
      scaffold: { enabled: false },
    },
  },
  {
    schemaVersion: 1,
    template: {
      id: 'web-mini-game-course',
      version: 3,
      title: 'Web 小游戏课程项目',
      description: '启用结对式 Web 小游戏课程、游戏设计任务文档和 Phaser 3 脚手架支持。',
      createdAt: '1970-01-01T00:00:00.000Z',
    },
    capabilities: {
      chat: { enabled: true, defaultRoute: '/opencode-chat' },
      course: {
        enabled: true,
        title: 'Web 小游戏制作路径',
        slots: webMiniGameCourseSlots,
        stages: webMiniGameCourseStages,
      },
      publish: { enabled: true, provider: 'works-square' },
      scaffold: {
        enabled: true,
        kind: 'phaser-2d-casual',
        entryFile: 'src/main.ts',
        startCommand: 'pnpm dev',
        packageManager: 'pnpm',
      },
      gameDevelopment: {
        enabled: true,
        engine: 'phaser3',
        requiredSkillIds: ['nianxxgame-skill'],
        requiredRoleIds: ['gameplay', 'game-dev', 'game-release'],
        designDocument: 'GDD.md',
        taskDocument: 'TASKS.md',
        collaborationMode: 'pair',
      },
    },
  },
];

export function isProjectTemplateId(value: unknown): value is ProjectTemplateId {
  return typeof value === 'string' && projectTemplateIds.includes(value as ProjectTemplateId);
}

export function isProjectTemplateCourseStageId(value: unknown): value is CourseStageId {
  return typeof value === 'string' && value.trim().length > 0;
}

export function createProjectTemplateSnapshot(
  templateId: ProjectTemplateId,
  now = new Date().toISOString(),
): ProjectTemplateSnapshot {
  const source = builtInProjectTemplates.find((template) => template.template.id === templateId);
  if (!source) {
    throw new Error(`Unknown project template: ${templateId}`);
  }

  return {
    ...structuredClone(source),
    template: {
      ...source.template,
      createdAt: now,
    },
  };
}

export function hasProjectCapability(
  snapshot: ProjectTemplateSnapshot | null | undefined,
  key: ProjectTemplateCapabilityKey,
): boolean {
  return Boolean(snapshot?.capabilities[key]?.enabled);
}

export function getProjectTemplateRequiredSkillIds(
  snapshot: ProjectTemplateSnapshot | null | undefined,
  roleId: string | null | undefined,
): string[] {
  const gameDevelopment = snapshot?.capabilities.gameDevelopment;
  if (!gameDevelopment?.enabled || !roleId || !gameDevelopment.requiredRoleIds.includes(roleId as GameDevelopmentRoleId)) {
    return [];
  }
  return [...gameDevelopment.requiredSkillIds];
}

export function getProjectTemplateDisplayLabel(snapshot: ProjectTemplateSnapshot | null | undefined): string {
  return snapshot?.template.title ?? '未选择模板';
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
}

function pushMissing(errors: string[], condition: boolean, field: string) {
  if (!condition) {
    errors.push(field);
  }
}

function isCourseDeliverableType(value: unknown): value is CourseDeliverableType {
  return value === 'markdown' || value === 'html' || value === 'code' || value === 'report';
}

function isRecommendedAgentProfile(value: unknown): value is ProjectTemplateRecommendedAgentProfile {
  return (
    isRecord(value)
    && isProjectTemplateCourseStageId(value.roleId)
    && typeof value.displayName === 'string'
    && value.displayName.trim().length > 0
    && Array.isArray(value.notes)
    && value.notes.every((note) => typeof note === 'string')
  );
}

function isProjectTemplateScaffoldCapability(value: unknown): value is ProjectTemplateScaffoldCapability {
  if (!isRecord(value) || typeof value.enabled !== 'boolean') {
    return false;
  }
  if (value.enabled === false) {
    return true;
  }
  return value.kind === 'phaser-2d-casual'
    && value.entryFile === 'src/main.ts'
    && value.startCommand === 'pnpm dev'
    && value.packageManager === 'pnpm';
}

function isProjectTemplateGameDevelopmentCapability(
  value: unknown,
): value is ProjectTemplateGameDevelopmentCapability {
  if (!isRecord(value) || typeof value.enabled !== 'boolean') {
    return false;
  }
  if (value.enabled === false) {
    return true;
  }

  const requiredSkillIds = Array.isArray(value.requiredSkillIds) ? value.requiredSkillIds : [];
  const requiredRoleIds = Array.isArray(value.requiredRoleIds) ? value.requiredRoleIds : [];
  return value.engine === 'phaser3'
    && requiredSkillIds.length > 0
    && requiredSkillIds.every((skillId) => (
      typeof skillId === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/.test(skillId)
    ))
    && new Set(requiredSkillIds).size === requiredSkillIds.length
    && requiredRoleIds.length > 0
    && requiredRoleIds.every((roleId) => (
      typeof roleId === 'string' && gameDevelopmentRoleIds.includes(roleId as GameDevelopmentRoleId)
    ))
    && new Set(requiredRoleIds).size === requiredRoleIds.length
    && value.designDocument === 'GDD.md'
    && value.taskDocument === 'TASKS.md'
    && value.collaborationMode === 'pair';
}

function collectBuiltInContractMismatches(
  actual: unknown,
  expected: unknown,
  path: string,
  mismatches: Set<string>,
): void {
  if (Array.isArray(expected)) {
    if (!Array.isArray(actual) || actual.length !== expected.length) {
      mismatches.add(path);
      return;
    }
    for (let index = 0; index < expected.length; index += 1) {
      collectBuiltInContractMismatches(actual[index], expected[index], `${path}[${index}]`, mismatches);
    }
    return;
  }

  if (isRecord(expected)) {
    if (!isRecord(actual)) {
      mismatches.add(path);
      return;
    }

    const actualKeys = Object.keys(actual).sort();
    const expectedKeys = Object.keys(expected).sort();
    if (actualKeys.join('\0') !== expectedKeys.join('\0')) {
      mismatches.add(path);
    }

    for (const key of expectedKeys) {
      const nextPath = path ? `${path}.${key}` : key;
      if (nextPath === 'template.createdAt') {
        continue;
      }
      collectBuiltInContractMismatches(actual[key], expected[key], nextPath, mismatches);
    }
    return;
  }

  if (actual !== expected) {
    mismatches.add(path);
  }
}

const LEGACY_YOUTH_DEPLOY_STAGE: ProjectTemplateCourseStage = {
  id: 'deploy',
  order: 6,
  title: '发布部署',
  agentName: '部署工程师',
  agentRole: '发布部署',
  goal: '确认作品可以通过 Docker 构建、启动、打包并通过作品广场上传接口提交。',
  task: '创建或维护 Dockerfile 和 docker-compose.yml，检查 Docker 构建状态，把当前项目打成 zip 包，通过作品广场上传接口提交，并记录发布目标、发布步骤、回滚说明和作品广场提交清单。',
  deliverableTitle: '部署报告.md',
  deliverableType: 'report',
  deliverableSummary: 'Dockerfile、docker-compose.yml、发布目标、准备情况、Docker 执行命令、zip 包路径、作品广场上传接口结果、发布步骤、回滚步骤。',
  acceptanceCriteria: [
    '有明确发布目标',
    '有 Dockerfile',
    '有 docker-compose.yml',
    '有 Docker 构建或检查结果',
    '有 zip 包路径',
    '有作品广场上传接口结果',
    '有发布步骤',
    '有回滚步骤',
    '没有隐私或密钥风险',
  ],
  handoffTarget: null,
};

const LEGACY_GAME_RELEASE_STAGE: ProjectTemplateCourseStage = {
  id: 'game-release',
  order: 4,
  title: '发布打包',
  agentName: '游戏发布官',
  agentRole: '游戏发布官',
  goal: '准备构建结果、试玩记录和发布检查清单。',
  task: '记录如何运行游戏、试玩了什么，以及发布前后需要检查哪些项目。',
  deliverableTitle: 'RELEASE_CHECKLIST.md',
  deliverableType: 'report',
  deliverableSummary: '构建结果、试玩检查、运行说明、发布检查项和已知风险。',
  acceptanceCriteria: [
    '包含构建命令和结果',
    '包含试玩记录',
    '包含运行说明',
    '包含发布检查项',
    '包含已知风险或问题',
  ],
  handoffTarget: 'game-showcase',
};

type LegacyPublishTemplateId = 'youth-ai-course' | 'web-mini-game-course';

function createExpectedLegacyPublishContractSnapshot(
  templateId: LegacyPublishTemplateId,
  createdAt: string,
  version: number,
): ProjectTemplateSnapshot {
  const expected = createProjectTemplateSnapshot(templateId, createdAt);
  expected.template.version = version;
  if (!expected.capabilities.course.enabled) return expected;
  const legacyStage = templateId === 'youth-ai-course' ? LEGACY_YOUTH_DEPLOY_STAGE : LEGACY_GAME_RELEASE_STAGE;
  expected.capabilities.course.stages = expected.capabilities.course.stages.map((stage) => (
    stage.id === legacyStage.id ? structuredClone(legacyStage) : stage
  ));
  expected.capabilities.course.slots = expected.capabilities.course.slots.map((slot) => (
    slot.id === legacyStage.id ? { ...slot, goal: legacyStage.goal } : slot
  ));
  return expected;
}

function isExactSnapshotMatch(candidate: Record<string, unknown>, expected: ProjectTemplateSnapshot): boolean {
  const mismatches = new Set<string>();
  collectBuiltInContractMismatches(candidate, expected, '', mismatches);
  return mismatches.size === 0;
}

function getLegacySnapshotMeta(
  value: Record<string, unknown>,
  templateId: LegacyPublishTemplateId,
): { createdAt: string; version: number } | null {
  const template = isRecord(value.template) ? value.template : {};
  const allowedVersions = templateId === 'web-mini-game-course' ? [1, 3] : [1];
  if (template.id !== templateId || !allowedVersions.includes(Number(template.version)) || typeof template.createdAt !== 'string') return null;
  return { createdAt: template.createdAt, version: Number(template.version) };
}

function isLegacyPublishContractSnapshot(value: Record<string, unknown>, templateId: LegacyPublishTemplateId): boolean {
  const meta = getLegacySnapshotMeta(value, templateId);
  return meta !== null && isExactSnapshotMatch(value, createExpectedLegacyPublishContractSnapshot(templateId, meta.createdAt, meta.version));
}

function createExpectedWebMiniGameSnapshotBeforeShowcase(
  createdAt: string,
  releaseContract: 'current' | 'legacy',
  version: number,
): ProjectTemplateSnapshot {
  const expected = releaseContract === 'legacy'
    ? createExpectedLegacyPublishContractSnapshot('web-mini-game-course', createdAt, version)
    : createProjectTemplateSnapshot('web-mini-game-course', createdAt);
  expected.template.version = version;
  if (expected.capabilities.course.enabled) {
    expected.capabilities.course.stages = expected.capabilities.course.stages.filter((stage) => stage.id !== 'game-showcase');
    expected.capabilities.course.slots = expected.capabilities.course.slots.filter((slot) => slot.id !== 'game-showcase');
    const releaseStage = expected.capabilities.course.stages.find((stage) => stage.id === 'game-release');
    if (releaseStage) releaseStage.handoffTarget = null;
  }
  return expected;
}

function isLegacyWebMiniGameSnapshotBeforeShowcase(value: Record<string, unknown>): boolean {
  const meta = getLegacySnapshotMeta(value, 'web-mini-game-course');
  return meta !== null && isExactSnapshotMatch(value, createExpectedWebMiniGameSnapshotBeforeShowcase(meta.createdAt, 'current', meta.version));
}

function isLegacyWebMiniGameSnapshotBeforeShowcaseWithLegacyRelease(value: Record<string, unknown>): boolean {
  const meta = getLegacySnapshotMeta(value, 'web-mini-game-course');
  return meta !== null && isExactSnapshotMatch(value, createExpectedWebMiniGameSnapshotBeforeShowcase(meta.createdAt, 'legacy', meta.version));
}

function normalizeProjectTemplateSnapshotForCompatibility(value: Record<string, unknown>): Record<string, unknown> {
  const template = isRecord(value.template) ? value.template : {};
  const capabilities = isRecord(value.capabilities) ? value.capabilities : {};
  const chat = isRecord(capabilities.chat) ? capabilities.chat : {};
  const builtInTemplate = builtInProjectTemplates.find((candidate) => (
    candidate.template.id === template.id && candidate.template.version === template.version
  ));

  let normalized: Record<string, unknown> | null = null;

  if (template.id === 'youth-ai-course' && template.version === 1 && chat.defaultRoute === '/subagents') {
    normalized = structuredClone(value) as Record<string, unknown>;
    const normalizedCapabilities = isRecord(normalized.capabilities) ? normalized.capabilities : {};
    const normalizedChat = isRecord(normalizedCapabilities.chat) ? normalizedCapabilities.chat : {};
    normalizedChat.defaultRoute = '/opencode-chat';
  }

  const expectedScaffold = builtInTemplate?.capabilities.scaffold;
  if (expectedScaffold?.enabled === false && capabilities.scaffold === undefined) {
    normalized ??= structuredClone(value) as Record<string, unknown>;
    const normalizedCapabilities = isRecord(normalized.capabilities) ? normalized.capabilities : {};
    normalizedCapabilities.scaffold = { enabled: false };
  }

  const candidate = normalized ?? value;
  const candidateTemplate = isRecord(candidate.template) ? candidate.template : {};
  const createdAt = typeof candidateTemplate.createdAt === 'string' ? candidateTemplate.createdAt : null;
  if (createdAt !== null) {
    if (isLegacyPublishContractSnapshot(candidate, 'youth-ai-course')) {
      return createProjectTemplateSnapshot('youth-ai-course', createdAt);
    }
    if (
      isLegacyPublishContractSnapshot(candidate, 'web-mini-game-course')
      || isLegacyWebMiniGameSnapshotBeforeShowcase(candidate)
      || isLegacyWebMiniGameSnapshotBeforeShowcaseWithLegacyRelease(candidate)
    ) {
      return createProjectTemplateSnapshot('web-mini-game-course', createdAt);
    }
  }

  return candidate;
}

export function validateProjectTemplateSnapshot(value: unknown): ProjectTemplateValidationResult {
  const errors: string[] = [];

  if (!isRecord(value)) {
    return { ok: false, error: 'snapshot must be an object' };
  }

  const normalizedValue = normalizeProjectTemplateSnapshotForCompatibility(value);

  pushMissing(errors, normalizedValue.schemaVersion === PROJECT_TEMPLATE_SCHEMA_VERSION, 'schemaVersion');

  const template = isRecord(normalizedValue.template) ? normalizedValue.template : {};
  pushMissing(errors, isProjectTemplateId(template.id), 'template.id');
  pushMissing(errors, Number.isInteger(template.version) && Number(template.version) > 0, 'template.version');
  pushMissing(errors, typeof template.title === 'string' && template.title.trim().length > 0, 'template.title');
  pushMissing(
    errors,
    typeof template.description === 'string' && template.description.trim().length > 0,
    'template.description',
  );
  pushMissing(
    errors,
    typeof template.createdAt === 'string' && template.createdAt.trim().length > 0,
    'template.createdAt',
  );

  const capabilities = isRecord(normalizedValue.capabilities) ? normalizedValue.capabilities : {};
  const chat = isRecord(capabilities.chat) ? capabilities.chat : {};
  const course = isRecord(capabilities.course) ? capabilities.course : {};
  const publish = isRecord(capabilities.publish) ? capabilities.publish : {};
  const scaffold = capabilities.scaffold;
  const gameDevelopment = capabilities.gameDevelopment;

  pushMissing(errors, typeof chat.enabled === 'boolean', 'capabilities.chat.enabled');
  pushMissing(errors, typeof course.enabled === 'boolean', 'capabilities.course.enabled');
  pushMissing(errors, typeof publish.enabled === 'boolean', 'capabilities.publish.enabled');
  if (scaffold !== undefined) {
    pushMissing(errors, isProjectTemplateScaffoldCapability(scaffold), 'capabilities.scaffold');
  }
  if (gameDevelopment !== undefined) {
    pushMissing(
      errors,
      isProjectTemplateGameDevelopmentCapability(gameDevelopment),
      'capabilities.gameDevelopment',
    );
  }

  if (chat.enabled === true) {
    pushMissing(
      errors,
      chat.defaultRoute === '/opencode-chat' || chat.defaultRoute === '/subagents',
      'capabilities.chat.defaultRoute',
    );
  }

  if (course.enabled === true) {
    pushMissing(
      errors,
      typeof course.title === 'string' && course.title.trim().length > 0,
      'capabilities.course.title',
    );

    const stages = Array.isArray(course.stages) ? course.stages : [];
    const slots = Array.isArray(course.slots) ? course.slots : [];

    pushMissing(errors, stages.length > 0, 'capabilities.course.stages');
    pushMissing(errors, slots.length > 0, 'capabilities.course.slots');

    const stageIds = new Set<string>();
    for (const stage of stages) {
      if (!isRecord(stage)) {
        errors.push('capabilities.course.stages.item');
        continue;
      }

      const stageId = typeof stage.id === 'string' ? stage.id.trim() : '';
      pushMissing(errors, isProjectTemplateCourseStageId(stage.id) && !stageIds.has(stageId), 'capabilities.course.stages.id');
      pushMissing(errors, Number.isInteger(stage.order) && Number(stage.order) > 0, 'capabilities.course.stages.order');
      pushMissing(errors, typeof stage.title === 'string' && stage.title.trim().length > 0, 'capabilities.course.stages.title');
      pushMissing(errors, typeof stage.agentName === 'string' && stage.agentName.trim().length > 0, 'capabilities.course.stages.agentName');
      pushMissing(errors, typeof stage.agentRole === 'string' && stage.agentRole.trim().length > 0, 'capabilities.course.stages.agentRole');
      pushMissing(errors, typeof stage.goal === 'string' && stage.goal.trim().length > 0, 'capabilities.course.stages.goal');
      pushMissing(errors, typeof stage.task === 'string' && stage.task.trim().length > 0, 'capabilities.course.stages.task');
      pushMissing(errors, typeof stage.deliverableTitle === 'string' && stage.deliverableTitle.trim().length > 0, 'capabilities.course.stages.deliverableTitle');
      pushMissing(errors, isCourseDeliverableType(stage.deliverableType), 'capabilities.course.stages.deliverableType');
      pushMissing(errors, typeof stage.deliverableSummary === 'string' && stage.deliverableSummary.trim().length > 0, 'capabilities.course.stages.deliverableSummary');
      pushMissing(
        errors,
        Array.isArray(stage.acceptanceCriteria)
          && stage.acceptanceCriteria.length > 0
          && stage.acceptanceCriteria.every(
            (criterion) => typeof criterion === 'string' && criterion.trim().length > 0,
          ),
        'capabilities.course.stages.acceptanceCriteria',
      );
      pushMissing(
        errors,
        stage.handoffTarget === null || isProjectTemplateCourseStageId(stage.handoffTarget),
        'capabilities.course.stages.handoffTarget',
      );

      if (stageId) {
        stageIds.add(stageId);
      }
    }

    const slotIds = new Set<string>();
    for (const slot of slots) {
      if (!isRecord(slot)) {
        errors.push('capabilities.course.slots.item');
        continue;
      }

      const slotId = typeof slot.id === 'string' ? slot.id.trim() : '';
      pushMissing(errors, isProjectTemplateCourseStageId(slot.id) && !slotIds.has(slotId), 'capabilities.course.slots.id');
      pushMissing(errors, typeof slot.title === 'string' && slot.title.trim().length > 0, 'capabilities.course.slots.title');
      pushMissing(errors, typeof slot.agentName === 'string' && slot.agentName.trim().length > 0, 'capabilities.course.slots.agentName');
      pushMissing(errors, typeof slot.agentRole === 'string' && slot.agentRole.trim().length > 0, 'capabilities.course.slots.agentRole');
      pushMissing(errors, typeof slot.goal === 'string' && slot.goal.trim().length > 0, 'capabilities.course.slots.goal');
      pushMissing(errors, isRecommendedAgentProfile(slot.recommendedAgentProfile), 'capabilities.course.slots.recommendedAgentProfile');

      if (slotId) {
        slotIds.add(slotId);
      }
    }

    pushMissing(
      errors,
      slotIds.size === stageIds.size && [...stageIds].every((stageId) => slotIds.has(stageId)),
      'capabilities.course.slotStageAlignment',
    );

  }

  if (publish.enabled === true) {
    pushMissing(errors, publish.provider === 'works-square', 'capabilities.publish.provider');
  }

  const snapshotId = isProjectTemplateId(template.id) ? template.id : null;
  const snapshotVersion = Number.isInteger(template.version) ? Number(template.version) : null;
  if (snapshotId && snapshotVersion !== null) {
    const builtInTemplate = builtInProjectTemplates.find((candidate) => (
      candidate.template.id === snapshotId && candidate.template.version === snapshotVersion
    ));
    if (!builtInTemplate) {
      errors.push(`built-in contract ${snapshotId}@${snapshotVersion}`);
    } else {
      const expectedSnapshot = createProjectTemplateSnapshot(snapshotId, String(template.createdAt ?? builtInTemplate.template.createdAt));
      const mismatches = new Set<string>();
      collectBuiltInContractMismatches(normalizedValue, expectedSnapshot, '', mismatches);
      if (mismatches.size > 0) {
        errors.push(
          `built-in contract ${snapshotId}@${snapshotVersion}: ${Array.from(mismatches)
            .filter(Boolean)
            .join(', ')}`,
        );
      }
    }
  }

  if (errors.length > 0) {
    return {
      ok: false,
      error: `Invalid project template snapshot: ${Array.from(new Set(errors)).join(', ')}`,
    };
  }

  return { ok: true, snapshot: normalizedValue as ProjectTemplateSnapshot };
}