pbwraith/osrs-codex

Fork 0

Client-agnostic source of truth for everything botable in OSRS: activities, ordering, actions, requirements. AI agents translate entries into client APIs.

Go to file

Claude 052c6984ac codex: low-alch-members — loss-reserve stop direction + fill-price scenario GP bounds (bounce-fix attempt 5) Owner guidance 2026-08-29 for governor review 10361 (PR #8), finding by finding: 1. Loss-reserve stop direction — the stop read 'session net loss (total assets - initial capital) > 162,990'; a loss makes that LHS negative so it could never exceed the positive reserve (the stop could never fire). Now expressed everywhere as 'initial capital - total assets > 162,990' (stop_conditions, worked-example step 6, recovery block, version pin): a loss makes the difference positive, the strict-greater comparison fires on losses and never on profits, and exactly-at-boundary does not fire. tools/validate.py gains alch_accounting_regression(): comparator boundary fixtures (below 162,989 / at 162,990 / above 162,991 / profit side +50,000 / breakeven) plus entry-text pins rejecting the reversed form anywhere in the file. 2. Fill-price scenarios for realized GP bounds — previously gp_per_hour_low /high derived only from the live-low -3.00/cast margin while the buy policy permits live low + 5% (candidate 423.15 + nature 147 = 570.15 vs 540 lowalch = -30.15/cast). The economy block now declares FILL-PRICE SCENARIOS A (live-low 543 -> -3.00/cast) and B (max allowed +5% 570.15 -> -30.15/cast) as the single ledger behind capital, batch economics AND the GP bounds: gp_per_hour_low -29,463 (scenario B x session-fast 977.2), gp_per_hour_high -1,758 (scenario A x session-slow 585.9), midpoints -22,365 / -2,225 pinned; validator enforces the exact bound values and the -30.15/570.15/423.15 scenario pins. Preserved: complete GE acquisition/restock flow, one-cast iteration, monotonic break/restock counters, total-assets accounting (floor 575,150), fail-closed staff path, and the earlier fixed pacing/equip findings. version 5 -> 6, updated 2026-08-29. Gate: python3 tools/validate.py -> 2 entries, 0 errors, 1 pre-existing F2P WARN (low-alch-f2p researched, untouched); git diff --check clean; regression negative-tested (old gp pins, reversed form, missing scenario pins all rejected).		2026-08-29 03:00:56 -05:00
codex/economy	codex: low-alch-members — loss-reserve stop direction + fill-price scenario GP bounds (bounce-fix attempt 5)	2026-08-29 03:00:56 -05:00
docs	Codex skeleton: schema contract, action grammar, data-sources rules, JSON schema, validator, golden example (low-alch-f2p, wiki+price verified), README	2026-08-27 02:59:55 -05:00
schemas	Codex skeleton: schema contract, action grammar, data-sources rules, JSON schema, validator, golden example (low-alch-f2p, wiki+price verified), README	2026-08-27 02:59:55 -05:00
tools	codex: low-alch-members — loss-reserve stop direction + fill-price scenario GP bounds (bounce-fix attempt 5)	2026-08-29 03:00:56 -05:00
README.md	Codex skeleton: schema contract, action grammar, data-sources rules, JSON schema, validator, golden example (low-alch-f2p, wiki+price verified), README	2026-08-27 02:59:55 -05:00

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 against prices.runescape.wiki on 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 requires improvised: 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.