1 files changed, 110 insertions, 0 deletions
diff --git a/research/experiments/001-checkpoint-granularity/README.md b/research/experiments/001-checkpoint-granularity/README.md
new file mode 100644
index 0000000..4c04950
--- /dev/null
+++ b/research/experiments/001-checkpoint-granularity/README.md
@@ -0,0 +1,110 @@
+# Experiment 001: checkpoint granularity
+
+This is a native measurement apparatus for one known space/time tradeoff. It is
+not a new algorithm, a general dependency-graph runtime, or the product's language
+choice. The apparatus uses C17 and Python's standard library so it can be run
+with the tools present on the initial Linux host and with a C compiler on macOS.
+
+## Question and pre-measurement expectations
+
+How much does storing intermediate results at different intervals save, once the
+editable program and scheduling state are included? How much extra work does it
+cause when a rule changes?
+
+Expected, not measured at the time of writing this section:
+
+- Uniformly spaced checkpoints shrink the result cache at the cost of starting
+  recomputation before the changed instruction.
+- Root input changes offer no prefix to reuse. Fine checkpoints may only add
+  cache writes and comparisons in this workload.
+- Edits near the end favor fine checkpoints. This deliberately favorable case
+  must not stand in for all edits.
+- The editable model stays resident, so shrinking the cache 16-fold will not
+  shrink total core storage 16-fold.
+
+## Semantics and comparison
+
+The model consists of independent, statically connected chains. Each instruction
+is an 8-byte record with a scalar operator and parameter. Values are uint64_t;
+overflow wraps. Supported operators are add, XOR, multiply, and rotate/XOR.
+Only the final result of each chain is observed.
+
+One update applies a batch of changes, then computes all affected observed
+outputs. Changes alter roots, operators, and parameters, not graph topology.
+There is no renderer, effectful I/O, concurrent execution, or state migration.
+
+- Block 1 stores every intermediate result (fine incremental baseline).
+- Blocks 4, 16, and 64 store results at block ends.
+- A block equal to chain length recomputes the whole affected chain, retaining
+  only its final output (full recomputation baseline).
+
+All variants share program representation, input handling and per-chain dirty
+ranges. Unaffected chains are skipped by every variant. Fine and full variants
+use dedicated loops. Fine/block variants stop at an unchanged cached boundary
+only after passing the last changed instruction in the batch.
+
+The chain structure makes dependency information implicit. No general graph
+edge storage or graph partitioning is needed. This is an optimistic case for
+compact checkpoints; it cannot establish results for arbitrary graphs.
+
+For G chains of length L and checkpoint spacing B, the requested persistent
+storage in this implementation is:
+
+```text
+sizeof(Engine) + 8*G*L + 16*G + 8*G*ceil(L/B)
+                 model   inputs+   cached values,
+                         dirty    including outputs
+```
+
+This includes all live core arrays and the engine descriptor, but not allocator
+bookkeeping, stack, executable code, trace storage or OS pages. Trace size is
+recorded separately. It is not RSS, physical footprint, or total application RAM.
+There are no allocations in the timed update path.
+
+## Workloads
+
+The fixed initial matrix uses 16 chains, lengths 256 and 1024, and 256 updates per
+trace. Workload seed: 20260922.
+
+- `roots`: every chain's input changes on every update.
+- `uniform`: one uniformly selected instruction changes per update.
+- `tail`: one instruction in the last eight positions changes per update.
+- `dense`: eight instruction edits per chain per update, with replacement.
+
+Changes are XOR deltas so repeated traces continue changing the model. Two
+warm-up passes precede timing. Even measured replay counts leave identical final
+models across strategies; the runner checks their output checksums. Differential
+tests additionally compare every output after every update against independent
+from-scratch evaluation across multiple seeds, odd sizes and edge cases.
+
+## Reproduce
+
+From this directory, with Python 3 and a C compiler with ASan/UBSan support:
+
+```sh
+python3 run.py --check-only
+python3 run.py --output results/local-run
+```
+
+The runner refuses to overwrite an existing result directory. `CC` can select a
+compiler, such as `CC=clang`. It builds into a temporary directory. On Linux it
+pins itself and child processes to one available CPU and records that choice.
+
+Default measurements use seven trials with randomized strategy order within
+each trial. Pilot timings choose an even replay count per case, targeting 20 ms
+per measurement. All raw samples, memory counts, instruction counts, compiler
+flags, source hashes and host metadata are retained. Timing excludes program
+creation, trace creation, warm-up, and output verification. It includes change
+application, scheduling and recomputation.
+
+`median_ns_per_tick` is the median of batch-average processing times. It is not a
+P50/P99 input-to-display latency measurement. A shared host without controlled
+power or temperature permits preliminary comparisons, not hardware guarantees.
+
+The reported storage reduction is largely predicted by the formula. The useful
+observations are the whole-core reduction, processing cost and losing workloads.
+This experiment cannot establish automatic policy quality, novel research,
+editor usability, M3 performance, or universal memory savings.
+
+The first run and its interpretation are available in the
+[Korean research report](../../../docs/research/002-checkpoint-results.md).