# Frozen rail power loop data contract

The values in `contract.json` are frozen. There are 98 briefs (7 power values × 7 durations × 2 conditions) and eight fixed-family architectures per brief. No coefficients differ from the agreed proposal. Per-pack heat is a synthetic thermal design allowance, not a claim about measured heat at fixed load. Usable kWh is net DC energy after cell-internal losses; cooling electricity and converter loss are additional demands. `atlas.json` is generated by the actual pinned Python package and contains all 784 calculations, including catalogue-unavailable outcomes.

## Query and architecture keys

Brief: `{powerKW:750,durationHours:8,condition:"hot"}`, ID `p750-h8-hot`. Default is this brief. Architecture ID is `{batteryId}-{converterId}-{coolerId}`, e.g. `standard-efficient-liquid`. Families are `standard|compact`, `standard|efficient`, `air|liquid`, respectively. All eight records remain visible, including ties. Resource minimisation uses `{capitalGBP,landM2}` componentwise.

## Atlas schema

- `schemaVersion`, `title`, `domain`, `default`, `catalogueCaps`, `catalogues`, `conditions`, `interfaces`, `traceColumns`, `boundary` copy the visible declared model.
- `provenance` contains package version, GitHub source URL and pinned commit, hashes of actual imported package sources, `modelSha256`, `contractSha256`, `generatorSha256`, and deterministic build information. No time-dependent fields.
- `architectures`: eight `{id,label,battery,converter,cooler}` objects; family fields are IDs.
- `queries`: 98 `{id,powerKW,durationHours,condition,frontier,results}` objects. `frontier` is an array of architecture IDs for all catalogue-feasible nondominated designs; equal cost/land tuples retain every architecture ID.
- `results`: eight objects with `architectureId`, `calculation_status`, `catalogue_feasible`, `verified_complete`, `iterations`, `witness`, `service_only`, `trace`, and `catalogueChecks`.
- `calculation_status` is the package status string. Successful builds require `converged` and exact interface checks. A `max_iter` or `diverged` result aborts the build and must never be labelled catalogue infeasibility.
- `catalogue_feasible` means the complete least count vector fits all three declared availability caps. `verified_complete` means its three physical model interfaces have been independently checked by direct arithmetic after package convergence; it does not mean the availability caps are met or that the design is field validated.
- `witness` and `service_only` have the same shape: `{counts:{batteries,converters,coolers},resources:{capitalGBP,landM2},values:{energyKWh,outputKW,heatKW,coolingKW,drawKW,lossKW},checks:[{id,label,unit,required,provided,margin,satisfied}],complete}`.
- `catalogueChecks`: `[{component,count,limit,satisfied}]`, in battery/converter/cooler order.
- `trace` is an array of integer arrays, each ordered by `traceColumns`: `[iteration,batteries,converters,coolers,heatKW,coolingKW,drawKW,lossKW,capitalGBP,landM2]`. The seed is row zero. Counts and component quantities come from the actual package trace; time and floating deltas are omitted. The converged duplicate final row is retained.
- `summary` counts all cases, statuses, feasible results, and maximum iterations.

## Meaning of the comparison

`service_only` sizes batteries from H×P and converters from P, then sizes cooling for those initial components' heat. It stops without enlarging the batteries/converters to cover cooling draw and converter losses. Its exact three interface checks expose any undersizing. It is a deliberately incomplete once-through comparator, not another solver or a safe configuration. `witness` is the cold-start package feedback result.

## Availability and UI ceilings

Modules calculate unbounded non-negative integer counts by exact ceiling division. Their declared extended-natural input posets also contain top (+infinity); each module explicitly maps top demand to all-resource top through the normal Module wrapper. This mathematical boundary does not add any supported outer power/duration value. `module_boundary_tests.py` checks the direct module calls, zero and first rating boundaries. After convergence the least count vector is checked against the explicit catalogue caps 32/12/20. Because the monotone count map starts at zero, its fixed point is componentwise no larger than every compatible count vector within the same architecture. Exceeding a cap therefore proves no available implementation of that architecture exists. This avoids the package's partial-top/divergence behaviour when a module returns an empty antichain.

UI capital and land ceilings filter only records with `calculation_status="converged"`, `verified_complete=true` and `catalogue_feasible=true`. Retain family IDs and all ties. Such upper-resource ceilings preserve any admissible point's componentwise dominators, so the global frontier may be filtered directly. If displaying all remaining architectures, recomputing its two-resource Pareto subset is merely post-filtering package results, not running a JS co-design solver.

## Embedding and reproduction

The UI embeds the exact JSON in a script with `id="mcdp-atlas"` and type `application/json`; no network or Python browser dependency is needed. `build_atlas.py` writes only `atlas.json`; it does not edit the app. `build_atlas.py --check` regenerates and byte-compares the atlas. Install `requirements.txt` in an isolated environment. The independent oracle is maintained separately and imports no model sizing or transition helpers.