diff --git a/README.md b/README.md index 586ad51..9f12433 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ This branch is an analysis-only bootstrap for a Mainline-first modernization of The preserved 8,401-line Mainline source must be analyzed sequentially, in evidence-backed batches, before runtime work begins. All behavior-critical shortened symbols must be resolved and all batches must be complete before any public Lua API, runtime module, modern TOC, packaging, or release work is added. -Batches 01–06 (lines 1–3,000) are documented. The remaining batches are scheduled but not analyzed. +Batches 01–07 (lines 1–3,500) are documented. The remaining batches are scheduled but not analyzed. ## Goal diff --git a/docs/analysis/batch-schedule.md b/docs/analysis/batch-schedule.md index b769000..0fb2970 100644 --- a/docs/analysis/batch-schedule.md +++ b/docs/analysis/batch-schedule.md @@ -10,7 +10,7 @@ The immutable analysis source is `Legacy/Bejeweled_Mainline.lua` from commit `6f | 04 | 1501–2000 | 500 | `lines-1501-2000.md` | complete | | 05 | 2001–2500 | 500 | `lines-2001-2500.md` | complete | | 06 | 2501–3000 | 500 | `lines-2501-3000.md` | complete | -| 07 | 3001–3500 | 500 | `lines-3001-3500.md` | pending | +| 07 | 3001–3500 | 500 | `lines-3001-3500.md` | complete | | 08 | 3501–4000 | 500 | `lines-3501-4000.md` | pending | | 09 | 4001–4500 | 500 | `lines-4001-4500.md` | pending | | 10 | 4501–5000 | 500 | `lines-4501-5000.md` | pending | diff --git a/docs/analysis/identifier-ledger.md b/docs/analysis/identifier-ledger.md index 109212b..42fc844 100644 --- a/docs/analysis/identifier-ledger.md +++ b/docs/analysis/identifier-ledger.md @@ -120,7 +120,7 @@ Each row identifies one declaration, not merely one spelling. `chunk` means the | `z` / chunk (numeric overwrite) | 322 | Overwrites earlier binding with `7`; no batch-01 read. | unknown enum seven | unresolved | Low. | 01–01 | Engine | Locate consumers. | | `o` / chunk | 323 | Eight row tables initialized, exported as `debugArray`, and traversed as `o[row][column]` gem frames (324–326, 442, 1275–1293). | `gemGrid` | resolved | High: explicit 8×8 traversal. | 01–03 | Engine/Grid, UI/GemPool | Debug export naming is incidental. | | `e` / debug-array loop | 324 | Loop 1–8; indexes `o` for writes (325). | `index` | resolved | High: direct loop role. | 01–01 | Core/Init | None. | -| `v` / chunk | 327 | Forward declaration; used as key for authenticated personal-best payload in `n.statDB` (887, 900). | `statEncodedScoreKey` | working | Medium: value type is proven; concrete selected key is not. | 01–02 | Core/SavedVariables | Find assignments for mode-specific key. | +| `v` / chunk | 327 | Forward declaration; used as key for authenticated personal-best payload in `n.statDB` (887, 900) and signed zero payloads in classic/timed profile stats (3490–3491). | `statEncodedScoreKey` | working | Medium: value type is proven; concrete selected key is not. | 01–07 | Core/SavedVariables | Find assignments for mode-specific key. | | `I` / chunk | 327 | Forward declaration; used as key for numeric personal-best metric in `n.statDB` (885–886, 898–899). | `statNumericScoreKey` | working | Medium: value type is proven; concrete selected key is not. | 01–02 | Core/SavedVariables | Find assignments for mode-specific key. | | `ge` / chunk | 327 | Forward declaration populated by `ze` with faction-selected four-region coordinate adjacency graphs (1040–1249). | `flightGraph` | resolved | High: complete assignment shape. | 01–03 | Core/SavedVariables | Region meanings/search consumers pending. | | `we` / chunk | 327 | Forward declaration; assigned `true` when max-score level-up begins (529). | `levelUpPendingFlag` | working | Low: writer observed, reader absent. | 01–02 | Engine/Scoring, UI/Animations | Find consumer/reset. | @@ -474,11 +474,53 @@ Complete helpers are resolved from full bodies. Same-spelling functions are sepa | `Ue` / shadow function; `t` local | 2770–2771 | Advances current-game level/multiplier/threshold. | `advanceLevel`; `gameState` | resolved | High. | 06–06 | Engine/Scoring | None. | | `Ce` / shadow function; `t`,`n` bindings | 2800–2801 | Processes hyper chain using gem and animator. | `triggerHyperChain` | resolved | High. | 06–06 | Engine/Matches | None. | | `S`,`s`,`i`,`r`,`l`,`d`,`e` / `Ce` locals/loops | 2814–2821 | Source/target centers, coordinates, row/column, matching gem. | coordinate/search roles | resolved | High. | 06–06 | Engine/Matches | None. | -| `he` / chunk function | 2842 | Match scanner/marker continues after 3000. | `findAndMarkMatches` | working | High for prefix. | 06–06 | Engine/Matches | Complete in batch 07. | -| `x`,`e`,`S`,`c`,`T`,`r`,`s`,`w`,`g`,`C`,`u`,`l`,`d`,`p`,`f` / `he` locals | 2843–2844 | Match-found flag, run length/color/counts, gem, creation flags and cross-arm bounds. | working match-scan roles | working | Medium: function incomplete. | 06–06 | Engine/Matches | Resolve on completion. | -| `i`,`t`,`n`,`e`,`d`,`l` / `he` loops | 2845–2999 | Grid and vertical/horizontal run/cross-arm indices. | row/column/run indices | working | High for observed scopes. | 06–06 | Engine/Matches | Continue in batch 07. | -| `explodeCount` / implicit chunk global | external; writes 2887, 2975 | Accumulates `Le` explosion returns and is passed to `M`. | `explosionCount` | working | High; accidental global. | 06–06 | Engine/Matches | Must become local. | +| `he` / chunk function | 2842 | Scans vertical/horizontal matches, marks clears, creates power/hyper gems, reports matches/statistics, returns match-found at 3039. Shadows the RGB table captured by earlier effect factories. | `findAndMarkMatches` | resolved | High. | 06–07 | Engine/Matches | None. | +| `x`,`e`,`S`,`c`,`T`,`r`,`s`,`w`,`g`,`C`,`u`,`l`,`d`,`p`,`f` / `he` locals | 2843–2844 | Match-found flag, run length/color/counts, gem, creation flags and cross-arm bounds. | match-scan roles by use | resolved | High. | 06–07 | Engine/Matches | None. | +| `i`,`t`,`n`,`e`,`d`,`l` / `he` loops | 2845–3033 | Grid, run, and cross-arm indices in declaration-specific loop scopes. | row/column/run indices | resolved | High. | 06–07 | Engine/Matches | None. | +| `explodeCount` / implicit chunk global | external; writes 2887, 2975; read 3019 | Accumulates `Le` explosion returns and is passed to `M`. | `explosionCount` | working | High; accidental global. | 06–07 | Engine/Matches | Must become local without changing accumulation. | ## Batch 06 resolution policy Completed factories are resolved by pool/field contracts. The open match scanner and its reused locals remain working until batch 07; accidental `explodeCount` is recorded as global evidence. + +## Batch 07 declarations and scopes + +| Legacy identifier / scope | Decl. | Evidence | Proposed name | Status | Confidence | First–last | Target | Question | +| --- | ---: | --- | --- | --- | --- | --- | --- | --- | +| `ce` / shadow function; `e` param | 3041 | Mouse-leave handler clears deferred hover or ends eligible effects. Shadows earlier half-gem-width constant only for later declarations. | `handleGemMouseLeave`; `gem` | resolved | High. | 07–07 | UI/GemPool | None. | +| `Z` / shadow function; `t` param | 3057 | Main click/swap controller. `he` retains the earlier `createHyperGem` binding. | `handleGemClick`; `gem` | resolved | High. | 07–07 | Engine/Input | None. | +| `r` / `Z` adjacency scope | 3082 | False until clicked gem is one orthogonal neighbor of current selection. | `isAdjacent` | resolved | High. | 07–07 | Engine/Input | None. | +| `a` / `Z` swap scope | 3083 | Holds hyper activation/target state used with match result. | `hyperTriggered` | resolved | Medium-high. | 07–07 | Engine/Input, Engine/Matches | Preserve exact truthy values. | +| `l` / `Z` swap scope | 3084 | Animator used for hints and moving-gem scheduling. | `animator` | resolved | High. | 07–07 | UI/Animations | None. | +| `o`,`i` / `Z` selected-coordinate scope | 3089 | Hold selected X/Y; nested `o` at 3102 separately binds selected gem. | `selectedX`,`selectedY` | resolved | High. | 07–07 | Engine/Input | Keep nested binding distinct. | +| `o` / `Z` adjacent-swap scope | 3102 | Selected gem paired with clicked parameter `t`. | `selectedGem` | resolved | High. | 07–07 | Engine/Input | None. | +| `e` / `Z` bCrowbar scope | 3148 | Serialized previous-board state for optional bCrowbar integration. | `previousState` | resolved | High. | 07–07 | Integration/bCrowbar | None. | +| `t` / repeated `Z` locals and loop | 3150–3151 | Repeated same-scope nil declarations precede board serialization loop. | dead temporaries / row index | dead | High. | 07–07 | Integration/bCrowbar | Remove only after equivalence tests. | +| `n` / `Z` serialization loop | 3155 | Inner board index for bCrowbar previous-state capture. | `column` | resolved | High. | 07–07 | Integration/bCrowbar | None. | +| `o`,`i` / `Z` generic loop | 3161 | Iterator key/value over serialized board state. | `key`,`value` | resolved | High. | 07–07 | Integration/bCrowbar | None. | +| `i` / `Z` swap local | 3167 | Temporary used while exchanging gem identity/state. | `swapTemporary` | resolved | High. | 07–07 | Engine/Input | None. | +| `l` / `Z` result scope | 3174 | Boolean indicating both swapping gems are hyper gems. | `bothHyper` | resolved | High. | 07–07 | Engine/Matches | None. | +| `a` / `Z` result scope | 3182 | Receives `he` return and participates in valid-move decision. | `matchFound` | resolved | High. | 07–07 | Engine/Matches | None. | +| `t`,`e` / `Z` invalid-result scope | 3208 | Snapshot `o.fxType` and `o.fxFrame`, then are never read. | — | dead | High. | 07–07 | Engine/Input | Remove after behavioral capture. | +| `ee` / shadow function; `t` param | 3234 | Drag-release handler maps cursor displacement to a neighboring gem and calls new `Z`. `he` retains earlier `createPowerGem`. | `handleGemDragRelease`; `gem` | resolved | High. | 07–07 | Engine/Input | None. | +| `e`,`l` / `ee` locals | 3239 | Cursor coordinates from `GetCursorPosition`, later reused for target column/row. | `cursorXOrColumn`,`cursorYOrRow` | resolved | High. | 07–07 | Engine/Input | Verify Retail coordinate scaling. | +| `r`,`i` / `ee` locals | 3240–3241 | Horizontal and vertical displacement from pressed gem, normalized on the selected axis. | `deltaX`,`deltaY` | resolved | High. | 07–07 | Engine/Input | None. | +| `d` / `ee` local | 3242 | Neighbor chosen from dominant drag direction. | `targetGem` | resolved | High. | 07–07 | Engine/Input | None. | +| `U` / shadow function; `n` param | 3270 | Selects one of four tabs and restyles all tab buttons; shadows color-name table for later code. | `selectTab`; `tabButton` | resolved | High. | 07–07 | UI/Tabs | None. | +| `e` / `U` first local | 3271 | Declared and immediately shadowed before any read. | — | dead | High. | 07–07 | UI/Tabs | None. | +| `e` / `U` parent local | 3272 | Parent container whose contents/buttons are updated. | `container` | resolved | High. | 07–07 | UI/Tabs | None. | +| `t` / `U` loop | 3273 | Tab index 1–4. | `index` | resolved | High. | 07–07 | UI/Tabs | None. | +| `nt` / shadow function; `o`,`r` params | 3288 | Populates leaderboard rows for owner and selected list; shadows direction constant for later code. | `populateLeaderboard`; `owner`,`listKey` | resolved | High. | 07–07 | UI/Leaderboard | None. | +| `t` / duplicated `nt` locals | 3293 | Two nil declarations superseded by row-loop `t` without a read. | — | dead | High. | 07–07 | UI/Leaderboard | None. | +| `n`,`i`,`l` / `nt` locals | 3293 | Record name/rank/score values reused for classic and timed rows. | `name`,`rank`,`score` | resolved | High. | 07–07 | UI/Leaderboard | None. | +| `h`,`a`,`S`,`d`,`s` / `nt` locals | 3294–3298 | Score list, cyan color, green color, player name, friend count. | `scoreList`,`cyan`,`green`,`playerName`,`friendCount` | resolved | High. | 07–07 | UI/Leaderboard | None. | +| `t` / `nt` row loop | 3299 | Display row index 1–10. | `rowIndex` | resolved | High. | 07–07 | UI/Leaderboard | None. | +| `e` / `nt` friend loops | 3315, 3348 | Friend-list index in distinct nested loop scopes. | `friendIndex` | resolved | High. | 07–07 | UI/Leaderboard | None. | +| `Ne` / shadow function; `t`,`n` params | 3369 | Throttled timer `OnUpdate`; delta parameter `n` is consumed before a later local shadows it. Shadows direction constant for later code. | `updateTimer`; `frame`,`delta` | resolved | High. | 07–07 | UI/Timer | None. | +| `n` / `Ne` timed-window local | 3378 | Timed-window object used after delta accumulation. | `timedWindow` | resolved | High. | 07–07 | UI/Timer | None. | +| `i`,`a`,`t`,`o` / `UpdateSavedVariablesDatabase` locals | 3463–3466 | Classic stats, timed stats, saved state, and player identity/checksum; `o` changes role after upgrade checks. | `classicStats`,`timedStats`,`savedState`,`playerNameOrChecksum` | working | Medium-high. | 07–07 | Persistence/Migration | Continue method in batch 08. | +| `n` / score-migration popup scope | 3494 | Popup frame constructed for incomplete score migration; construction continues after 3500. | `migrationPopup` | working | High for object role. | 07–07 | UI/Migration | Complete in batch 08. | + +## Batch 07 resolution policy + +Bindings are resolved only where complete control/data flow closes within this batch or the completed cross-batch `he` body. Locals in the open saved-variable method and ambiguous animator/row temporaries remain working; unused declarations are marked dead without yet authorizing removal. diff --git a/docs/analysis/lines-3001-3500.md b/docs/analysis/lines-3001-3500.md new file mode 100644 index 0000000..0332ac1 --- /dev/null +++ b/docs/analysis/lines-3001-3500.md @@ -0,0 +1,57 @@ +# Batch 07: lines 3001–3500 + +Source: `Legacy/Bejeweled_Mainline.lua` at commit `6faec1c` +Coverage: lines 3001–3500 inclusive +Blank: 3040, 3056, 3233, 3269, 3287, 3368, 3407 +Status: complete; `he` closes at 3039 and `Bejeweled:UpdateSavedVariablesDatabase` continues into batch 08 + +## Line-indexed coverage audit + +| Lines | Evidence represented | +| ---: | --- | +| 3001–3039 | Finishes the horizontal-run branch of match scanner `he`: creates a contents-9 hyper gem for qualifying five-or-more runs, reports the match, updates current-game and profile largest-cascade maxima, increments the per-color `gemMatch` counter, and returns match-found flag `x`. This resolves `he` across lines 2842–3039. | +| 3040 | Blank. | +| 3041–3055 | `ce` is the gem mouse-leave handler. It clears deferred hover when moves are disallowed; otherwise it ends eligible hover effects and reverses adjacent-highlight animation `ke` when the gem is not moving, then clears `adj`. | +| 3056 | Blank. | +| 3057–3064 | New chunk-local function `Z` shadows the earlier hyper-gem factory after `he` has captured that older binding. This function handles gem click/swap input, rejects absent-mode or paused state, and delegates jewel-edit clicks to bCrowbar when enabled. | +| 3065–3087 | When moves are disallowed, `Z` records or applies a deferred selection. In normal play it creates a hint animator from current legal-move finder `Q`, then starts selected-gem adjacency testing with boolean `r`. | +| 3088–3100 | Captures the current selection's grid coordinates and tests whether the clicked gem is one of its four orthogonal neighbors. | +| 3101–3146 | For an adjacent click, adds both gems to the animator, clears cursor/highlight state, configures hyper/color activation, and initializes reciprocal movement destinations, step vectors, partner references, movement flags, and the animator's moving-gem count. The hyper color target is derived from the non-hyper counterpart. | +| 3147–3166 | Captures the optional bCrowbar previous-board state. The snapshot creates or wipes each destination cell and copies every key/value from the corresponding `jewelArray` cell through nested numeric and generic loops. | +| 3167–3212 | Swaps `contents` and `bigStar`, resolves whether both participants were hyper gems, and combines hyper activation with `he`'s match result. An invalid swap restores both fields, marks the pair invalid, and plays `Invalid`; a valid move increments game/profile move totals and awards move-100/move-250 skills. Locals `t` and `e` at 3208 snapshot `o.fxType`/`o.fxFrame` but are never read before their scope ends. | +| 3213–3232 | Completes adjacent-swap handling and the non-adjacent path: clicking the selected gem clears selection; clicking another gem transfers selection and hover/adjacent effects. Function `Z` then closes. | +| 3233 | Blank. | +| 3234–3268 | New `ee` shadows the earlier power-gem factory after `he` captured it. As the drag-release handler, it optionally creates a hint, reads cursor coordinates, chooses the dominant horizontal or vertical displacement, maps that direction to an in-bounds neighbor, and invokes click handler `Z`; no valid neighbor clears selection/hover state. | +| 3269 | Blank. | +| 3270–3286 | `U` is the tab-click handler and shadows the earlier gem-color-name table only for later code. Its first local `e` is immediately shadowed and dead; it resolves the parent, hides all four content panes, selects the requested pane, and applies selected/unselected tab textures and label colors. | +| 3287 | Blank. | +| 3288–3298 | `nt` begins leaderboard-row population for owner `o` and list key `r`, shadowing the earlier direction constant. It refreshes guild data, scrubs lists, binds the selected score list and player/friend context, and initializes cyan/green name colors. The duplicated `t` declarations at 3293 are superseded by the row-loop variable without an intervening read. | +| 3299–3367 | Iterates ten display rows, unpacks classic and timed leaderboard records, formats rank and score, and colors PopCap, player, friend, and guild entries. Two nested friend scans test membership. Rank texture coordinates use a 16-pixel cell normalized by 128. | +| 3368 | Blank. | +| 3369–3378 | `Ne` is the timer-window `OnUpdate` handler, shadowing an earlier direction constant for later code. It accumulates elapsed time and performs work at 0.1-second granularity; after consuming parameter `n`, a local `n` is declared for the timed window. It advances elapsed time, decrements remaining time, and updates Legendary Journey progress. | +| 3379–3406 | After more than four seconds it lazily registers `PLAYER_MONEY`, disables the flight checkbox below 60 seconds, expires the timer at zero, and updates visible timer text. The window accumulator and display are reset/updated only at the throttled interval. | +| 3407 | Blank. | +| 3408–3411 | Begins `Bejeweled:UpdateSavedVariablesDatabase` and exposes selected internals to bCrowbar: board grid, current game, gem renderer, and match scanner. This method remains open at the batch boundary. | +| 3412–3462 | Beta-reset branch clears selected `BejeweledData` flags and replaces `BejeweledProfile` with a compact default schema: classic/timed and aggregate statistics, skill progress, and gameplay/publishing settings. These assignments are wire-format evidence, not authorization to migrate either saved-variable table. | +| 3463–3492 | Binds classic/timed stat tables, saved state, and player name; upgrades an unversioned profile by setting version/migration fields and re-signing its saved score; supplies `defaultPublish`; then reuses `o` for a player checksum. When `scoreList` is absent it zeros both scores, seeds friend/guild leaderboards, and writes signed zero payloads at shared chunk key `v` in both mode tables. | +| 3493–3500 | If score migration has not been marked complete, creates popup frame `n`, sizes and centers it, enables mouse input, marks it top-level, and hides it initially. The popup construction, conditional, and `UpdateSavedVariablesDatabase` all continue in batch 08. | + +## Findings + +- `he` resolves as `findAndMarkMatches`: it returns whether any match was found after updating cascade and per-color statistics. +- The new `Z` is the click/swap controller, not the hyper-gem factory. The new `ee` is drag-release direction handling, not the power-gem factory. Lua lexical capture means `he` retains both earlier factory bindings. +- Swap validation is optimistic: visual/game state is exchanged first, then `he` decides whether to keep the move; invalid swaps restore state and use explicit invalid-animation flags. +- `nt` owns leaderboard presentation and encodes rank-atlas geometry as `16 / 128`; name color is data-derived from PopCap/player/friend/guild membership. +- `UpdateSavedVariablesDatabase` supplies direct evidence for both persistent wire formats. Its beta reset and unversioned-profile upgrade must remain descriptive until the method and all consumers are analyzed. + +## API and architecture mapping + +- `GetCursorPosition`, `C_GuildInfo.GuildRoster`, `C_FriendList`, `IsInGuild`, frame registration, texture-coordinate, and text calls are legacy API contracts requiring current authoritative Retail verification before implementation. +- `Engine/Input.lua`: `Z`, `ee`, selection, adjacency, swap setup, invalid rollback. +- `Engine/Matches.lua`: completed `he` contract and hyper activation. +- `UI/Leaderboard.lua`: `nt`; `UI/Tabs.lua`: `U`; `UI/Timer.lua`: `Ne`. +- `Persistence/Migration.lua`: `UpdateSavedVariablesDatabase`, pending completion and schema proof in later batches. + +## Forward dependencies + +Batch 08 must continue at line 3501 without treating the partially constructed score-migration popup or `UpdateSavedVariablesDatabase` as complete. It must trace the rest of the migration, all signatures/checksums, and every mutation of `BejeweledData` and `BejeweledProfile` before any schema conclusion. diff --git a/tools/verify-bootstrap.ps1 b/tools/verify-bootstrap.ps1 index 5ba670c..2c56995 100644 --- a/tools/verify-bootstrap.ps1 +++ b/tools/verify-bootstrap.ps1 @@ -135,9 +135,10 @@ Assert-ReportCoverage 'docs/analysis/lines-1001-1500.md' 1001 1500 Assert-ReportCoverage 'docs/analysis/lines-1501-2000.md' 1501 2000 Assert-ReportCoverage 'docs/analysis/lines-2001-2500.md' 2001 2500 Assert-ReportCoverage 'docs/analysis/lines-2501-3000.md' 2501 3000 +Assert-ReportCoverage 'docs/analysis/lines-3001-3500.md' 3001 3500 $lineCount = (Get-Content -LiteralPath 'Legacy/Bejeweled_Mainline.lua').Count Assert-True ($lineCount -eq 8401) "Legacy source has $lineCount lines, expected 8401" Write-Output "Verified: forbidden files absent; legacy and $($assetPaths.Count) asset hashes match $SourceCommit." -Write-Output "Verified: strict UTF-8 text, exact 8,401-line schedule, and complete batch-01/02/03/04/05/06 line coverage." +Write-Output "Verified: strict UTF-8 text, exact 8,401-line schedule, and complete batch-01/02/03/04/05/06/07 line coverage."