Implement deterministic Perbug Pattern Recall puzzle in node framework

[ercmine]

Motivation

• Add a second modular Perbug puzzle (memory-pattern recall) that plugs into the existing node/puzzle architecture rather than a standalone demo.
• Ensure patterns are deterministically generated from node latitude/longitude seeds so the same node + knobs always produce the same puzzle instance.
• Provide a reusable framework and lifecycle hooks (preview, recall, success/failure, analytics, reward stubs) so future puzzle types can integrate cleanly.

Description

• Introduced a small shared puzzle framework with PuzzleType, PuzzleSeedInput, deterministic seededRandom (FNV-1a hash), PuzzleDifficulty, PuzzleResult, PuzzleSession, PuzzleLifecycleEvent, and generator/validator interfaces (app/lib/features/home/puzzles/perbug_puzzle_framework.dart).
• Implemented Pattern Recall domain and session models, knobs, distraction model, phases, debug metadata, and state view (pattern_recall_models.dart).
• Implemented a deterministic PatternRecallGenerator that builds a non-trivial symbol sequence from the node lat/lng seed, derives mirrored/reversed/distraction behavior and computes a weighted difficulty score/tier and explainer contributions (pattern_recall_generator.dart).
• Added PatternRecallValidator with tolerance-aware validation, analytics payload, and clear success/failure criteria (pattern_recall_validator.dart).
• Added a polished puzzle UI sheet with briefing → deterministic preview playback → recall input → success/failure, distraction highlighting, mirrored/reversed rule messaging, reset/retry/close actions (pattern_recall_puzzle_sheet.dart) and integrated a launch button + live difficulty display into the Perbug game page (perbug_game_page.dart).
• Extended PerbugGameState and PerbugGameController to hold active puzzle session state and lifecycle/telemetry event stream and implemented full pattern recall lifecycle APIs (generate, start preview, preview step, complete preview, input, validate, retry, abandon, close) with reward/energy hook stubs (perbug_game_models.dart and perbug_game_controller.dart).
• Added focused tests covering determinism, node variance, difficulty scaling, tolerance behavior, preview/input gating, and lifecycle event emission (app/test/perbug_pattern_recall_test.dart).

Testing

• Added unit tests app/test/perbug_pattern_recall_test.dart that assert deterministic generation from the same seed, different outputs for different nodes, difficulty scaling with tuning, validator tolerance behavior, and controller lifecycle/input gating (tests present but not executed in this environment).
• Ran repository checks (diff --check) which reported no issues.
• Attempted to run flutter test for the new test file but the execution environment lacks Flutter (/bin/bash: flutter: command not found), so the tests were not executed here; tests are included and ready to run in a proper Flutter/dev environment.

---

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.