-
Generate traces into a scratch dir; every generator is seeded and deterministic.
-
The simulator drives the real library:
./gradlew simulator:run -q -Dcaffeine.simulator.maximum-size=<N> -Dcaffeine.simulator.files.paths.0=<fmt>:<path> -Dcaffeine.simulator.policies.0=product.Caffeine -Dcaffeine.simulator.policies.1=linked.Lru -Dcaffeine.simulator.admission.0=Always -Dcaffeine.simulator.report.format=csv.
Always pass admission.0=Always — the default admission list includes Clairvoyant, which
materializes the whole trace.
-
probe.py <trace> --size N is the per-cell verdict instrument: fresh LRU / Belady /
best-static-window anchors, the real cache's hit rate, and a TRAP? flag when the gap to the
ceiling is under −3pp. Run it from the repo root (or set CAF_TREE).
-
The reactive arm is a third anchor, not just an ablation. LRU says "better than doing
nothing"; the static-window ceiling says "how much is on the table"; the reactive arm says
"is the density machine earning its complexity on this row" — which is the only one of the
three that can retire code. These families were constructed to attack the density signal, so
most of them are not traps for the hit-rate law at all and "far above LRU" is a bar that hides
that. Measured 2026-08-04: on the deterministic families the reactive arm is level or ahead
(whisper 66.04 vs 66.78, mixture d025@32k 56.46 vs 58.48, mixture d050 long 58.44 vs 58.18),
and where the machine is clearly better the gain is often a spread rather than a level —
straywall2 reactive 48.12 ±19.84 against 55.07±0.03, demoflood 61.83 ±9.87 against
68.56±0.05. A single draw on those two reads 54.71 / 68.40, i.e. near-parity, and is wrong;
never quote a reactive comparison from one run.
Like LRU and the ceiling, the value is a property of the trace instance rather than of the
change under test, so it is measured once and recorded in the table's reactive column — a
routine change-verification run does not need to re-measure it. Re-measure when the instance is
regenerated by a new generator revision, or when a change touches shared climber state
(Step, Sample, the sample period, the resize path) rather than the density tier alone.
Refresh it with gate.py <traces> hybrid,reactive out.csv, which pairs the arms inside each
run; it needs the harness worktree, since reactive is a harness knob.
-
The static-window anchor is weighted-capable (2026-08-02; before that date weighted runs
silently dropped it — "no curve" in under a second): sketch.WindowTinyLfu declares WEIGHTED
and budgets its regions by entry weight, mirroring BoundedLocalCache's candidate/victim
eviction loop; on unit-weight traces it is bit-for-bit the classic single-step form (verified
on the bundled lirs cells). Weighted terrain/ceiling scans sweep percent-main exactly like
unweighted ones — but read the right metric: the panel reports the weighted (byte) hit
rate for weighted cells, while the climber's own goal metric is the per-request object rate
(its sample counters are unweighted), so judge climber terrain on the Hit Rate column.
A weighted ceiling taken before 2026-08-07 is void. The policy's admission filter was
sized once, when the cache first filled, and never re-sized; the cache retracks it on every
addition. The sketch's reset period scales with its capacity, so a frozen one ages at
near-zero period and flatters small windows, where nearly every admission is filtered.
On metaCDN_rprn@4G that put the reported static-window optimum at a 1% window when it is at
80%. Nothing recorded was affected (no weighted ceiling had been taken); the filter now
retracks per addition and unweighted output is unchanged bit-for-bit.
-
run.py <trace> --size N [--anchors] [--runs N] [--variants ...] [--dump PREFIX] runs one
cell (LRU + static-window anchors, N repeats, mean ± spread), and gate.py <traces-dir> [variants] [out.csv] runs this table's whole battery at the table's per-cell N — the
runnable form of the gate; update the two together. gate.py rotates its arms inside each
run rather than running them in blocks, which keeps the separate processes temporally
adjacent. It does not make them share JVM state or admission draws (they ran in blocks until
2026-08-02, which made slow environmental drift harder to distinguish).
-
Characterizing a holdout: pass an EMPTY --variants. run.py --anchors and probe.py
both used to loop a variant list that was never allowed to be empty, so every anchor run also
fired one product.Caffeine pass. §6 selects a holdout by LRU-only characterization and a
cell is spent once the product has touched it, so the tool silently burned the cell it was
characterizing — measured 2026-08-02, cost arc/P1@65536. Both now accept --variants '' and
skip the product entirely; verify with the printed output (an anchors-only run prints the
LRU=… ceiling=… line and nothing else).
-
-Dcaffeine.climber.seed=<n> (harness) makes each arm deterministic. BoundedLocalCache.admit's
1-in-128 HashDoS draw is the simulator's only live nondeterminism (the policy runs
.executor(Runnable::run)), so seeding it makes an arm reproduce bit for bit and a lottery
basin can be compared seed by seed instead of by unseeded draw counting. Equal seeds initialize
equal streams, but different contest schedules can attach the kth draw to different requests.
This is paired-by-seed evidence, not request-indexed common-random-number pairing, unless both
the draw count and request-index digest match. Added 2026-08-03, where it
settled two contested rows immediately: a −5.77 on phases_d050 was pure basin draw (arms
bit-identical on all 8 seeds) while a −2.12 on crashnoise_a12 was real (−1.43 on 7 of 8).
Prefer it for any single-cell adjudication. It does NOT replace the unseeded N≥8 policy for
claims about the distribution of basins, and a seeded sweep is only as broad as its seed list —
use 8 seeds, not one.
-
harness.py wires in the adversarial-round instrumentation — harness.py apply <worktree>
(also verify and strip), distilled from rounds 2–4 so each round stops rebuilding it. NEVER
commit the result: it prints to stderr and carries variant knobs, and ErrorProne flags the
SystemOut by design. It adds -Dcaffeine.climber.debug=true (one mode-labeled stderr line per
density sample — the trajectory instrument that found every behavioral defect to date),
-Dcaffeine.climber.seed=<n> (a seeded admission tiebreak), -Dcaffeine.climber.auditbar=<f>
(the audit crash bar's fraction of the rate frozen at arm; 0 restores the pre-fix absolute
5pp), and -Dcaffeine.climber.variant= with ablation arms: noaudit (audit layer off),
reactive (hit-rate tier at every size), nocal (no cold-start calibration), hardreset /
starvwrite / prefix (restore the pre-round-3 clock reset, the pre-round-3 starvation
schedule write, or both), absprobe (the pre-adv3 absolute walk-interior bar for starvation
probes), precrash (the pre-crash-semantics machine: shared crash ledger, escalated crashes
double the audit clock, one-sample audit aborts), noretest (a veto's return never re-tests the claim that sent it, the pre-2026-08-19 arrival), flatroom (the pre-2026-08-03 room rule,
measuring the flat restart magnitude while the walk strode up to 4× it), and staleclaim (the
pre-2026-08-03 stand-down, which left the goal metric smoothing across a regime shift) — the A/B
arms for landed fixes without checking out history. One arm is a candidate rather than history:
parkbound (end an audit's park with its shield instead of holding to the next audit — battery
mean +0.08 and real-corpus neutral). It was recorded as the live lead on the R4-F1 give-back,
worth "+1.3..2.0 uniformly on all three shieldtrap seeds". That does not reproduce under
seeded paired runs and the lead is withdrawn (2026-08-04, N=8 admission seeds 1–8, arms
rotated inside each run): s7 78.06 → 76.92, s11 77.19 → 77.60, s13 77.44 → 77.83 — mean
−0.11, not +1.3..2.0, and it closes none of the 1.37pp the reactive arm leads this family by
(78.93). What it actually does is collapse the basin structure to a fixed ~77.6: on s11 its
spread is 0.13 against hybrid's 2.94, so it gains where hybrid draws low and gives back where
hybrid draws high. On s7 that trade is bad — two of eight seeds fall to 74.37/74.68 against
hybrid's 79.01/79.00, a −4.6 tail the unseeded mean hid. (the family's other
sentinel) is +0.49, which does not pay for it. Re-open only with a mechanism for the s7 tail.
The family (, , , , , ,
, ; one flag table in ) is the stand-down re-arm of §8
item 4's latency face, priced dead in every form 2026-08-22: a discarding stand-down restarts
the audit schedule, gated on held parks or not, with the stillness run restarted or kept. Kept
so the square can be re-priced after an alternation change; hill-climber.md §5 has the numbers.
-
It is snippets, not a diff, and that is load-bearing. It was experiment-harness.patch until
2026-08-04, when it broke three times in one day: a unified diff encodes the source it was cut
from, carrying javadoc as context, so an unrelated comment reword breaks it — and both failure
modes are silent. git apply is all-or-nothing per file, so one stale hunk refuses every
hunk for that file and yields a build with no instrumentation that still prints plausible numbers
(an ablation arm then measures the shipped machine). A fuzzy patch lands the rest and reverts
whatever the stale context encodes — twice reverting a landed fix inside densityClimb.
Both harnesses assert their edit tables are safe before touching a file: presence of the applied
form is the idempotency test, the verify test and the strip target, so two edits whose applied
forms are equal — or where one contains the other — make the second invisible. Apply skips it as
already wired, verify passes, and the instrumentation is silently partial while still printing
plausible numbers. That is not hypothetical: the admission harness hit it on its first run
(two edits inserting the same counter line at different anchors) and lost 276,764 of 558,186 hits.
harness.py anchors on code only, so doc edits cannot move it; a moved anchor names itself
and stops, applying is idempotent, and strip round-trips to pristine. If a variant arm reads
suspiciously like the baseline, run harness.py verify before believing it is a finding.
It earned this on its first use: verify reported 5 of 27 not wired in a study that had
applied the old patch with --fuzz, and two of the five were the admission-seeding pair — so
every "seeded, bit-reproducible" adjudication in that study would have been fiction. The
study reset both files, re-applied, and then proved seeding empirically (one cell, one seed,
run twice, bit-identical) rather than reasoning past the warning. Do that check whenever
verify is not clean.
Point run.py/gate.py at the worktree via CAF_TREE.
-
A probe you add yourself must print climb -prefixed lines, and must assert its own
denominator. run.py keeps only stderr lines starting with "climb ", so an ad-hoc
System.err.println("MYCOUNTER ...") is discarded before it reaches the --dump file and the
count reads zero — from a probe that compiled in and ran on every sample. Measured
2026-08-09, where it turned 3 phantom anchor plants into a "no measured exposure" conclusion
that was about to be written up. The line must also carry win= and mode=, since
summarize parses both out of every dumped line. The check that catches it is free: pair the
new counter against a quantity the harness already counts (drain evaluations must equal
mode=undo samples) and refuse the numerator until the denominator matches. Same family as the
verify incident above — a silent probe and a wired probe produce identical-looking output.
-
exposure.py (harness-dependent) answers "can this trace ever audit?": stillness fraction,
longest run vs the wait, audits/probes armed — the instrument behind the corda blind-hold
and w097 at-the-bar findings. blindlock.py (harness-dependent) answers the neighbouring
question, "how much exploration is the blind-corner branch refusing?" — it reads a --dump
trajectory and counts blind-corner samples (labelled hold/ARM*) whose stillness run has
already reached auditWait. It is what found the 2026-08-04 lockout: metronome refused 116 due
re-tests, its longest unbroken run being 65, and four other cells 29 apiece. Its columns
changed meaning when holdOrAudit shipped — a due clock now pre-empts the refractory hold, so
the count is starvation probes outranking an ordered audit and no longer includes holds; read
its docstring before comparing against a pre-2026-08-06 number.
-
census.py and corner.py (harness-dependent, 2026-08-15) read trajectory dumps. census.py run dumps one trajectory per (cell, seed) for gate.py's cells plus real.py's, and census.py parse emits a row per audit confirm: direction, base and confirmed window, whether the confirm
sample was blind or the grown region starved, the park's length and how many of its samples
starve, how it ended, and the hit rate over the park against the samples before the arm. It is
what showed a park on a starved position is 3 in 642 confirms, that 204 of 254 audits crashing
out of a park release it, that 34 of 92 veto returns arrive with the rate up and release the hold,
and how often the 5pp shift trigger discards the anchor per cell. corner.py reports the corner
starvation probes over the same dumps (rung at arm, ending, depth, the ending sample's cost):
302 upper-corner probes ending 163 crash / 115 fail / 11 confirm against the floor's 1,098 ending
785 confirm. Re-run both before proposing a rule about parks, corners or the stand-down.
-
The tier gate moves the law and the cadence together, and the 2×2 separates them. Above
4096 the climber switches steering law and sample period (10× maximum → 4×), so neither can be
attributed alone. harness.py carries all four corners: reactive / density force a tier at
every size, and react4x / dens10x are the cross arms (hit-rate law on the short cadence, and
density law on the long one). The 2026-08-04 D2 study needed this — the dominant term flips with
terrain, so a single isDense switch attributes a tier cliff to the wrong half.
-
byworkload.py counts workloads, not cells; pair.py compares seeds, not spreads. Both
encode a mistake that is easy to make with these corpora. Epoch slices of one trace are not
independent evidence — six agreeing epochs are replication within one workload, and pooling them
inflates the base of a reachability claim (D2's "8 movers" were 3 workloads until it was widened
to 9). And a seeded sweep is not a repeated measurement of one basin: each seed defines an
independently reproducible run, so arms are compared seed by seed and an arm's own column
spread says nothing about whether a difference is real (phases_d050 spreads 12.9pp across
eight seeds with the code held fixed). This pairing controls seed identity only; it does not
align draws to requests without the parity proof above. sweep.py is the canonical seeded
long-format producer: it interleaves arms within each seed and aborts a cell rather than writing
a partial arm vector. Its output carries parallel seeds and runs fields; pair.py rejects
legacy positional rows, duplicate seeds, incomplete arms, and unequal seed sets rather than
truncating or shifting the comparison.
byworkload.py enforces the same identity contract when comparing the 4096/4097 tier pair.
-
lcs2lirs.py projects a libCacheSim oracleGeneral trace to unit-weight LIRS epochs. The tier
boundary is 4096 in the maximum's native units, so on a byte-weighted trace it means 4096
bytes; projecting to unit weight is what makes such a trace usable at the density tier at all.
-
run.py --seeds 1,2,..,8 runs one pass per admission seed instead of --runs repeats, so
each arm is reproducible and a contested cell is compared by seed rather than by unseeded draw
counting. Variants run adjacently within each seed, and the output prints the exact
seeds=s1:hit-rate,... vector for every arm. Before 2026-08-04 no
committed tool accepted -Dcaffeine.climber.seed, and three workspaces had each hand-rolled
their own; use this. It is what showed a −6.32 slowswap_step, a −2.60 phases_d050 and a
−0.59 bandtrap2 were all basin draws (bit-identical on all eight seeds).
-
real.py sweeps the real corpus (ten cloud-physics cells plus three ARC) and floors.py the
thin-signal floor cells (w50@123038, S1/S2/S3, DS1@1051635) — the runnable form of the gate's
thin-signal floors row, and the cost side of anything that touches the refractory or the
probe machine. Both skip the frozen merge-gate holdout and arc/P3. The ARC cells declare
the arc reader: they were lirs until 2026-08-04, which yields nothing silently, so every
ARC row written before then was blank and the "real corpus 10/10 ties" bar on record is the ten
cloud-physics cells alone.
-
marginal.py answers "where does a steering signal rest, versus
where does the hit rate peak?" — signal anatomy with no controller involved. Wire a worktree
with harness.py apply (NEVER commit it: it adds region-attributed hit counters and an
LRU-tail band to the static-window anchor, maintained by an O(1) midpoint marker), point
CAF_TREE at it, and sweep. The tail band catches only a small share of window hits
(~0.4% on attack_whisper@8192), so on a small or short cell it rounds to zero and the
marginal error goes epsilon-driven: cs@512 reads ht=0/hq=0 at every window while
attack_whisper@8192 reads ht=2009/hq=2.18M. Confirm ht/hq are non-zero on the cell
you are measuring before trusting a marginal number from it. It reports, per cell, the
peak window and the zero-crossing of
both the average-value error ln((H_w/C_w)/(H_m/C_m)) — what the density arm steers on — and
the marginal-value error ln((H_tail/C_tail)/(H_prob/C_prob)). This is the instrument that
measured the density arm's give-back to its cause in 2026-08-02 (average rest point above the
peak on 7/7 crossing cells, losing 0.71pp mean vs the marginal form's 0.09pp); TAIL=<delta>
sweeps the band fraction to check an answer is not an artifact of it. Its window list stops at
0.80 because that is the window's reachable ceiling (increaseWindow donates only the protected
allocation), which is the right range for a rest-point question; set WINDOWS=0.9,0.95,... when
the question is instead where the hit rate peaks, since six of twenty-one cells measured
2026-08-08 peak above the ceiling and a sweep stopping at 0.80 reports the wrong peak for them.
-
admission_harness.py + admission.py answer "how often is an admission right, and how much
does it earn when it is?" — the measure taken from Merlin's Figure 20, which prices admission
decisions directly instead of inferring their quality from the end hit rate. Same worktree
convention (admission_harness.py apply <worktree>, never commit), then
CAF_TREE=<wt> admission.py <out.csv> <manifest> sweeps static windows and reports, per region,
precision (share of admissions ever hit) and yield (mean hits when hit). It exists because
density = precision x yield x (entries per capacity) and the steering signal sees only the
product: at P3@152508's rest point the two regions look comparable by density (15.4 vs 12.3)
while the window is right 1.1% of the time for 1.03 hits against main's 59.2% for 10.78 —
a 1% window's turnover carries a region almost nothing is hit in. Every row is
conservation-checked (window hits + main hits must equal the reported hit count) and a row that
fails is refused, which is not decoration: the harness's first version dropped every
protected-region hit and still printed plausible precisions.
Diagnostic only — do not re-derive equalization. Precision- and yield-equalization were both
checked against the peak on four cells: precision ratio spans 0.01–2.55 and yield ratio
0.03–0.26, against density's 0.58–0.95.
-
-Dcaffeine.climber.startwin=<frac> (harness) plants the initial window, and it is the only
instrument here that asks whether the climber DESCENDS. Every other row starts the cache where
the product starts it, at 1%. On a frequency-favorable trace that is already the answer, so the
row passes without the machine moving, and a broken descent would read clean on the whole real
corpus. startwin.py sweeps the plant over 5/10/20/40/80% and reports, per cell, the frozen
static window at the plant (the do-nothing floor), the same cell from the shipped start (the
recovery target) and recov, the fraction of the gap between them the run wins back. Four things
about it are load-bearing:
- The plant holds probation at its shipped 19.8% instead of re-splitting main 80/20, which is
the geometry
increaseWindow itself produces (it conserves window and protected). That is what
puts an 80% plant at the window's reachable ceiling rather than above it. --split resize
gives the other geometry, which a setMaximum resize leaves but the climber cannot reach.
- It also means
run.py's static sweep is not a like-for-like frozen reference at a large
plant: it varies percent-main alone, so its 80% point has 16% protected where the plant has
0.2%. frozen_matched.py re-measures the frozen point with the plant's own split.
- Recovery is a function of density samples, not of cache size. A sample is
4 × maximum
requests and a full descent from 80% needs 15–20 of them, so the plant's cost in hit rate
scales with the maximum while the descent does not. Read the sample count before reading a
deficit: on ds1_4M an 80% plant ends at an 80.1% window because two samples is two
commands, which prices arithmetic and not the machine.
ds1_256k is not a member of this family, and neither is any other DS1 cell below ~1M:
DS1's static optimum moves with size, a 30% window at 262144 against 1–2% at 1M, so a plant
there is not a descent test at all.
Four instruments come with it. descent.py reports the median falling step per sample and the
undone column; repeat.py replays a trace N times, which is what separates "too short for this
maximum" from "cannot descend"; screen.py picks further workbench cells from anchors alone, so
it spends nothing; and mechanism.py recomputes |error| × 0.03 × maximum per sample and prints
it beside the motion observed, which is how "the descent is gain-limited" was established rather
than assumed.
-
Noise: unseeded admission gives ±0.1–0.8pp run to run. Gate verdicts are coarse (an escape vs
a ~28pp pin), so 1–2 runs suffice; take N≥5 before claiming anything under 2.5pp. Keep
candidate-vs-reference arms in the same sweep (interleaved runs, append+resume CSVs) rather
than comparing across sweeps, and compare seeded arms seed by seed. Interleaving limits drift;
equal seeds are not request-indexed common random numbers without draw-count and digest parity.
