第08章 - 六个模板总览与pattern

// packages/templates/src/pattern/index.ts（节选）
export function definePatternLevel(manifest: LevelManifest): LevelModule {
  let game: { destroy(removeCanvas: boolean): void; loop: { sleep(): void; wake(): void } } | null = null;

  return {
    manifest,
    createRuntime: (detail, opts) => createPatternRuntime(detail, opts),
    async mount(ctx, runtime) {
      if (!ctx.canvasHost) return;
      game = createPhaserGame(ctx.canvasHost, {
        designSize: manifest.designSize,
        scenes: [createPatternScene(ctx, runtime)],
      });
    },
    async unmount() { game?.destroy(true); game = null; },
    pause() { game?.loop.sleep(); },
    resume() { game?.loop.wake(); },
  };
}

// packages/templates/src/shared/runtime.ts（节选）
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;
  checkpoints(state: S, ctx: TemplateCheckpointContext): Record<string, boolean>;
  toolState(state: S): Partial<ToolStateMap>;
  validate(detail: LevelDetail, variant: RuntimeVariant, artifact: unknown): Verdict;
  actionsFor(detail: LevelDetail, variant: RuntimeVariant, artifact: unknown): LevelAction[];
  // …artifactSummaries / 可选的 argumentState / transferVariants / transferFailureClass
}

// packages/templates/src/pattern/schema.ts（全文）
import { z } from 'zod';

export const patternScriptSchema = z.object({
  scenario: z.object({
    kind: z.literal('path'),
    length: z.number().int().min(3).max(24),
    visible: z.array(z.string().min(1).nullable()).min(3).max(24),
    startIndex: z.number().int().min(0).max(12).default(0),
    symbols: z.record(z.string(), z.string()).optional(),
  }),
  pattern: z.object({
    allowedPeriods: z.array(z.number().int().min(2).max(6)).min(1),
    allowedTransforms: z.array(z.enum(['none', 'mirror', 'rotate', 'shift', 'reflect'])).min(1),
    ambiguous: z.boolean().default(false),
  }),
});
export type PatternScript = z.infer<typeof patternScriptSchema>;

export const patternArtifactSchema = z.object({
  patternRule: z.object({
    tokens: z.array(z.string().min(1)).min(2).max(6),
    period: z.number().int().min(2).max(6),
    transform: z.enum(['none', 'mirror', 'rotate', 'shift', 'reflect']),
  }),
  repair: z.array(z.object({ index: z.number().int().min(0), token: z.string().min(1) })),
});

// packages/templates/src/pattern/logic.ts（节选）
export function validateArtifact(
  script: PatternScript,
  variant: PatternVariant,
  artifact: unknown,
): Verdict {
  const applied = applyVariant(script, variant);
  const symbols = symbolsOf(variant);
  const relabeled = Object.keys(symbols).length > 0;
  const world = toWorld(applied, symbols);
  const artifacts = summarizeArtifact(artifact);
  const candidate = artifact as { patternRule?: { tokens?: unknown }; repair?: unknown } | null | undefined;
  const hasRule = Boolean(candidate?.patternRule && Array.isArray(candidate.patternRule.tokens));
  const hasRepair = Array.isArray(candidate?.repair);
  // 既没声明规律、也没补块：这是"空产物"，要报明确的结构失败类（A1b），不能走缺证据分支。
  if (!hasRule && !hasRepair) {
    return {
      passed: false,
      stamps: [],
      failure: { class: 'pattern-rule-invalid', variantId: variant.id, causes: [] },
      missingEvidence: [],
      artifacts,
    };
  }
  // …
}

// packages/toolkit/src/pattern/index.ts（节选）
export function validatePattern(world: PatternWorld, artifact: unknown): PatternValidation {
  // 1) 规则是否合法（tokens 2–6、period 与 tokens 等长且在 allowedPeriods 内、transform 合法）
  const ruleError = validateRule(world, rule);
  if (ruleError) return { passed: false, failureClass: ruleError };
  // 2) 规则必须在每一个可见格上成立
  for (let i = 0; i < world.length; i += 1) {
    const visible = world.visible[i];
    if (visible === null || visible === undefined) continue;
    if (tokenAt(rule, i) !== visible) return { passed: false, failureClass: 'pattern-cycle-wrong', conflictIndex: i };
  }
  // 3) 缺口必须全部补上
  if (missing.length > 0) return { passed: false, failureClass: 'pattern-repair-incomplete', missingIndices: missing };
  // 4) 补的块必须与规则一致
  if (mismatch.length > 0) return { passed: false, failureClass: 'pattern-mismatch', mismatchIndices: mismatch };
  return { passed: true };
}

// packages/toolkit/src/pattern/index.ts（节选）
/** 规则在第 index 位应该生成的 token。index 从 0 开始。 */
export function tokenAt(rule: PatternRule, index: number): string {
  const period = rule.period > 0 ? rule.period : rule.tokens.length;
  if (rule.transform === 'reflect') {
    const cycle = period * 2;
    const position = ((index % cycle) + cycle) % cycle;
    return rule.tokens[position < period ? position : cycle - 1 - position] ?? '';
  }
  const i = ((index % period) + period) % period;
  switch (rule.transform) {
    case 'mirror': return rule.tokens[(period - 1 - i) % period] ?? '';
    case 'rotate': return rule.tokens[(i + 1) % period] ?? '';
    case 'shift':  return rule.tokens[(i + period - 1) % period] ?? '';
    case 'none':
    default:       return rule.tokens[i] ?? '';
  }
}

/**
 * 「只填不声明」：没有 patternRule 时，用可见格推出的候选规律检验补的块。
 * 判据和带规律的判法同源：填法必须能被本关允许的某条规律完整解释，
 * 所以它不是放宽判定，而是允许玩家把「声明」省掉。
 */
export function validateRepairOnly(script: PatternScript, repair: unknown): { … } {
  const world = toWorld(script);
  // 1) 缺口必须补齐
  if (missing.length > 0) return { passed: false, failureClass: 'pattern-repair-incomplete', missingIndices: missing };
  // 2) 补法必须能被某条「从可见格推出来」的候选规律解释
  for (const rule of candidateRules(script)) {
    if ([...repairs].every(([index, token]) => tokenAt(rule, index) === token)) return { passed: true, rule };
  }
  // 3) 连候选规律都没有：按「规则和带子对不上」报，别退化成空判定
  return { passed: false, failureClass: 'pattern-cycle-wrong' };
}

case 'pattern/commit': {
  if (!state.rule) return fail('先拼出一个重复单元。');
  const error = validateRule(world, state.rule);
  if (error) {
    emit({ phase: 'hypothesize', tool: 'pattern', action: action.type, outcome: 'fail', failureClass: error });
    notify();
    return fail('这条规律不在这一关允许的范围里。');
  }
  state.committed = true;
  // 提交后画布要让位给「哪块放错了」的即时提示，预览 ghost 先收起。
  state.preview = undefined;
  state.checkpoints.hypothesis = true;
  // …usage + emit + notify
}

case 'pattern/preview': {
  // rule 来自 action.payload 的 cycle/transform（省略这三行）
  const sameAsCommitted = state.committed && state.rule
    && patternRuleKey(state.rule) === patternRuleKey(rule);
  state.rule = rule;
  // 预览不是提交：只有预览的规则与已提交的规则不一致时，才让旧提交失效。
  if (!sameAsCommitted) state.committed = false;
  state.previewSeq += 1;
  state.preview = buildPreview(script, state.rule, opts.now(), state.previewSeq);
}

/** 规则指纹：tokens 顺序与变换都要算进去，否则换变换后旧预览会被误认成同一条规则。 */
export function patternRuleKey(rule: Pick<PatternRule, 'tokens' | 'transform'>): string {
  return rule.tokens.join('') + ':' + rule.transform;
}

private signatureOf(snapshot: RunSnapshot): string {
  const pattern = patternStateOf(snapshot);
  const preview = this.activePreview(pattern);
  return [
    snapshot.phase,
    String(snapshot.revision),
    (pattern?.inspected ?? []).join(','),
    pattern?.cycle?.join('') ?? '',
    pattern?.committed ? 'committed' : 'open',
    pieces.map((piece) => `${piece.x}:${piece.shape}`).join(','),
    snapshot.lastRun?.id ?? '',
    causes.map((cause) => `${cause.kind}:${cause.ref}`).join(';'),
    // 预览也要进 signature：ghost 与「连点重新跑一遍」都靠它触发重绘。
    preview ? preview.ruleKey + '@' + preview.seq : '',
  ].join('|');
}

/**
 * 迁移门：内容里所有带 `scenario.symbols` 的变体都是换表征变体，逐条要过。
 * 返回空数组表示这一关没有迁移门（template verifier 的可选约定）。
 */
export function transferVariants(detail: LevelDetail): PatternVariant[] {
  const variants = Array.isArray(detail.variants) ? detail.variants : [];
  return variants
    .filter((variant) => Object.keys(symbolsOf(variant)).length > 0)
    .map((variant) => ({ id: variant.id, axis: variant.axis, patch: { ...variant.patch } }));
}

/** 把带子上的 token 按映射改名；映射里没有的 token 原样保留，不静默丢信息。 */
export function relabelVisible(visible: readonly (string | null)[], symbols: PatternSymbolMap): (string | null)[] {
  if (Object.keys(symbols).length === 0) return [...visible];
  return visible.map((token) => (
    token === null || token === undefined ? null : (symbols[token] ?? token)
  ));
}

// 迁移门只认「随映射走」的产物：只填不声明的 repair-only 是把答案抄在旧表征上（空壳），
// 换个表示以后没有规律可翻译，必须报 pattern-transfer-failed，而不是悄悄当成通过。
if (relabeled && !hasRule) {
  return {
    passed: false,
    stamps: [],
    failure: {
      class: 'pattern-transfer-failed',
      variantId: variant.id,
      causes: [{ kind: 'variant', ref: variant.id, messageKey: 'level.pattern.transfer.message' }],
    },
    missingEvidence: [],
    artifacts,
  };
}

/** 逐条跑换表征变体；和 shared/runtime 的 transferCheck 同语义：第一条失败即门失败。 */
function transferCheck(artifact: unknown): { passed: boolean; results: { id: string; passed: boolean }[]; failure?: Verdict } {
  const results: { id: string; passed: boolean }[] = [];
  for (const variant of gateVariants) {
    const verdict = validateArtifact(script, variant, artifact);
    results.push({ id: variant.id, passed: verdict.passed });
    if (!verdict.passed) return { passed: false, results, failure: verdict };
  }
  return { passed: true, results };
}

// games/forge/src/levels/k-structure-pattern-path.ts（全文，省略 import）
const manifest: LevelManifest = {
  id: 'k-structure-pattern-path',
  band: 'k',
  thread: 'structure',
  template: 'pattern',
  designSize: DESIGN,
  estimatedMinutes: 5,
  hasCanvas: true,
};

export default definePatternLevel(manifest);