Runtime core¶

The runtime layer is the execution substrate for coalition evaluations:

Run archive — SQLite index plus the generated text of every coalition.
Dedup registry — SHA-256 coalition keys that collapse repeated work.
Hot store — in-memory LRU of recent generations.
Inference scheduler — async execution with bounded max_inflight.

Run archive¶

RunArchive persists CoalitionRecord rows with the packed mask, timing and cache-hit flag in archive.sqlite; the generated text sits next to it, so history_lazy() streams rows without loading every generation into memory. The directory also holds manifest.json (RunManifest) and the base generation. Archives store generations, not payoffs: reanalyze recomputes payoffs and attributions from them. open() creates an archive and refuses an existing one unless on_exists is "overwrite"; load() opens one for reading and checks its schema version.

Coalition deduplication¶

build_coalition_key() hashes snapshot id, player order, packed mask bytes, absence policy, model id, and generation settings. CoalitionDedupRegistry tracks which keys already required backend execution. dedup_enabled() maps ExplainConfig dedup mode to deterministic generation (auto follows temperature == 0).

Hot store sizing¶

HotResultStore is an LRU of coalition key to generated text. Inside ExplainRunner it is the scoring buffer of the run, sized to \(2^n\) entries so that no output of the run is evicted before it is scored; the grand coalition is seeded from the base generation. Memory grows with the number of coalitions actually evaluated, not with \(2^n\).

Scheduling¶

InferenceScheduler checks the hot store, then the dedup registry, then acquires a concurrency semaphore before calling the backend. SchedulerMetrics reports requested, executed, deduplicated, cache_hits and kv_cache_hits.

Failure semantics¶

The first exception raised by a backend call ends the run: the scheduler cancels every pending job, collects the exceptions of jobs that failed at the same time (so none is reported as “never retrieved”), and re-raises the first one. No metrics and no partial attributions are returned, and an archive written so far keeps the outputs that completed.

Optional progress¶

Pass a CoalitionProgress implementation to InferenceScheduler or ExplainRunner to receive sync on_coalitions_planned / on_coalition_finished callbacks. When omitted, NullCoalitionProgress keeps the hot path near zero cost.