Client-agnostic source of truth for everything botable in OSRS: activities, ordering, actions, requirements. AI agents translate entries into client APIs.
671d025d9f
A successful sell followed sell-filled-awaiting-collect -> closed, and 'closed' had no outgoing transition while the scheduler left closed slots untouched — every GE slot could perform ONE flip and then became permanently unusable (no rotations, breaks, or longer sessions). Fix (finding-by-finding, governor comment 10471): 1. 'closed' is no longer a sink. The completed cycle's ledger is reconciled and ARCHIVED at close, and the physical slot is released to free via the explicit archival transition closed -> free (flip-candidates.yaml slot_transitions, whens, scheduler_iteration, a9 archive step, summary, risk, sources). The scheduler pass dispatches the release (SLOT_DISPATCH['closed'] = 'release'), so a closed slot is only ever transient. 2. A deliberately closed cancelled sell releases identically: sell-cancelled-awaiting-collect -> closed -> free (whens updated). 3. Committed two-rotation regression (validator, wired into ge_lifecycle_errors for every flipping entry): slot_reuse_violations walks one physical slot through free -> buy-open -> buy-filled-awaiting-collect -> ready-to-sell -> sell-open -> sell-filled-awaiting-collect -> closed -> free -> buy-open (second buy in the SAME slot), validating every ledger frame against both conservation gates; archived_ledger_preserved_after_second_buy proves the rotation-1 archived ledger survives rotation 2 bit-for-bit (no loss, duplication, or mutation). Negative fixtures prove a closed sink or a closed that does not release to free FAILS. 4. ge_lifecycle_errors now requires closed == ['free'] exactly and rejects any machine where a state has no transitions. 5. Worked example: t5/t8 walk the release, t8b runs rotation 2 in the same physical slots. All prior fixtures preserved (tax x4, async-slot scheduler, collection-box, limit-window, side-aware conservation x25) — now 35 selftest checks. Evidence: python3 tools/validate.py -> 2 entries, 0 errors, 1 pre-existing warning; --selftest -> 35 PASS, 0 errors; git diff --check clean. |
||
|---|---|---|
| codex/economy | ||
| docs | ||
| schemas | ||
| tools | ||
| README.md | ||
OSRS Codex
One source of truth for everything that can be botted in OSRS.
Every bot-able activity — alching, mining, slayer, bosses, trading — is described here once, in a strict client-agnostic YAML structure: requirements, execution order (state machine), the exact action sequence, economics, best-in-class setup, and anti-ban notes.
AI agents building scripts do not re-learn the game. They read a codex entry and translate it into the target client API (DreamBot / Microbot / Storm / RuneLite plugins / …). The game knowledge lives in this repo; the client glue lives in whatever script is being written.
client-agnostic client-specific (NOT in this repo)
+----------------+ +-------------------+
| codex entry | translate | DreamBot Java |
| (YAML, strict) | ---------> | Microbot JS |
| actions: verbs | | RuneLite plugin |
+----------------+ +-------------------+
Layout
codex/<domain>/<entry-id>.yaml # one entry per activity
economy/ trading, alching, flipping
training/ skill grinds (magic, mining, woodcutting, ...)
combat/ bosses
combat-slayers/
quests/ quest entries (referenced by requires_quest)
transport/ teleport/teleport-reach recipes (shared by many entries)
meta/ account rotation, world hopping, break scheduling
docs/schema.md # the entry contract (read this first)
docs/action-grammar.md # the universal verb vocabulary
docs/data-sources.md # where every fact must come from + how to verify
schemas/entry.schema.json
tools/validate.py # the gate: python3 tools/validate.py (must exit 0)
The rules (short version)
- One entry = one activity. State machine + action list, both mandatory.
- Every fact carries a source. Wiki-cited or
researched <date>(a TODO: follow-up issue must land the proper citation). Live prices are re-verified againstprices.runescape.wikion every bump. - Best-in-class setup is mandatory (
best_practice). Top-operator execution: staff of fire for alchemy, noted items, shortest routes. Translators adopt it by default; deviating requiresimprovised: true. - Anti-ban is first-class. Every action declares delay bounds and
movement style; entries carry
risk.ban_level+ notes. - The gate must pass before a PR merges:
python3 tools/validate.py. - Never mix in client knowledge. No DreamBot/Microbot/Storm API names in entries. Translations live in script repos, referencing the entry id.
Entry lifecycle
draft → verified (all facts sourced, prices re-checked, validator
clean) → stale (facts > 30d old or prices moved materially). Stale
entries are skipped by translators unless explicitly allowed.
Contributing
This repo is issue-driven: all content is specified in Gitea issues
(acceptance criteria + source URLs + expected output path), implemented in
branches, and gated by tools/validate.py in CI. No direct pushes.