azurkit 1.0.0__py3-none-any.whl

azurkit/tools/randomizer/data/world.toml

@@ -0,0 +1,368 @@
+# Imported at Step R1.4 from the R0 evidence repo @ 4b8f3f3 (db-draft/world.toml), re-imported at Step R1.4b @ 7530b0b (D145, rjc5), format keys /1; R0's scripts stay there.
+# Below, FORMAT is docs/RANDOMIZER_DB.md, db-draft/ is azurik_mod/randomizer/data/, and R0's checks (db_check.py,
+# tricks_check.py) are `azurik-mod rando check`.
+# world.toml: start, hub, victory, the trick families and the non-monotone mechanisms (DRAFT, R0.6, 2026-10-11;
+# trick families revised 2026-10-12 for D113; six added for D120).
+# Spec: db-draft/FORMAT.md section 7.
+
+format = "azurik-rando-world/1"  # prefilled
+start = "w1_beach"  # migrated, unverified (starting_node; the owner's notes agree)
+hub = "town_central"  # prefilled (RANDOMIZER_PLAN section 2.3; logic_db's town_core)
+victory = "flag:d1.spideyzar.killed"  # prefilled (D76 / RQ-1; replaces logic_db's discs + placement events)
+starting_items = []  # migrated, unverified
+# logic_db victory_condition was: {"type":"all_of","items":["disc_air","disc_water","disc_fire","disc_earth","disc_life","event_place_disc_air","event_place_disc_water","event_place_disc_fire","event_place_disc_earth","event_place_disc_life"]}  # migrated, unverified
+
+# Trick families (D113, 2026-10-12): a trick has no tier; difficulty sits on each skip, in the levels' [[skip]]
+# lists (FORMAT 4.8). Drafted from tricks/tricks.toml, whose `name` and `description` project here (tricks_check).
+# Before D113 each entry also carried default_tier (bskip 2, pstorage 3, saveanywhere 5, rjump 3, tjump 3, itrig 3,
+# nolight 1; prefilled proposals).
+
+[[trick]]  # drafted (D113)
+name = "bskip"  # prefilled (OWNER_NOTES)
+description = "barrier skips: a general term for skipping any barrier, such as the fire barrier between w1 and town (e.g. around it with air power 2)"  # drafted from tricks/tricks.toml (the owner's words, shortened)
+
+[[trick]]  # drafted (D113)
+name = "pstorage"  # prefilled (OWNER_NOTES)
+description = "power storage: in the tutorial select powers with LT held but don't evoke them, load another save, then release LT: the power is evoked even if that save has no access to it (e.g. an air flap with no air levels)"  # drafted from tricks/tricks.toml (the owner's words, shortened)
+
+[[trick]]  # drafted (D113)
+name = "saveanywhere"  # prefilled (OWNER_NOTES)
+description = "save anywhere: the in-game cheat White, Up, Down, A, B, right-stick press saves anywhere; saving and reloading allows falling infinitely, resets fall damage, or rarely clips through geometry"  # drafted from tricks/tricks.toml (the owner's words, shortened)
+
+[[trick]]  # drafted (D113)
+name = "rjump"  # prefilled (OWNER_NOTES)
+description = "roll jump: chain rolls off a ledge and jump on the frame a roll ends; the fall is cancelled and air flaps work again; limited by deaths after free falling too long"  # drafted from tricks/tricks.toml (the owner's words, shortened)
+
+[[trick]]  # drafted (D113)
+name = "tjump"  # prefilled (OWNER_NOTES)
+description = "tree jump: hold up and press jump repeatedly on a ladder against certain geometry, with no air shield worn, to charge jump velocity, released as a super jump at the top; mostly used to skip the puzzle that opens the Great Tree to the air realm, with no powers"  # drafted from tricks/tricks.toml (the owner's words, shortened)
+
+[[trick]]  # drafted (D113)
+name = "itrig"  # prefilled (OWNER_NOTES)
+description = "invisible triggers: clip through the level geometry in a few rare places and activate a trigger such as a level-loading zone; mostly in w1, to skip the dark cave and reach the alternate route to town where a water disc fragment is"  # drafted from tricks/tricks.toml (the owner's words, shortened)
+
+[[trick]]  # drafted (D113)
+name = "nolight"  # prefilled (OWNER_NOTES)
+description = "no light: doing a dark room or maze without the fire power; possible but inconvenient"  # drafted from tricks/tricks.toml (the owner's words, shortened)
+
+# D120 (owner, 2026-10-12): the six video moves become families, each its own and with no tier; their skips stay
+# held until xemu or the owner confirms them (D114).
+
+[[trick]]  # D120 (owner, 2026-10-12)
+name = "elevbounce"  # D120
+description = "elevator bounce: land on the moving d1 central-spire elevator at the right moment and spot (holding forward, steadied with flaps) and bounce past most or all of its puzzle"  # drafted from tricks/tricks.toml (VIDEO_CATALOGUE 1.2, in plain words)
+
+[[trick]]  # D120 (owner, 2026-10-12)
+name = "iceclimb"  # D120
+description = "ice climb: get up slippery ice, or a slide meant for coming down, by hopping up its centre line or flying it with flaps (w3's ice jet or bridge to frag_fire_1 without the frost switch; the e6 slide)"  # drafted from tricks/tricks.toml (VIDEO_CATALOGUE 1.2, in plain words)
+
+[[trick]]  # D120 (owner, 2026-10-12)
+name = "ledgepop"  # D120
+description = "ledge pop: from high ground, drop off one ledge just right and Azurik pops up the wall; in f4 it skips most of the level and the Blaze Sentinel fight on the way to the battle platform, and needs a lot of air fuel"  # drafted from tricks/tricks.toml (VIDEO_CATALOGUE 1.2, in plain words)
+
+[[trick]]  # D120 (owner, 2026-10-12)
+name = "elevjump"  # D120
+description = "lift jump: jump at the top of a rising lift, or touch a moving platform while moving, and keep its speed for extra height (f3's lifts, e2's tower lift, e5's moving platform)"  # drafted from tricks/tricks.toml (VIDEO_CATALOGUE 1.2, in plain words)
+
+[[trick]]  # D120 (owner, 2026-10-12)
+name = "botstep"  # D120
+description = "bot step: draw enemies' attention and use their invisible hitboxes as steps (w3, over the icebergs); how it is done is not known"  # drafted from tricks/tricks.toml (VIDEO_CATALOGUE 1.2, in plain words)
+
+[[trick]]  # D120 (owner, 2026-10-12)
+name = "flipcancel"  # D120
+description = "flip cancel: a little flip on landing after a roll jump cancels momentum that would otherwise kill (a5's monolith); the input is not known"  # drafted from tricks/tricks.toml (VIDEO_CATALOGUE 1.2, in plain words)
+
+[[trick]]  # D630 (owner, 2026-10-24, Step R2.18)
+name = "flutter"  # D630: the owner's name, "air fluttering"
+description = "air fluttering: in mid-air, cast the air armor again (LT+Y) once its flaps are spent, for another flap, at 2 air fuel a cast; a flight is bounded by the air fuel, not the armor's flap count"  # drafted from tricks/tricks.toml (the owner's X.67 demo, D630)
+
+# Time-savers (D145, owner 2026-10-12, verbatim: "keep in mind some of the tricks you saw in the speedrun video are
+# not skips, bur rather just meant to save time."): each goes where plain movement with the same kit already goes,
+# only faster, so it is never in logic. Listed here (id, name, level, tricks; projected from tricks/tricks.toml
+# [[time_saver]], which tricks_check checks) for the spoiler's routing notes and so the loader can refuse one in
+# logic: no expression may name skip:<its id>, no level file may hold it, and no settings toggle may name it
+# (FORMAT 4.9). The level files never name one.
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "w1.rjump_teleporter_island"
+name = "w1 teleporter-island roll jump"
+level = "w1"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "f3.rjump_earth_frag"
+name = "f3 roll jump to frag_earth_2"
+level = "f3"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "f3.rjump_earth_power"
+name = "f3 roll jump to the earth power 1 platform"
+level = "f3"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e2.rjump_lethal_drop"
+name = "e2 four-roll lethal drop"
+level = "e2"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e2.rjump_entrance_tree"
+name = "e2 four-roll jump into the tree"
+level = "e2"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e2.rjump_gondola_key_slope"
+name = "e2 roll jump down the slope (second gondola key)"
+level = "e2"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e2.rjump_drill_room_drop"
+name = "e2 drill-room roll jump"
+level = "e2"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e2.rjump_bridge"
+name = "e2 three-roll jump onto the bridge"
+level = "e2"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e2.rjump_excavator"
+name = "e2 roll jump to the excavator"
+level = "e2"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e5.rjump_conveyor_ladder"
+name = "e5 conveyor roll jump to the ladder (air 2)"
+level = "e5"
+tricks = ["rjump"]
+
+[[time_saver]]  # Step R1.31b (2026-10-19, the owner's X.35 C3)
+id = "e5.rjump_conveyor_ladder_air1"
+name = "e5 conveyor roll jump to the ladder (air 1)"
+level = "e5"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e5.rjump_five_roll_drop"
+name = "e5 five-roll drop (air 2)"
+level = "e5"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e5.double_rjump_earth_power2"
+name = "e5 double roll jump to earth power 2"
+level = "e5"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e6.rjump_entrance_drop"
+name = "e6 three-roll drop after the entrance"
+level = "e6"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "a1.rjump_branches"
+name = "a1 branch-to-branch roll jump"
+level = "a1"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "a1.pipe_flight"
+name = "a1 pipe flight to the tree top"
+level = "a1"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "a5.monolith_flipcancel"
+name = "a5 monolith roll jump with a flip cancel"
+level = "a5"
+tricks = ["rjump", "flipcancel"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "town.towerfall_centre"
+name = "town centre towerfall (five-roll jump)"
+level = "town"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "d1.spires"
+name = "d1 spires (skips d2)"
+level = "d1"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "a6.rjump_platforms_green"
+name = "a6 roll jumps to the green key"
+level = "a6"
+tricks = ["rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "a6.iceblock010_air2"
+name = "a6 IceBlock_010 round the end (air 2)"
+level = "a6"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "a6.iceblock012_air2"
+name = "a6 IceBlock_012 round the end (air 2)"
+level = "a6"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e6.firewall01_air1"
+name = "e6 FireWall_01 (air 1)"
+level = "e6"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "w2.iceblock01_air3"
+name = "w2 IceBlock_01 (air 3)"
+level = "w2"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "w3.iceblock016_air2"
+name = "w3 IceBlock_016 (air 2)"
+level = "w3"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "w3.iceblock024_air1"
+name = "w3 IceBlock_024 (air 1)"
+level = "w3"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "w3.iceblock024_no_air"
+name = "w3 IceBlock_024 (no air)"
+level = "w3"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "w3.iceblock026_air2"
+name = "w3 IceBlock_026 (air 2)"
+level = "w3"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "a6.acid_fly_around"
+name = "a6 level-3 acid fly-around (a key)"
+level = "a6"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e2.firewall_walkthrough"
+name = "e2 lit fire wall walk-through (fire power 1)"
+level = "e2"
+tricks = ["bskip"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e6.vine_launch_upper"
+name = "e6 vine launch to the upper section"
+level = "e6"
+tricks = ["tjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "a1.air_tube_oob"
+name = "a1 out-of-bounds to the air tubes"
+level = "a1"
+tricks = ["itrig", "rjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e5.dark_interior_nolight"
+name = "e5 frag_fire_3 interior without light"
+level = "e5"
+tricks = ["nolight"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "f3.elevjump_earth_frag"
+name = "f3 lift boost to frag_earth_2"
+level = "f3"
+tricks = ["elevjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e2.elevjump_excavator_key1"
+name = "e2 tower lift jump to excavator key 1"
+level = "e2"
+tricks = ["elevjump"]
+
+[[time_saver]]  # D145 (2026-10-12)
+id = "e5.elevjump_earth_power2"
+name = "e5 moving-platform jump to earth power 2"
+level = "e5"
+tricks = ["elevjump"]
+
+[[time_saver]]  # Step R2.17b (2026-10-24, the owner's D657)
+id = "w3.botstep_icebergs"
+name = "w3 bot steps over the icebergs"
+level = "w3"
+tricks = ["botstep"]
+
+[[time_saver]]  # Step R2.18 (2026-10-24, the owner's X.67 demo, D655)
+id = "f6.seal_skip"
+name = "fire power 3 / fire disc 4 skip (f6 seal)"
+level = "f6"
+tricks = ["bskip"]
+
+[[time_saver]]  # Step R2.18 (2026-10-24, the owner's X.67 demo, D656)
+id = "a5.rings_air_power3"
+name = "a5 ring roll jump to air power 3"
+level = "a5"
+tricks = ["rjump"]
+# Non-monotone mechanisms (RANDOMIZER_PLAN section 3.1): the loader refuses a database that uses one without
+# declaring it here. Handling: forfeitable | product_bit | out_of_logic | harmless | keys_vanilla.
+
+[[mechanism]]  # prefilled
+id = "disc_teleport"  # prefilled
+kind = "one_shot_teleport"  # prefilled
+handling = "forfeitable"  # prefilled (RQ-4 / D81)
+note = "a6, w3, f6, e5: count >= 4 AND the town has not placed the disc; w1 BossDefeated: water >= 4 and a touch, no placed check; life: none (thresholds/disc_chains.txt). Level-triggered [inferred, static: the gameState is refreshed every frame, 0x711C0]; TODO(R0.4b-ii) I-7(a,d,e)"  # prefilled
+
+[[mechanism]]  # prefilled
+id = "timed_barriers"  # prefilled
+kind = "respawn"  # prefilled
+handling = "harmless"  # prefilled proposal
+note = "barriers with persist timed or level_reset are re-checked on every crossing; the 32 FireWall OpenNCloseToggles are unsaved with a stored turnOff (thresholds/barrier_levels.txt) [inferred, static]; TODO(R0.4b-i) I-8, I-15"  # prefilled
+
+[[mechanism]]  # prefilled
+id = "toggles"  # prefilled
+kind = "toggle"  # prefilled
+handling = "out_of_logic"  # prefilled proposal
+note = "a toggle whose off state gates an edge is a load error until modelled (RANDOMIZER_PLAN 2.5)"  # prefilled
+
+[[mechanism]]  # prefilled
+id = "key_slot_cap"  # prefilled
+kind = "capacity"  # prefilled
+handling = "keys_vanilla"  # prefilled proposal
+note = "5 key slots, a 6th type is refused [verified static, RAM_RECIPES section 4: 0x58090, 0x587B0]; TODO(R0.4a) confirm in xemu, then RANDOMIZER_PLAN risk 4 applies"  # prefilled
+
+[[mechanism]]  # prefilled
+id = "w4_daynight"  # prefilled
+kind = "cycle"  # prefilled
+handling = "harmless"  # prefilled proposal
+note = "the 5 fan platforms unfold while day night timer is in [0.25,0.75) (generated/w4.json; thresholds/w4_daynight.txt); no clock-driven node is saved (wiring/saved_nodes.json), so nothing latches on the clock [inferred]: a wait, not a flag; TODO(owner, R0.7) I-19"  # prefilled
+
+[[mechanism]]  # prefilled
+id = "gem_fuel_upgrade"  # prefilled
+kind = "spend"  # prefilled
+handling = "out_of_logic"  # prefilled proposal
+note = "a gem pickup can run the fuel-cap upgrade, which subtracts gems from the slot (0x58639-0x58642) and raises a fuel cap (0x586BB) [verified static, ramdis.py dis 0x585f0:70; RAM_RECIPES section 2.1]; the gem counters count items collected, not the in-game value, so a data gate on the in-game gem counters is non-monotone; gems stay out of v1 logic (plan 2.8)"  # prefilled
+
+[[mechanism]]  # prefilled
+id = "minecart_e2e5"  # prefilled
+kind = "cart"  # prefilled
+handling = "out_of_logic"  # prefilled proposal
+note = "e2-side one-bit state DownToggle (saved), set by riding SwitchE5a and cleared only by arriving at E5a_E2a and touching TriggerShape (logic_dump.py e2); e5's MineCarToggle is e5's side [inferred, static]; both e2 gondolas need the 2 key_circuitboard locks [inferred, physical]; TODO(R0.4b-ii) I-10"  # prefilled
+
+[[mechanism]]  # prefilled
+id = "minecart_e2e7"  # prefilled
+kind = "cart"  # prefilled
+handling = "harmless"  # prefilled proposal
+note = "e2-side one-bit state DownToggle1 (saved), cleared by arriving at E7_E2 and touching Trigger2Shape; e7's only exit E7_E2_switch lands at E7_E2 (generated/e7.json), so the round trip resets it [inferred, static]; SwitchE5a1 is the only exit into e7 (generated), so it stays in logic, with both circuitboard locks [inferred, physical]; TODO(R0.4b-ii)"  # prefilled

azurkit/tools/randomizer/dbcache.py

@@ -0,0 +1,197 @@
+"""The planner loader's database key and load (``planner/loader.py``'s
+``load_database`` and ``kept_logic`` call them), in place of Modkit's
+``planner/dbcache.py``, which keeps the checked database as a pickle in the
+user cache. AzurKit keeps none on disk: the site's worker has no lasting
+disk, and a pickle read back from a folder the program writes runs what it
+holds. ``kept_logic`` keeps the :class:`~.planner.solver.Logic` it builds
+for the process, under :func:`entry`'s key.
+
+The wheel and the frozen app ship the checked database instead (Step 4.3g,
+P4): ``shipped/<key>.pickle`` beside this module, which their builds write
+(:func:`ship`, from ``scripts/web_tools.py`` and ``scripts/freeze.py``;
+generated, never in the checkout). :func:`load` serves it for the key it was
+made for, so a changed data file or planner module reads and checks the
+database as before (about 4 s); it is read only from the wheel (its RECORD
+lists it) or the frozen app, never from a checkout. Its file holds the
+database's skip table first (:func:`shipped_skips`: a page's remembered
+randomizer is checked against it, about 14 KB, never the 87.6 MB logic,
+Step 4.4bd), then the database; the logic's read is counted.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import gc
+import hashlib
+import importlib.metadata
+import io
+import pickle
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from azurkit.core import progress
+
+PLANNER = Path(__file__).resolve().parent / "planner"
+SHIPPED = Path(__file__).resolve().parent / "shipped"
+# The frozen app's planner is in its archive, not files, sealed with the data it ships: its key is the data's alone.
+FROZEN = bool(getattr(sys, "frozen", False))
+NOTES = 20   # the logic's read is a core.progress note each twentieth of its file ("reading its logic, k of 20")
+
+
+def entry(root: Path, planner: Path | None = None if FROZEN else PLANNER) -> Path:
+    """The key of the database at ``root``, as a path whose name is the
+    sha256 (32 hex digits) of the name and bytes of each file under it and
+    under the planner's code (``planner``; None: the data's alone, as the
+    frozen app's): a changed file gives another key. Each file's bytes are
+    hashed again only once its size or its modification or change time
+    differs (:func:`_file`): ``kept_logic`` asks the key each call, eight
+    times in a plan's first tracker view."""
+    h = hashlib.sha256()
+    for folder in (Path(root), *([planner] if planner is not None else [])):
+        for path in sorted(folder.rglob("*")):
+            if path.is_file() and "__pycache__" not in path.parts:
+                h.update(f"{path.relative_to(folder).as_posix()}\0".encode())
+                h.update(_file(path))
+    return Path(h.hexdigest()[:32])
+
+
+_FILES: dict[Path, tuple[tuple[int, int, int], bytes]] = {}   # a file -> (its size and times, its bytes' sha256)
+
+
+def _file(path: Path) -> bytes:
+    """The sha256 of ``path``'s bytes, kept while its size, modification and change times stay as they were."""
+    at = path.stat()
+    stamp = (at.st_size, at.st_mtime_ns, at.st_ctime_ns)
+    if (kept := _FILES.get(path)) is not None and kept[0] == stamp:
+        return kept[1]
+    digest = hashlib.sha256(path.read_bytes()).digest()
+    _FILES[path] = (stamp, digest)
+    return digest
+
+
+def _path(root: Path, key: str | None = None) -> Path | None:
+    """The shipped file of ``root``'s key (``key``, :func:`entry`'s when the caller has it, else worked out now), or
+    None (no such file, or this isn't the wheel's or the frozen app's own)."""
+    if not SHIPPED.is_dir():
+        return None
+    path = SHIPPED / f"{key or entry(root).name}.pickle"
+    return path if path.is_file() and (FROZEN or _installed(path)) else None
+
+
+def _table(skips: object, path: Path) -> dict:
+    """The skip table read from the front of ``path``, or :class:`RuntimeError` naming a file of another layout."""
+    if not isinstance(skips, dict):
+        raise RuntimeError(f"{path.name}: not a shipped database of this AzurKit's layout (its skip table, then its "
+                           "database)")
+    return skips
+
+
+class _Counted(io.RawIOBase):
+    """``raw`` read on, each twentieth of its ``size`` read a core.progress
+    note ("reading its logic, k of 20"), so the logic's read is counted by
+    the bytes it has taken (Step 4.4bd)."""
+
+    def __init__(self, raw: io.RawIOBase, size: int):
+        self.raw, self.size, self.done, self.told = raw, max(size, 1), 0, 0
+
+    def readable(self) -> bool:
+        return True
+
+    def readinto(self, buffer) -> int:
+        got = self.raw.readinto(buffer)
+        self.done += got
+        if (k := min(self.done * NOTES // self.size + 1, NOTES)) > self.told:
+            self.told = k
+            progress.note(f"reading its logic, {k} of {NOTES}")
+        return got
+
+
+def shipped(root: Path, key: str | None = None) -> tuple | None:
+    """(the checked database at ``root``, its Logic's tables, its memos'
+    types) as the wheel's or the frozen app's build made them for ``root``'s
+    key (``key``, :func:`entry`'s, when the caller has it), its ``root``
+    put back, or None (as :func:`_path`). It is read as a stream, counted
+    (:class:`_Counted`). What it reads (about a million
+    objects, kept for the process) is frozen out of the cycle collector's
+    walks (``gc.freeze``): read at once, two full walks of it (0.4 s each,
+    the GIL held) came with the next call's allocations, which held the app's
+    server, a model's pictures asked meanwhile waiting a second (train B2)."""
+    if (path := _path(root, key)) is None:
+        return None
+    with open(path, "rb", buffering=0) as raw:
+        stream = io.BufferedReader(_Counted(raw, path.stat().st_size), 1 << 20)
+        _table(pickle.Unpickler(stream).load(), path)   # the skip table ahead of it (shipped_skips')
+        db, tables, memos = pickle.Unpickler(stream).load()
+    gc.freeze()
+    db.root = Path(root)
+    return db, tables, memos
+
+
+def shipped_skips(root: Path) -> dict | None:
+    """The shipped database's skip table (``{id: skip}``, the skips of
+    its ``skips``, each beside its level there), read from the front of its
+    file (about 14 KB, not the 87.6 MB of the database after it), or None
+    (as :func:`_path`): what a page's remembered randomizer is checked
+    against without reading the logic (Step 4.4bd)."""
+    if (path := _path(root)) is None:
+        return None
+    with path.open("rb") as f:
+        return _table(pickle.load(f), path)
+
+
+def _installed(path: Path) -> bool:
+    """Whether ``path`` is a file the installed wheel put there (its RECORD lists it)."""
+    try:
+        files = importlib.metadata.files("azurkit") or []
+    except importlib.metadata.PackageNotFoundError:
+        return False
+    rel = path.relative_to(path.parents[4]).as_posix()     # azurkit/tools/randomizer/shipped/<key>.pickle
+    return any(f.as_posix() == rel and Path(f.locate()).resolve() == path for f in files)
+
+
+def load[T](root: Path, build: Callable[[Path], T]) -> T:
+    """The database at ``root``: the shipped one for its key (:func:`shipped`), else read and checked now
+    (``build(root)``)."""
+    got = shipped(root)
+    return got[0] if got is not None else build(root)
+
+
+def shipped_logic(root: Path, logic_type: type, key: str | None = None) -> object | None:
+    """A ``logic_type`` (the planner's Logic) of :func:`shipped`'s database
+    (for ``key``, the loader's, so it is worked out once) with the tables
+    its build made and its memos empty, or None: the loader's
+    ``kept_logic`` builds one in about 1.4 s otherwise."""
+    if (got := shipped(root, key)) is None:
+        return None
+    db, tables, memos = got
+    logic = logic_type.__new__(logic_type)
+    vars(logic).update(tables, db=db, **{name: kind() for name, kind in memos.items()})
+    return logic
+
+
+def ship(out: Path, planner: Path | None = PLANNER) -> Path:
+    """Check the shipped database and write ``out/<key>.pickle`` (the key
+    :func:`entry` gives under ``planner``): its skip table
+    (:func:`shipped_skips`), then the database with its ``root``
+    dropped, so no path of the checkout that built it is in it, the tables
+    its Logic built and its memos' types. Only under ``PYTHONHASHSEED=0``
+    (never ``python -I``, which ignores it), so its sets pickle in one order
+    and a build gives the same bytes every time."""
+    if sys.flags.hash_randomization:
+        raise RuntimeError("the shipped database is written under PYTHONHASHSEED=0 (not python -I, which ignores it)")
+    from azurkit.tools.randomizer.planner import loader
+    from azurkit.tools.randomizer.planner.solver import Logic
+
+    report = loader.check_database(loader.DATA_DIR)
+    if report.issues:
+        raise loader.DatabaseError(loader.DATA_DIR, report.issues)
+    logic = Logic(report.database)
+    tables = {k: v for k, v in vars(logic).items() if k not in loader._MEMOS}
+    memos = {k: type(v) for k, v in vars(logic).items() if k in loader._MEMOS and k != "db"}
+    path = Path(out) / f"{entry(loader.DATA_DIR, planner).name}.pickle"
+    skips = {sid: s for sid, (_, s) in report.database.skips.items()}
+    path.write_bytes(pickle.dumps(skips, pickle.HIGHEST_PROTOCOL)
+                     + pickle.dumps((dataclasses.replace(report.database, root=None), tables, memos),
+                                    pickle.HIGHEST_PROTOCOL))
+    return path

azurkit/tools/randomizer/draft/__init__.py

@@ -0,0 +1,11 @@
+"""Randomizer authoring drafts: tools that derive logic data from the game.
+
+Authoring only (REORG_PLAN Phase R1, §12.1's layout): the planner and the
+writer never import this package.  :mod:`.envelope` holds the movement
+tiers as margins over the physics envelope (``tiers.toml``,
+:mod:`azurkit.tools.randomizer.physics`);
+:mod:`.reach` is the reach model (:mod:`.geometry`, :mod:`.floors`,
+:mod:`.flights`, :mod:`.wiring`, :mod:`.moves`, :mod:`.gates`,
+:mod:`.coverage`), which needs numpy (a runtime dependency), and
+:mod:`.export` writes its derived data (``azurik-mod rando derive``).
+"""