第04章 - 核心契约-动作驱动运行时

export interface LevelModule {
  manifest: LevelManifest;
  /** 纯运行时：不碰 DOM；外壳与审计都用它 */
  createRuntime(detail: LevelDetail, opts: RuntimeOptions): LevelRuntime;
  /** 挂载画布（如有）并接上同一个 runtime；无画布关卡实现为空 */
  mount(ctx: LevelContext, runtime: LevelRuntime): Promise<void>;
  unmount(): Promise<void>;
  pause(): void;
  resume(): void;
}

export type LevelAction = {
  [K in keyof ActionPayloadMap]: { type: K; payload: ActionPayloadMap[K] };
}[keyof ActionPayloadMap];

export interface ActionPayloadMap {
  'pattern/inspect': { index: number };
  'pattern/setCycle': { cycle: string[]; transform: PatternTransform };
  /** 可选带规则：预览只写"预测"，不该把已提交状态打掉（玩家常先提交再点预览）。 */
  'pattern/preview': { cycle?: string[]; transform?: PatternTransform };
  'pattern/commit': Record<string, never>;

  'construct/place': { piece: PiecePlacementInput };
  'rule/place': { block: ProgramBlock; at: number };
  'knob/set': { key: string; value: number };
  'probe/sample': { n?: number };
  'counter/edit': { patch: CounterPatch };

  /** 宿主统一动作：所有模板都必须处理 */
  'run': Record<string, never>;
  'submit': Record<string, never>;
  'reset': Record<string, never>;
}

function toolOf(type: string): ToolId | null {
  const prefix = type.split('/')[0];
  return (TOOL_IDS as readonly string[]).includes(prefix) ? (prefix as ToolId) : null;
}

export interface LevelRuntime {
  readonly detail: LevelDetail;
  snapshot(): RunSnapshot;
  subscribe(listener: (snapshot: RunSnapshot) => void): () => void;
  dispatch(action: LevelAction): Promise<ActionResult>;
  /** 自动通关：内部仍逐条 dispatch，不允许直接改状态 */
  autoplay(): Promise<ActionResult>;
  reset(): Promise<void>;
}

// 判定顺序（docs/01 §5.1 的修订版 + docs/12 P0-1）：
// 1) 一件产物都没有：给出缺失证据（audit A1 要求无工具提交必须被拒且带缺失证据）；
// 2) 有产物：先跑结构校验。真实错误必须优先于缺步骤提示，
//    以前 missingEvidence 在前，把 network/schedule/frontier 写好的失败反馈全顶掉了；
// 3) 结构正确但证据步骤没走完：仍然按缺失证据处理（守住 A8 与内容门禁）。

const artifact = adapter.artifact(meta.state);
const missing = missingEvidence();

if (artifact === null) {                                   // ① 空产物
  if (missing.length === 0) return fail('还差一个可以提交的结构。');
  return { ok: true, verdict: missingVerdict(missing), snapshot: snapshot() };
}
const verdict = adapter.validate(detail, BASE_VARIANT, artifact);
if (!verdict.passed) {                                     // ② 结构错误优先上屏
  verdict.missingEvidence = missing;                       //    缺步骤降级为第二行
  recordRun('fail', verdict.failure?.class);
  return { ok: true, verdict, snapshot: snapshot() };
}
if (missing.length > 0) {                                  // ③ 结构对但步骤没走完
  return { ok: true, verdict: missingVerdict(missing), snapshot: snapshot() };
}
const transfer = transferCheck(artifact);                  // ④ 迁移门：逐个变体验一遍
if (!transfer.passed) { /* failure.class = 模板声明的迁移失败类，带 variantId */ }

async function autoplay(): Promise<ActionResult> {
  const solution = detail.solutions[0];
  if (!solution) return { ok: false, reason: 'not-ready', message: '这一关还没有黄金解。', snapshot: snapshot() };
  const actions = adapter.actionsFor(detail, BASE_VARIANT, solution.artifact);
  let submitted = false;
  let last: ActionResult = { ok: true, snapshot: snapshot() };
  for (const action of actions) {
    if (action.type === 'submit') submitted = true;
    last = await dispatch(action);       // ← 逐条走玩家的同一条路径
    if (!last.ok) return last;
  }
  if (!submitted) last = await dispatch({ type: 'submit', payload: {} });
  return last;
}

export interface RunSnapshot {
  levelId: LevelId;
  variantId: string;
  phase: 'idle' | 'observing' | 'editing' | 'running' | 'failed' | 'passed';
  artifacts: ArtifactSummary[];
  toolState: Partial<ToolStateMap>;      // 工具编辑态；未开放的工具不出现
  toolUsage: Record<ToolId, ToolUsageState>;
  checkpoints: Record<string, boolean>;
  runs: RunRecord[];                     // 最近 10 次
  lastRun?: RunRecord;
  verdict?: Verdict;
  argument?: ArgumentSnapshot;           // 只有 argue 模板会出现
  stamps: StampId[];
  revision: number;
  updatedAt: number;
}

export interface Verdict {
  passed: boolean;
  stamps: StampId[];                 // constraint / simple / transfer / argument
  failure?: FailureReport;
  missingEvidence: EvidenceRequirement[];
  metrics?: Record<string, number>;
  artifacts: ArtifactSummary[];
  /** 迁移门的逐变体结果；没有迁移门的关卡不出现 */
  variantResults?: { id: string; passed: boolean }[];
}

export interface FailureReport {
  class: string;                     // 模板定义的失败类，如 'rule-not-general'
  variantId?: string;                // 迁移门失败时指出是哪张地图
  causes: FailureCause[];            // 指向具体格子/步骤/约束/结论
}

export interface FailureCause {
  kind: 'cell' | 'step' | 'constraint' | 'variant' | 'claim' | 'sample';
  ref: string;
  messageKey: string;
  params?: Record<string, string | number>;
}

export interface EvidenceDraft {
  phase: EvidencePhase;              // observe / hypothesize / construct / run /
                                     // result / revise / generalize / argue
  variantId: string;
  tool?: ToolId;
  action: string;
  artifact?: ArtifactSummary;        // { id, kind, digest, summary }
  outcome?: 'info' | 'pass' | 'fail';
  failureClass?: string;
  metrics?: Record<string, number>;
  scaffold?: Scaffold;               // none / env / tool / demo：提示等级
}

export interface RuntimeAdapter<S> {
  initialState(detail: LevelDetail, now: number): S;
  /** 只处理工具动作；run/submit/reset 由共享运行时统一处理 */
  apply(state: S, action: LevelAction): AdapterResult<S>;
  artifact(state: S): unknown | null;              // 没有产物时返回 null（提交会被拒）
  artifactSummaries(state: S): ArtifactSummary[];
  checkpoints(state: S, ctx: TemplateCheckpointContext): Record<string, boolean>;
  toolState(state: S): Partial<ToolStateMap>;
  /** 用最终产物直接校验（审计/多解/编辑器用，不依赖动作回放） */
  validate(detail: LevelDetail, variant: RuntimeVariant, artifact: unknown): Verdict;
  /** 黄金解 → 动作序列（autoplay 用；必须走与玩家相同的 dispatch 路径） */
  actionsFor(detail: LevelDetail, variant: RuntimeVariant, artifact: unknown): LevelAction[];
  transferVariants?(detail: LevelDetail): RuntimeVariant[];
  transferFailureClass?(detail: LevelDetail): string;
  argumentState?(state: S): ArgumentSnapshot | undefined;
}

// games/forge/src/levels/k-structure-pattern-path.ts
const manifest: LevelManifest = {
  id: 'k-structure-pattern-path', band: 'k', thread: 'structure',
  template: 'pattern', designSize: DESIGN, estimatedMinutes: 5, hasCanvas: true,
};
export default definePatternLevel(manifest);

// 真迁移门：内容里带 scenario.symbols 的变体（换表征），submit 时逐条重验。
// pattern 自管 runtime（不像 rule/construct 走 shared/runtime 的 adapter），所以门要在这里接。

export function seedFor(levelId: string, profileId: string): number {
  const input = levelId + '|' + profileId;
  let hash = 2166136261;
  for (let index = 0; index < input.length; index += 1) {
    hash ^= input.charCodeAt(index);
    hash = Math.imul(hash, 16777619);
  }
  return (hash >>> 0) % 1_000_000_000;
}

export interface RuntimeOptions {
  seed: number;
  now: () => number;
  locale: Locale;
  reducedMotion: boolean;
  /** 只允许 DEV / webdriver 打开；生产分享链接不得带 autoplay */
  autoplay?: boolean;
  /** 证据出口：运行时只写草稿，落盘由外壳负责 */
  onEvidence?: (draft: EvidenceDraft) => void;
}