--- title: Architecture transition ledger --- # Architecture transition ledger The solver, result, and execution architecture is moving in vertical slices. Every built-in kernel publishes a native core-program graph and a public `KernelOutput`. Bootstrap policies and deliberately deferred integrations keep each slice bounded. Every item below has an explicit replacement or retirement condition. A plan step is not complete while its corresponding transition item remains without a current justification. One invariant is permanent rather than transitional: a result never authenticates its own values or replay artifacts. Before forward execution, the consuming `Model` owns immutable descriptors built from its canonical regimes and parameters and, for data-dependent adaptive axes, a private solve-side record. Those descriptors own the exact artifact identity and channel, payload type, canonical dtypes, ordered axes and lengths, state/action roles, categorical code domains, applicability, requiredness, and consuming replay route. Payloads and repeated public metadata are checked independently against that authority at every log level. A future descriptor registry may replace today's private concrete dispatch, but must preserve this direction of authority. | Transitional implementation | Exact replacement or retirement condition | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The private `_lcm.execution.core_program` types and the current narrow `CoreExecutionRequirements` for action products and exact GridSearch target-value accesses | Plain EGM, GridSearch, NB-EGM, and an out-of-tree conformance solver have exercised a versioned public contract in `lcm.solver_api`. The public requirements describe all named axes, minimum widths and alignment, legal reordering, core dependencies, input access, reductions, output roles, and replay/retention needs without importing `_lcm`; graph liveness and the planner, not the solver program, select legal donation. | | The private target/source value-address types and the two-operation transfer catalogue, `ALIGNED_LOCAL` and `COPY_TO_SOURCE_LAYOUT`, used by the first GridSearch input-planning slice | A graph-wide input contract covers all built-in solvers and an external conformance route, expresses named-axis/layout conversions, and gives each target-to-source edge one planner-owned transfer. Replace the private address and adapter types and their tests through that seam in the same change. Add another transfer operation before then only for a demonstrated production route with fail-closed metadata, lowering/runtime identity, partial-mesh coverage, and a recorded retirement path. | | `PlannedInputLiveness` as eligibility-only remaining-consumer accounting. For planned GridSearch value reads, the transfer gate matches every declared `(source_regime, source_period, core_key)` to the actual compiled `_CoreTriple` and independently resolves its channel/path to the compiled-program argument leaf. Counts commit only after successful dispatch; dense programs that declare no value reads, retained-result consumers, and fold and gated-edge reads remain conservatively pinned. | The graph-wide planner extends that validation to every solve consumer, retention obligation, fold/gated-edge read, alias, and synchronization boundary; distributed tests prove safe physical lifetime transitions. A scheduler then owns release, donation, or offload after successful dispatch. Fold this ledger into that scheduler and delete its tests in the same change. Until then zero is not a memory action and no pin is removed merely because planned counts close. | | Process-local lowering deduplication based on Python callable identity plus the current `CoreProgram.specialization_key` fragment | A durable semantic compilation key covers solver API and kernel versions, core kind and period group, shapes and dtypes, arithmetic profile and topology, resolved layouts and submesh, retention and diagnostic specialization, static model and parameter fingerprints, tile widths, and relevant compiler options. Equivalent separately constructed cores then share a compiled executable without relying on object identity. | | The initial action-width policy that chooses a bounded power of two below the full product, capped at 64 | `ExecutionConfig` and the graph-wide planner reject memory-infeasible widths from lowering evidence, benchmark a deterministic feasible frontier on the target hardware, and cache the measured choice by the complete semantic and hardware key. No production test depends on the bootstrap cap or power-of-two rule. | | The first GridSearch `CoreProgram` covers solve-time singleton hard max and EV1 `VALUE`, plus collective `(VALUE, DISSOLUTION_FLAG)`, but publishes no replay or policy artifact | The declared output and retention contract can publish every graph-required channel and any requested replay artifact. Production simulation consumes the declared replay or recomputation route, and value-only execution is a retention specialization rather than a separate solver boundary. | | Dense GridSearch programs for co-map routes whose separate same-period or edge-reference channels lack named transfer metadata, action products of extent at most one, and dense simulation-policy construction | Each remaining nontrivial route has its own production `CoreProgram` and route-specific streamed reduction: every co-mapped input channel receives explicit named-axis transfer metadata; simulation retains the requested policy identity or moments. Trivial action products may remain dense only as an explicit no-streaming identity route. Public solve/simulation tests, partial-tile and global-identity oracles, and the candidate certificate cover every migrated route before its dense disposition is removed. | | EV1 GridSearch uses the explicit dense disposition `deliberately_dense:ev1_canonical_reduction_order`; the internal streamed log-sum-exp implementation remains a reference only because blocked grouping changes canonical floating-point values and can flip winners | A streamed implementation reproduces the declared dense EV1 reduction order and values exactly for both precision profiles across exhaustive small supports, partial and non-divisor tiles, and the recorded adversarial winner-flip class. Solve and simulation replay or policy-moment tests establish the same candidate identity before this disposition is removed. | | Collective GridSearch uses the explicit dense disposition `deliberately_dense:collective_resource_regression`; the internal streamed collective reducer remains a reference only because paired production-shape evidence regressed warm runtime, compilation, host/compiler memory, temporary/device memory, and HLO size | A streamed collective implementation preserves candidate identity, shared feasibility, stakeholder readout, and dissolution exactly and wins a representative paired benchmark envelope on the supported hardware across runtime, compilation, host/compiler memory, temporary/device memory, and graph-size measures. Retain the independent dense oracle after production migration. | | `ArtifactStore.project()` | Replay routes and readers consume addressed artifact stores directly. | | Concrete built-in descriptor construction and replay-validator dispatch in the output bridge and `Model` | A dependency-safe descriptor registry owns construction and validation for every installed artifact type without making returned payloads or their public metadata authoritative. The registry must preserve the permanent model-authority invariant above, including independent checks of values and repeated metadata, before this concrete dispatch is removed. | | `GeneratedReplayAuthority` and `Model._solution_authorities`: a kernel emits the exact data-dependent adaptive replay-axis coordinates on the auxiliary channel of its `KernelOutput` under the engine-private key `GENERATED_REPLAY_AUTHORITY`, the solve loop keeps them beside the policy they describe, and the model binds them into its authority and caches them per parameter fingerprint; storage grows only with distinct adaptive-route parameter fingerprints and relies on the deterministic mesh for equal model/parameter inputs; the adaptive replay policy is omitted as `NOT_PERSISTED` under `ALL_PERSISTABLE_ARTIFACTS` because nothing persistable carries those coordinates | Stable persistence provides a model-verifiable semantic descriptor for dynamic solver output contracts, or the model can independently rederive those exact axes without consulting returned artifacts. Then delete the process-local sidecar/cache and its pickle transport while retaining fail-closed preflight. | | `SolverDiagnostics` travels on the auxiliary channel of a `KernelOutput` under `SOLVER_DIAGNOSTICS`, and the loop keeps it only under the caller's `collect_solver_diagnostics` flag | Diagnostics are labelled artifacts whose construction and retention are governed only by `log_level`. | | `ContinuationPayload = ContinuationArtifact`, a keyed protocol the engine rolls opaquely, while every shipped producer and reader still exchanges the concrete `EGMCarry` fields | A `ContinuationReader` protocol carries the operations a parent needs (interpolated value and marginal at a query), and every shipped producer/consumer requests those operations instead of reading `EGMCarry` fields. Do not broaden the alias to `object`; the key already carries identity and version, so what remains is the operation vocabulary. | | Candidate-certificate source seals anchored to the current migration seams | Any callable move, bridge deletion, or source-route change deliberately regenerates and reviews the source inventory, then passes both precision profiles, every synchronized mutation, and every source-set perturbation. Never refresh a seal merely to make a changed route green. | | Hardware semantics in grid `batch_size` and `distributed` fields | `ExecutionConfig` and resolved planner layouts own the corresponding placement and tile choices; grids retain only economic support, ordering, interpolation, and quadrature semantics. | | EGM executes one program and DC-EGM executes its output-specialized values/replay variants dense under explicit reasons (`egm_one_row_no_product_axis`, `dcegm_solver_owned_node_and_grid_batching`): the one-row EGM step has no product axis to stream, and the DC-EGM step owns its stochastic-node and refined-grid batching through the solver's own `batch_size` knobs | The execution planner owns the stochastic-node width and the refined-grid batching, with a hard-max reduction the streamed reducer can carry; each dense disposition is then replaced by planned streamable axes and its solver-side batching knob retired | | NEGM's `outer_sweep` program takes the keeper's value and carry as arguments: its builder lowers with zero-filled placeholders in the keeper outputs' shape, and the kernel runs `keeper` first and replaces exactly those two arguments before dispatching the sweep, because a `CoreProgram` graph declares no dependency between its programs | `CoreProgram` declares typed internal outputs, so a graph names one program's outputs as another's inputs and the loop threads them between dispatches; the placeholders and the runtime replacement are then deleted | When a new adapter, bootstrap policy, or deferred integration is introduced, add it here in the same change. Remove its row only after the retirement condition is covered by a test through the replacement seam.