Files
aetherbound-guild/docs/runtime/p10_1/IMPLEMENTATION_PLAN.md
T

392 lines
23 KiB
Markdown

# P10.1 Siltwake First Crossing Implementation Plan
> Status: `COMPLETE_AT_LOCAL_CANDIDATE`
> Active step: none; `P10.1-STEP-6` is `DEFERRED_BY_OWNER`
> Baseline: `4426d6677f70935998d9f5ce2a114003a4f34700`
> Goal: `docs/goals/PHASE10_1_SILTWAKE_FIRST_CROSSING_GOAL.md`
> Contract: `docs/runtime/PHASE10_1_SILTWAKE_FIRST_CROSSING_CONTRACT.md`
## Player-Visible Stopping Point
One continuous landscape flow enters Siltwake, prepares against a disclosed
tide shift, resolves one automatic battle, settles victory or recovery and
reloads at Market 2. No later Siltwake Market or Boss is part of this milestone.
## Ordered Steps
<!-- markdownlint-disable MD013 -->
| Step | Status | Player outcome | Commit boundary |
| --- | --- | --- | --- |
| P10.1-STEP-0 Contract | `COMPLETE` | The first crossing and its exact end state are frozen before product edits. | Goal, contract, plan, checkpoint and ledger. |
| P10.1-STEP-1 Content and first Market authority | `COMPLETE` | Siltwake's first Market always discloses a deterministic tide and three distinct route pressures. | Isolated registry/generator and focused tests. |
| P10.1-STEP-2 Save v7 and Region entry | `COMPLETE` | A Windglass-cleared Guild enters a stable Siltwake Run and resumes Market 1 truthfully. | State, migration, transactions and persistence tests. |
| P10.1-STEP-3 First-crossing battle | `COMPLETE` | Pull, tide pressure, hindrance and healing denial resolve visibly and causally. | Battle/settlement authority and counterfactual tests. |
| P10.1-STEP-4 Landscape runtime slice | `COMPLETE` | The player completes preparation, battle, recovery/reward and saved Market 2 by touch. | Controller, world scene, normal renders and recording. |
| P10.1-STEP-4A Game-feel motion repair | `COMPLETE` | Battle motion reads as contact, displacement, pressure and recovery rather than looping sprites over a static scene. | Event-bound motion adapter, focused tests and fixed comparison recording. |
| P10.1-STEP-5 Profiles and candidate evidence | `COMPLETE` | Five policies prove bounded pacing and no universal response. | Simulations, persistence/layout matrix and immutable evidence. |
| P10.1-STEP-6 H5 delivery | `DEFERRED_BY_OWNER` | A future fresh private H5 may expose the complete accepted first crossing. | Requires a new explicit delivery activation. |
<!-- markdownlint-enable MD013 -->
## Step Contracts
### P10.1-STEP-1 CONTENT AND FIRST MARKET AUTHORITY
```text
ID: P10.1-STEP-1
PLAYER OUTCOME: Before committing the first route, the player can compare one
disclosed tide shift, four regional equipment responses and three materially
different battle pressures without reload rerolls.
IN SCOPE: isolated RG-02 catalog; CTR-R2-01; EN-R2-01..07; EQ-041..048;
reference-only BO-R2-01; deterministic tide and regional Market overlay;
localized preview data; focused schema/seed/board tests.
OUT OF SCOPE: Recruit materialization, state mutation, Save v7, prices,
equipment purchase, battle execution, runtime UI, media and H5.
OWNED FILES: runtime/p10_1/catalog.json; runtime/p10_1/content_registry.gd and
UID; runtime/p10_1/first_market_generator.gd and UID; focused P10.1 tests and
UIDs; durable status after the source commit.
ACCEPTANCE CHECKS: exact IDs/counts; complete zh_CN/en names and preview data;
source authorities exact; same inputs byte-identical; changed seed changes
owned draws; refresh changes equipment only; route/tide never rerolls;
unique 4 equipment and risk 0/1/2 routes; required response coverage;
malformed seed/content/index/reference rejects; P10.0 content/offer
regressions unchanged.
EVIDENCE LEVEL EXPECTED: automated_verified.
COMMIT BOUNDARY: focused source/test push, then docs-only step closure.
LEGAL TERMINAL: P10.1 Step 1 content and first Market authority complete.
NEXT STEP: P10.1-STEP-2.
```
### P10.1-STEP-2 SAVE V7 AND REGION ENTRY
```text
ID: P10.1-STEP-2
PLAYER OUTCOME: A Guild that sealed Windglass enters one stable Siltwake Run,
receives three generated Recruit offers and resumes Market 1 after restart.
IN SCOPE: Save v7 migration; RG-02 entry; regional Run seed; 3/4/3 board;
Market operations; interruption and duplicate receipts.
OUT OF SCOPE: battle execution, new runtime presentation, media and H5.
OWNED FILES: isolated P10.1 state/market/save modules and focused tests; minimal
explicit P10 integration boundary only after migration tests pass.
ACCEPTANCE CHECKS: exact v6 migration; locked-region rejection; stable seed and
offers; atomic entry/Market commands; checksum/backup/rollback/corruption;
zero offline value; unchanged P10.0 saves and behavior.
EVIDENCE LEVEL EXPECTED: automated_verified.
COMMIT BOUNDARY: focused source/test push, then docs-only step closure.
LEGAL TERMINAL: P10.1 Step 2 Save v7 and Region entry complete.
NEXT STEP: P10.1-STEP-3.
```
### P10.1-STEP-3 FIRST-CROSSING BATTLE
```text
ID: P10.1-STEP-3
PLAYER OUTCOME: The chosen order/equipment/route visibly changes survival
under pull, tide movement, hindrance and healing-denial pressure.
IN SCOPE: fixed-tick first-crossing battle; seven enemy identities; tide shift;
equipment behavior; victory/defeat; bounded recovery; reward and Market 2.
OUT OF SCOPE: later Markets, Boss, runtime presentation, media and H5.
OWNED FILES: isolated P10.1 battle/settlement modules and focused tests.
ACCEPTANCE CHECKS: deterministic causal events; reserved-target timing; no
resurrection; exactly-once settlement; stable-order and deliberate-movement
counterfactuals each win at least one fixture; P10.0 battle unchanged.
EVIDENCE LEVEL EXPECTED: automated_verified.
COMMIT BOUNDARY: focused source/test push, then docs-only step closure.
LEGAL TERMINAL: P10.1 Step 3 first-crossing battle complete.
NEXT STEP: P10.1-STEP-4.
```
### P10.1-STEP-4 LANDSCAPE RUNTIME SLICE
```text
ID: P10.1-STEP-4
PLAYER OUTCOME: One touch-driven world flow reaches saved Market 2 with tide,
pull, healing denial, damage, recovery and reward readable at play size.
IN SCOPE: P10.1 runtime controller; direct world targets; touch/drag; localized
status; layout/accessibility states; event-bound graybox motion; recording.
OUT OF SCOPE: final media, later content, H5 and native delivery.
OWNED FILES: P10.1 presentation/controller/tests and the narrow main handoff.
ACCEPTANCE CHECKS: parsed Touch/Drag; fallback/direct zero; 44px targets;
required states/locales/viewports; no card-wall composition; 20-30 second
recording; strict diagnostics and owned cleanup zero.
EVIDENCE LEVEL EXPECTED: runtime_verified and agent_visual_reviewed.
COMMIT BOUNDARY: runtime source/test push, then source-bound evidence closure.
LEGAL TERMINAL: P10.1 Step 4 landscape runtime slice complete.
NEXT STEP: P10.1-STEP-4A after Owner motion review.
```
### P10.1-STEP-4A GAME-FEEL MOTION REPAIR
```text
ID: P10.1-STEP-4A
PLAYER OUTCOME: The first crossing visibly behaves like a battle: combatants
anticipate, contact, react, recover and move between tide positions while
damage, healing denial, permanent loss and victory remain readable.
IN SCOPE: presentation-only motion state; wave entrance; allied/enemy contact;
ranged projectile; pull interpolation; tide translation; healing-denial
tether; indexed-mud marker; damage pop; local impact pause; Fallen collapse;
victory recovery; reduced-motion and low-power transforms; focused runtime
checks and one fixed normal-render comparison recording.
OUT OF SCOPE: battle formulas/events/order, content, Save v7, input semantics,
new raster/audio generation, H5, native delivery and release.
OWNED FILES: P10.1 presentation/controller, bounded motion tests/recording and
durable status only.
ACCEPTANCE CHECKS: every declared feedback starts from an authoritative event;
attack has anticipation/contact/recovery; pull and tide use eased continuous
displacement rather than teleport; damage values rise/fade at the affected
actor; healing denial and indexed mud persist while relevant; Fallen cannot
return to an idle/advance loop; terminal victory has a distinct resting state;
feedback overlap is capped; all effects return to rest; reduced motion and
low power preserve essential state without changing results; parsed touch and
Save-v7 regressions pass; 20-30 second normal recording passes play-size
motion review with strict diagnostics and owned cleanup zero.
EVIDENCE LEVEL EXPECTED: runtime_verified and agent_visual_reviewed; Owner
motion/game-feel acceptance remains open.
COMMIT BOUNDARY: presentation source/test push, then source-bound evidence and
docs-only repair closure.
LEGAL TERMINAL: P10.1 Step 4A game-feel motion repair complete.
NEXT STEP: P10.1-STEP-5.
```
### P10.1-STEP-5 PROFILES AND CANDIDATE EVIDENCE
```text
ID: P10.1-STEP-5
PLAYER OUTCOME: The first crossing remains understandable and recoverable
across different strategies, layouts and restart conditions.
IN SCOPE: five profiles; decision timestamps; anti-dominance; save matrix;
locale/layout/accessibility matrix; immutable candidate evidence.
OUT OF SCOPE: gameplay expansion, H5 and native delivery.
OWNED FILES: `runtime/tests/p10_1/five_profile_simulation_test.gd` and UID;
`runtime/tests/p10_1/candidate_matrix_test.gd` and UID; immutable evidence
roots and durable status. Product source is read-only unless a declared gate
exposes a product failure inside this step.
ACCEPTANCE CHECKS: exact normal/active/efficient/adversarial/returning profiles;
explicit timestamps and maximum no-decision gap at most 12 seconds; five
distinct policy tuples; low/high-route counterfactual opposition; defeat
recovery without starvation or resurrection; returning interruption/reload;
Save-v7 phase matrix; required runtime states and layout/accessibility
combinations; strict diagnostics; clean/upstream source.
EVIDENCE LEVEL EXPECTED: simulation_verified plus runtime_verified.
COMMIT BOUNDARY: source-bound evidence and docs-only candidate closure.
LEGAL TERMINAL: P10.1 first-crossing local candidate complete.
NEXT STEP: P10.1-STEP-6 only after no product repair remains.
```
### P10.1-STEP-6 H5 DELIVERY
```text
ID: P10.1-STEP-6
PLAYER OUTCOME: One private landscape H5 exposes the complete Siltwake first
crossing for Owner review.
IN SCOPE: fresh runtime-only Web export; new Gallery item; byte/MIME/cache/ETag
checks; durable delivery closure.
OUT OF SCOPE: product edits, native packaging, devices, stores and release.
OWNED FILES: P10.1 delivery record and durable status only.
ACCEPTANCE CHECKS: exact source; tests/docs/evidence absent from PCK; remote
bytes and transport pass; clean/upstream repository; processes zero.
EVIDENCE LEVEL EXPECTED: delivery transport verified; human gates remain open.
COMMIT BOUNDARY: docs-only closure after immutable delivery.
LEGAL TERMINAL: Aetherbound Guild P10.1 Siltwake first crossing candidate ready.
NEXT STEP: Owner uncoached play review.
```
## Frozen Scope
P10.0 behavior/Save v6/H5, later Siltwake content, Boss execution, later
Regions, existing media before the graybox gate, native packaging, stores,
release and other games remain frozen.
## Issue Register
<!-- markdownlint-disable MD013 -->
| ID | Status | Finding |
| --- | --- | --- |
| P101-I01 | `RESOLVED_IN_PLAN` | P10.0 validators own exact RG-01 counts and IDs. P10.1 begins as an isolated overlay and may integrate only through the explicit Save-v7 step. |
| P101-I02 | `RESOLVED_STEP_2` | P10.1 projects only three Recruit records from the accepted P10.0 generator, rebinds their Region offer identities and retains exact provider metadata without copying its algorithm. |
| P101-I03 | `GRAYBOX_PASSED_STEP_4` | Step 4 proves the Siltwake composition and event-bound motion with layered graybox treatment. Final regional media remains a later presentation task and is not silently claimed by this slice. |
| P101-I04 | `RESOLVED_STEP_3` | Early P10.1 receipts embedded full snapshots and caused recursive growth. Step 3 replaces them with compact operation metadata while retaining read compatibility for the unreleased earlier format. |
| P101-I05 | `RESOLVED_STEP_4` | The first development recording attempt stopped before gameplay on two missing Boolean annotations and produced zero frames. The script was repaired before source commit; no output from that dirty-tree attempt is reused. |
| P101-I06 | `RUNTIME_REPAIRED_OWNER_GATE_OPEN` | Step 4A replaces looping whole-line jitter with event-bound contact, eased displacement, actor-local feedback and terminal body states. Fixed-source runtime and agent visual review pass; only Owner motion/game-feel acceptance remains open. |
<!-- markdownlint-enable MD013 -->
## Completed Step Evidence
### P10.1 Step 1 Content And First Market Authority - 2026-08-15
- Source `fedfa0933f819788349e55054da3dd316815ba07` adds exactly the
isolated P10.1 catalog, registry, first-Market generator, two focused tests
and their tracked UID files. P10.0 source remains unchanged.
- The registry binds the three accepted content-document blobs and exposes 21
localized runtime identities: one Region, one Contract, eight equipment
rows, seven enemies, one reference-only Boss and three routes.
- Market 1 reserves the future three Recruit slots and deterministically
exposes four unique regional equipment offers, ordered risk `0/1/2` routes,
current/next safe indices, a 50-tick shift, 20-tick warning and the first
pull source. Refresh changes equipment only; route and tide authority never
reroll.
- Formal R1 is append-only `INVALID_GIT_SCOPE_PRECHECK`: its baseline object
identifier was malformed before scope capture. No R1 test log is reused.
- Fresh fixed-source R2 evidence is
`/private/tmp/abg-p101-fedfa09-step1-r2/`. Both P10.1 tests and the frozen
P10.0 content/offer regressions pass with four exact markers, strict
diagnostics zero and Godot pre/post counts zero. The ten-row inventory
SHA-256 is
`c00ce93702a7789d27f2e4b31ab987102afe215eee448e6b4f90e545aa09d5a3`.
- Step 1 reaches `automated_verified`. Step 2 alone now owns Save v7, Region
entry, Recruit-slot materialization and Market-1 persistence.
### P10.1 Step 2 Save V7 And Region Entry - 2026-08-15
- Source `c46af4e8e08eab5e2b6b8e1d6965f5aa7c3965ca` adds only four
isolated P10.1 modules, two focused tests and their tracked UID files. P10.0
source remains unchanged.
- A closed Save-v6 Guild migrates to Save v7 only when both Windglass facts and
RG-02 unlock are present and no Run/draft is active. Sequence and previous
commit bind the migration; checksum, backup, rollback, candidate interruption
and zero offline value remain authoritative.
- One atomic Region entry consumes one deterministic ordinal, creates a stable
Run seed and binds three projected Recruit offers to the Step-1 regional
board. The player can refresh regional equipment without rerolling tide or
routes, hire two Recruits, buy/equip one regional response, accept automatic
order, change order and save one prepared route.
- Ten applied operations each increment exactly one revision. Four targeted
rejection branches preserve the complete state, and entry receipts remain
idempotent after Save-v7 reload.
- Fresh fixed-source R1 evidence is
`/private/tmp/abg-p101-c46af4e-step2-r1/`. Four P10.1 and five frozen P10.0
markers pass with strict diagnostics and Godot pre/post counts zero. The
15-row inventory SHA-256 is
`98c0c4a84bde9f0cde9baa00c52f0df5f7b1d1e85c40f48d78991bb12ea37379`.
- Step 2 reaches `automated_verified`. Step 3 alone now owns battle execution,
settlement, recovery and Market-2 advance.
### P10.1 Step 3 First-Crossing Battle - 2026-08-15
- Source `ef9d92b95b7dd359a92a374e4f1e455f54fbb369` adds the fixed-
tick battle, settlement, shared fixture and two focused tests while extending
only the isolated P10.1 state/service phases. P10.0 source remains unchanged.
- The `100ms` timeline records wave entry, healing denial, healing conversion,
timed hindrance, pull/resist, indexed mud, tide warning/shift, allied/enemy
actions, authoritative damage, permanent Fallen and terminal cause within
200 ticks.
- `hold_line` preserves more vitality on the safe Reedbank route, while it
loses the high Broken Sluice route with a permanent casualty and
`follow_tide` wins it. This proves an opposed state-dependent response rather
than one universal plan.
- Victory grants the disclosed reward once and saves a source-bound Market-2
handoff. Defeat permanently removes Fallen identity/equipment ownership,
preserves survivors and enters exact-cost recovery without resurrection.
- An early development run exposed recursive receipt snapshots. The source
now stores compact idempotency metadata compatible with the unreleased legacy
receipt shape; Step-2 state/Save tests pass again after the repair.
- Fresh fixed-source R1 evidence is
`/private/tmp/abg-p101-ef9d92b-step3-r1/`. Six P10.1 and six frozen P10.0
markers pass with strict diagnostics and Godot pre/post counts zero. The
18-row inventory SHA-256 is
`bdeb913d282aa5338cd29a3fa8e08d92becbbda103bf69e629f491041c2ff855`.
- Step 3 reaches `automated_verified`. Step 4 now owns runtime presentation and
input only; gameplay expansion, final media and H5 remain frozen.
### P10.1 Step 4 Landscape Runtime Slice - 2026-08-15
- Source `0659b500424ea9c8c872c039e61cd49388fa1941` adds one P10.1
controller, one runtime fixture, touch/layout/recording programs and tracked
UID files. The only integration edit makes the canonical `main.gd` load the
compatibility controller; accepted P10.0 source and Save-v6 behavior remain
unchanged.
- A closed Windglass Guild now exposes a direct Siltwake world gate. Market 1
renders Recruit actors, equipment objects, route posts, current/next safe
positions and countdown without app panels or a card wall. Parsed touch hires
two Recruits, buys/equips one regional response and selects the route; parsed
drag changes the front-to-rear order.
- The opposed `hold_line` and `follow_tide` targets replay the accepted fixed-
tick authority rather than recalculating combat in presentation. Small
horizontal actors visibly bind pull, indexed mud, healing denial, tide shift,
damage text, permanent Fallen, recovery, reward and saved Market 2.
- A dirty-tree development recording attempt is retained separately as
`INVALID_HARNESS_PARSE` with zero frames and contributes no judgment. Fresh
fixed-source R1 is `/private/tmp/abg-p101-0659b50-step4-r1/`.
- R1 retains 19 exact success markers: eight P10.1 headless programs, nine
affected P10.0 regressions, one normal-render matrix and one MovieWriter
flow. Touch flow records `16` Touch / `1` Drag; the recording records `13`
Touch / `1` Drag; fallback/direct remain zero.
- Ten normal frames cover `760x360`, `844x390`, `1280x720`, portrait guidance,
zh_CN/en, 130% text, reduced motion, mute and low power. The fixed recording
is `844x390`, 30 FPS, 836 frames and `27.866667s`. Agent visual review passes;
strict diagnostics and owned process counts are zero.
- The 42-row inventory verifies completely; its SHA-256 is
`fa94b83f98d9e2ff3b17eb01976b6cb232511097351c6e51c100743ca1ed89d5`.
Step 4 reaches `runtime_verified + agent_visual_reviewed`. Human
understanding/fun/visual/listening, final media, devices and release remain
open. Step 5 now owns profiles, decision timestamps and candidate evidence.
### P10.1 Step 4A Game-Feel Motion Repair - 2026-08-15
- Source `47f2028c71215117d5cc37ffc7bb2797d9e9c84c` adds one isolated
motion presenter, focused semantic/runtime tests and the controller binding.
Battle formulas, events, results, Save v7, content and input semantics are
byte-unchanged from the accepted Step-4 authority.
- Enemy waves enter from the right and occupy continuous center-facing slots.
The front Recruit is closest to contact; attacks expose anticipation,
contact and recovery; pull and tide interpolate; actor-local projectiles,
impacts and damage values are capped; healing denial and indexed mud remain
persistent; Fallen, victory and enemy death cannot resume an unrelated loop.
- Reduced-motion and low-power transforms preserve the event state with less
displacement. Pausing also freezes presentation time. The runtime integration
test proves the presenter never mutates the complete battle snapshot.
- R1 `/private/tmp/abg-p101-47f2028-step4a-r1/` is append-only
`INVALID_EVIDENCE_AGGREGATION`: the final marker command used `rg -h`, which
emits help in the installed ripgrep. R2
`/private/tmp/abg-p101-47f2028-step4a-r2/` is append-only
`INVALID_PYTHON_ENVIRONMENT`: isolated Python lacked PIL during capture
summarization. Neither attempt contributes candidate evidence.
- Fresh fixed-source R3 is
`/private/tmp/abg-p101-47f2028-step4a-r3/`. Eight headless tests, one normal
layout run and one MovieWriter run produce ten exact markers. Strict
diagnostics, black intervals and owned post-run Godot processes are zero.
- Ten normal frames cover the declared layouts and accessibility states. The
fixed recording is `844x390`, 30 FPS, 836 frames and `27.866667s`; its
SHA-256 is
`a3fad80afc34578ad4eb56a0b8e10f98c711dda7e8294d711af989fa67c8170e`.
The 36-row evidence inventory verifies completely; inventory SHA-256 is
`611f8578a0d2b3d3ace9f463c1e025e30095598a8887bf3d53c07ce88222dc25`.
- Step 4A reaches `runtime_verified + agent_visual_reviewed`. Owner
motion/game-feel acceptance remains open. Step 5 is pending and no H5,
package, device, store or release action occurred.
### P10.1 Step 5 Profiles And Candidate Evidence - 2026-08-15
- Candidate source `d964ca9774b1c341b104921f7bed91d37faeabb8` adds only two
P10.1 simulation/matrix programs and tracked UID files over accepted product
source `47f2028c71215117d5cc37ffc7bb2797d9e9c84c`. Product runtime,
battle values, Save v7 schema, content and media remain unchanged.
- Normal, active, efficient, adversarial and returning profiles use five
distinct risk/plan tuples. They record 36 explicit decision timestamps with
a `10.6s` maximum gap, cover risks `0/1/2` and both plans, and independently
prove the low/high-route counterfactual preference reversal.
- The adversarial high-route hold loses one permanent Recruit, pays bounded
recovery and never resurrects the Fallen. Returning reloads before battle
and after settlement. Starvation, negative Coin and offline rewards are zero.
- The candidate matrix roundtrips five Save-v7 phases and checks 32 layout
combinations across `760x360`, `844x390`, `1280x720`, `390x844`, zh_CN/en,
100/130% text, reduced motion, mute and low power. Buttons remain at least
48px; app panels and card/modal surfaces remain zero.
- Fresh immutable R1 evidence is
`/private/tmp/abg-p101-d964ca9-step5-r1/`, bound to source archive SHA-256
`1a4e1d34b9be0e0652330bbf1a676af6c6ad9c50de4204d7bdf41eedec3465f3`.
Twenty-two headless programs, one normal layout run and one MovieWriter flow
produce 24 exact markers. Strict diagnostics, black intervals and owned
post-run engine processes are zero.
- Ten fresh normal captures and the unchanged-product `844x390`, 30 FPS,
836-frame, `27.866667s` recording pass supporting visual review. The 49-row
inventory verifies completely; inventory SHA-256 is
`f8bf7359500859c926ab461829c94608ba3e85cbb72749f336fafb80c04c04c8`.
- Step 5 reaches `simulation_verified + runtime_verified +
agent_visual_reviewed`. Owner understanding, fun, choice quality,
motion/visual/listening acceptance, H5, device, package, store and release
remain open. Step 6 is pending and not authorized by this closure.