# Wildlife monitoring power loop data contract

The declared values in `contract.json` define the current monitoring model. There are 98 briefs (7 power values × 7 durations × 2 conditions) and eight fixed-family architectures per brief. Power and energy now use W and Wh; costs use GBP and the second resource is allocated cabinet volume in L. The migration and synthetic volume relation are explicit in `scenarioMapping`. Per-pack heat is a synthetic thermal design allowance, not a claim about measured heat at fixed load. Usable Wh 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: `{powerW: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,volumeL}` componentwise.

## Atlas schema

- `schemaVersion`, `title`, `domain`, `default`, `catalogueCaps`, `catalogues`, `conditions`, `interfaces`, `traceColumns`, `boundary`, `physicalAssumptions`, `unitContract`, `scenarioMapping` 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,powerW,durationHours,condition,frontier,results}` objects. `frontier` is an array of architecture IDs for all catalogue-feasible nondominated designs; equal cost/volume 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,volumeL},values:{energyWh,outputW,heatW,coolingW,drawW,lossW},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,heatW,coolingW,drawW,lossW,capitalGBP,volumeL]`. 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 cabinet volume 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.

## Route and unit boundary

The active page is `monitoring-power-loop.html`, schema `monitoring-power-loop-1`, record format `monitoring-power-loop-comparison-1`. New share links use `powerW` and `volume` query parameters. The historical `rail-power-loop.html` route is a static notice with no script, redirect or query forwarding. It links to the new default and to the immutable historical source. Its saved railway queries are never interpreted as monitoring watts. The legacy documentation directory is retained for stable source links; its current files describe the new monitoring contract.