Implement Puzzle #4: modular deterministic Perbug Symbol Match

[ercmine]

Motivation

• Add a fourth modular puzzle type to the Perbug node challenge system that plugs into the existing node/puzzle lifecycle instead of being a disconnected demo.
• Ensure puzzles are deterministic from a node's lat/lng seed so the same node produces reproducible puzzles for tuning and analytics.
• Provide a flexible symbol/rule-based core so future variants (different rule families, grouping, multi-answer modes) can reuse the same framework.

Description

• Added a small shared puzzle framework (perbug_puzzle_framework.dart) with PuzzleSeedInput, DeterministicRng, PuzzleDifficulty, PuzzleInstance, PuzzleSession, and PuzzleResult, and a stable toSeed() derivation that quantizes lat/lng and mixes node id for determinism.
• Implemented Perbug Symbol Match (perbug_symbol_match.dart) providing deterministic symbol feature generation (shape/color/mark/rotation), rule generation/evaluation, decoy selection tuned by overlapSimilarity, per-round construction with fairness checks (exactly one valid answer), and a difficulty knobs model (SymbolMatchDifficultyKnobs) driving score and tier.
• Built a playable UI SymbolMatchPuzzleSheet (perbug_symbol_match_screen.dart) with pre-start difficulty display, multi-round selection flow, optional timer pressure, custom symbol painter, selection/submit/continue loop, and lifecycle events for start/round/complete/success/failure.
• Integrated the puzzle into the Perbug flow by extending game state/controller to track PuzzleSession and puzzle telemetry, adding buildSymbolMatchPuzzleForNode() and finalizePuzzleResult() to the controller, and launching the puzzle from reachable node actions in the main game page (perbug_game_page.dart) so successful puzzle completion is required to execute the jump reward.

Testing

• Added unit tests app/test/perbug_symbol_match_test.dart covering deterministic generation from the same seed, different-seed divergence, difficulty scaling with knobs, round fairness (single valid answer), answer validation, and timer-pressure behavior.
• Updated app/test/perbug_game_models_test.dart to reflect the extended PerbugGameState shape including puzzle event list.
• Could not run the Dart/Flutter test runner in this environment because dart/flutter executables are not available, so the tests were added but not executed here.
• Performed repository sanity checks such as git diff --check which reported no whitespace errors and committed the changes to the branch (commit recorded locally).

---

Codex Task

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.