diff --git a/docs/lantern-fuel-scope.md b/docs/lantern-fuel-scope.md index de7a624..d378bcd 100644 --- a/docs/lantern-fuel-scope.md +++ b/docs/lantern-fuel-scope.md @@ -41,4 +41,29 @@ An explicit Refuel action does not solve automatic burn compatibility: old ticks Separate compatibility plumbing and actual gameplay slices in the dependency graph. Inventory affected constructors/serializers first, then review exact plan before writers. Test genuine v4 decode/reencode/replay hashes plus resumed/exported continuity; unknown/mismatched version pairs rejected; new default fuel consumption, refill, depletion/extinction, multiple-lamp/drop/light-cache and sleep semantics deterministic; save/checkpoint/replay reconstruct same future behavior. Use ordinary starter content/process inputs, focused opt1 checks and one frozen checkpoint per development-validation.md. Preserve existing fixture files and provenance. No additional old-Rust matrix. +## Constructor and wire inventory (read-only follow-up) + +These are current symbols, not implemented new APIs. Line anchors refer to gameplay baseline757962b and may shift. No LegacyV4/FuelV5 selector or RunIdentity constructor methods exist today; identity construction uses struct literals. + +| Boundary | Current symbols / source anchors | Required consideration in proposed versioned design | +|---|---|---| +| Core construction | `State`, `State::new(seed)`, state.rs147–176,401–451 | Explicit immutable semantics before initialization; no silently changed existing caller defaults. | +| Full versus unattended time | `State::step`, `phase_light`, `preflight_unattended`, `advance_unattended`, `spend_copper_and_advance_unattended`, state.rs1717–1815,2262–2269 | Separate specified burn behavior; retain legacy spatial omissions and paid-time atomicity. | +| Images | `StateImage`, checkpoint.rs46–87; `State::to_image/from_image`, state.rs2484–2693 | Selector survives all reconstruction and is validated, not defaulted. | +| Hashing | `CANONICAL_HASH_VERSION`, `try_hash_state`, state.rs260–265,2696–2860 | Exact legacy prefix/domain stream; new hash contract includes new future-affecting state. | +| Identity | `RunIdentity`, `identity_to_wire/from_wire`, protocol.rs567–579,1525–1560 | Immutable reconstruction input, no CLI-only selector lost during replay. | +| Envelopes/wire | `EnvelopeHeader`, `RunWire`, `ReplayWire`, `RunIdentityWire`, protocol.rs774–814; version gates1409–1453 | Preserve v4 layout; validated format/hash pair may infer selector, then materialize it in runtime/image boundaries. | +| Run codecs | `encode_run/decode_run`, protocol.rs1222–1283 | Version-dispatch codec and validate identity/current/checkpoint consistency. | +| Replay codecs | `encode_replay/decode_replay`, protocol.rs1286–1336; entry.rs683–710 | Replay has identity/events, no state snapshot; semantics must reach bootstrap before any tick. | +| Hashed images | `HashedState`, `hashed_state_to_wire/from_wire`, `validate_hashed_image`, protocol.rs581–620,1756–1819 | Image→State recomputes hash; selector cannot live only on decoder. | +| Checkpoints | `StoryCheckpoint`, protocol.rs623–628,1788–1804; `build_checkpoint`, session.rs2335–2364 | Same semantics throughout checkpoint creation, prefix proof and resurrection. | +| New/resumed sessions | app.rs372–419 identity literal; `from_identity`, session.rs995–1079; `from_decoded`,1917–1958 | New bootstrap creates kit/standalone light; resume reconstructs decoded state directly. Both must be explicit. | +| Source movement/resurrection | `sync_player_light*`, session.rs3214–3227,4260–4268; resurrection2278–2297 | Legacy index0 behavior versus new owned lamp source and invalidation. | +| Replay/time/lifecycle | session.rs2060–2341,3597–3647; Inn3481–3503; app budget1868–1872 | Full idle ticks, unattended Inn time and checkpoint restoration all preserve selector/timeline. | +| Durable artifacts | save/artifact/mod.rs1299–1324,1729–1737 codec consumers | Coordinate downstream save/replay identity construction and validation. | + +Core owns State/image/light/item and must not gain a content dependency: content already depends on core. Save owns identities/hashed states/wire/codecs and depends on core/content. CLI owns startup/replay/lifecycle and presentation. Core and Save workers may only proceed with frozen shared signatures; CLI follows their interface checkpoint. Do not assign overlapping state/image/protocol/session constructor changes to independent workers. + +Existing oracle targets (not rerun during this inventory): Save `genuine_pretransfer_v4_fixtures_decode_and_reencode_identically` and `genuine_v3_run_replay_fixtures_reject_before_v4_body_parse`; immutable Classic/Story v4 run fixtures and v4 replay plus provenance. Core `same_seed_same_hash`, `full_tick_mutates_and_hashes`, `unattended_advance_matches_empty_world_clock_scope`, `unattended_advance_overflow_is_atomic`. CLI `exact_run_restore_retains_state_history_and_continuation`, `mixed_replay_reconstructs_same_tick_actions_idle_gaps_and_terminal_hash`, `inn_service_charges_unattended_work_before_dispatch`, `resume_resurrection_export_replay_matches`, `repeated_resurrection_keeps_ordered_history_and_active_checkpoint_reference`, `resurrection_continue_export_replay_matches`, `story_death_restores_town_checkpoint_and_can_repeat`, `deep_to_town_refreshes_checkpoint_after_transition_event`, `v4_replay_preserves_latest_story_checkpoint_reference`. These existing tests do not certify a proposed selector or fuel system. + Research itself does not certify a fuel mechanic or authorize broad compatibility implementation. Next useful work is a bounded exact version/lantern wiring plan, then independent review and any remaining operator-owned decision.