Cache format

A cache is a directory with a manifest, a state index, and one NumPy array per chain offset.

manifest.json
index.parquet
values/empty.npy
values/offset_00.npy
...
values/offset_49.npy

manifest.json is validated by the packaged JSON Schema. It records the source package, package fingerprint, libcbm version, CBM defaults hash, years, dtype, account names, offsets, state count, and file list. It also records the declared chain_family: the treatment, event count, allowed offsets, and whether untreated rows are stored. Legacy manifests without a family still load; the client treats them as legacy and does not infer a family.

index.parquet maps a row id to track_id, track_name, and age. Every value array has shape (states, years + 1, accounts). The empty chain is stored separately.

The cache is exact for the manifest identity. Any mismatch must fall back to WS4’s exact carbon ledger or a fresh libcbm run.

State, not blocks

CBM is aspatial. A cache row is a per-hectare stand state. Block effects are area-weighted sums of state rows applied by the consumer. The cache does not contain block topology, adjacency, or planning targets.