institution/TUNING.md

Institution — tuning reference

The suite's stochastic systems are paced by a handful of constants. This file records, for each, the design intent (what the rate should feel like in play), the target band, the measured value from the CBTUNE telemetry pass (Gangs _CompatTest.RunTuning, full-stack harness), and the verdict. Re-run the harness and read the CBTUNE lines to refresh the measured column.

Measurement method: the crime and reform rows are sampled from the real code (the crime row runs the actual Propensity.Would roll over 200 in-game days of windows per pawn tier; the reform row runs one real CorrectionsUtility.RunReformSession). The remaining rows are deterministic — fixed by a formula or a tick cadence — so they are recorded, not sampled.

Boot of record: full-stack harness rimworld-wardcompat.N5Xo2C — 45 CBTEST True / 0 False, 0 NotImplementedException, clean watchdog shutdown. Every measured rate fell inside its pre-registered band; no constant was changed. Two rows carry a WATCH note for real playtest.

Crime — free colonists offending

MapComponent_Crime: every 2500 ticks (24 windows/day) each eligible colonist rolls Propensity.Would(p, 0.02 × CrimeCover, …). CrimeCover = Lerp(0.1, 0.5, (freeColonists−3)/10) — crime rises with colony size (a crowd is cover). Would folds in Nature (traits) × Nurture (mood, held, reform, deterrence). Design intent: ordinary colonists almost never offend; a dangerous pawn offends occasionally; a dangerous and mistreated pawn is a near-daily problem you must house, treat, or police.

Tier	cover 0.1 (small colony)	cover 0.5 (big colony)	target band (big colony)	verdict
ordinary (no dark traits)	0.010 /day	0.030 /day	< 0.05 /day	✓ in band
dangerous (psychopath, content)	0.030 /day	0.185 /day	0.10 – 0.40 /day	✓ in band
powderkeg (dangerous + miserable + held)	0.205 /day	1.115 /day	0.50 – 1.50 /day	✓ in band

Nature/Nurture measured: ordinary & dangerous nurture 0.83 (decent mood, a well-policed colony's deterrence pulls below 1); powderkeg nurture 2.89 (floored mood ×2.5, held+unhappy ×1.4, deterrence back). The curve is well-shaped across the whole propensity spectrum — no change.

Reform — turning a prisoner around

CorrectionsUtility.RunReformSession: AdvanceRecovery(0.34 × quality[0.5–1.5] × skillFactor[0.5–1.0]) on Core's treatment track, plus record.reform += 0.10. Design intent: rehabilitation is a multi-day investment that needs sustained warden attention and a decent cell — not instant, not a grind.

Scenario	measured gain/session	sessions to full	days @ 3 sessions/day	target	verdict
bare cell, social-10 warden (slow end)	0.165	6.1	2.0 days	2 – 5 days	✓ in band
good cell, skilled warden (fast end, derived)	~0.51	~2	~0.7 day	≥ ~0.5 day	✓ but quick — WATCH

WATCH: the luxury fast-end (~0.7 day) is in band but brushes the "multi-day" intent. Left as-is; if playtest shows corrections feels like catch-and-release, halve the 0.34 base in AdvanceRecovery.

Smuggling supply route

MapComponent_Contraband.TickSmuggle: every 250 ticks (240/day), a held pawn with a non-hostile visitor or a corrupt warden (Corruption ≥ 0.25) within 3 cells has a 0.05 chance to receive a concealed OnBody item via Corruption.Smuggle. Design intent: the outside world resupplies the cell occasionally — a payoff for visits and a cost of a bent warden — countered by warden searches.

Metric	value	note
route yields an OnBody item	True (a MeleeWeapon_Gladius)	route works; the pool has hideable items
per-check chance	0.05
max items/day if a smuggler is adjacent all day	12.0	upper bound only; real adjacency is brief (wardens move)
WATCH	a full sword passed OnBodyMassLimit = 2.0	a smuggled blade is sharper than a shiv; no flood observed, so 0.05 left as-is

Realistic estimate (unmeasured — needs a longer sim than the 12000-tick watchdog allows): a bent warden is within 3 cells of a prisoner only during warden duties, so ~0.3–0.5 items/day, largely cancelled by warden searches (find 0.35–0.95/search). If a longer playtest shows contraband accumulating faster than searches clear it, drop SmuggleChancePerCheck to 0.02–0.03; the trigger has not fired yet.

Deterministic rates (formula / cadence — recorded, not sampled)

System	rate	design intent	verdict
Warden search find-chance	0.35 (social-0) → 0.59 (social-8) → 0.83 (social-16), cap 0.95	a rookie is leaky, a competent warden finds most	sane
Tunnel escape	3 – 15 days to breach (normalised to wall distance)	a multi-day project the player can interrupt by finding the shaft	sane
Riot	≤ 1/day (60000-tick cooldown), only when order < 0.25	a rare crisis when order collapses, not routine	sane
Gang recruitment	12 checks/day (5000-tick), only disposition ≥ 0.90	only the strongly-inclined join, and gradually	sane
Visitation	mean ~9 days between visits per eligible prisoner	occasional flavour + resupply, roughly weekly	sane

Notes

• The ThinkNode_PrioritySorter GetPriority: NotImplementedException seen at the tail of some harness logs is a vanilla JobGiver_GetRest.GetPriority firing during the watchdog's forced shutdown (tick 12000), not a suite fault — it never appears during the 0–11999 gameplay ticks, and the boot of record above logged zero of them. Nondeterministic teardown noise, not a tuning or correctness issue.
• What a headless harness cannot measure: emergent adjacency/occupancy (how often a smuggler is actually next to a prisoner), long-horizon reform decay, and player-driven pacing. Those are the real remaining playtest questions; the two WATCH rows above are where to look first.