# AM-RP-002: material-account contract v0.1

Author: Anant Mishra. Prepared 6 November 2026. Synthetic software arithmetic only; no facility, instrument, recovery yield, downstream use or policy experiment evaluated.

## Boundary and assumptions

One already-aggregated account for one physical facility and one declared reporting window. The caller must establish that boundary and measurement basis independently. The reference does not ingest weighbridge events, authenticate documents, remove duplicates, trace cohorts, measure stock, validate scales, estimate moisture or classify legal waste operations.

Quantities are integer grams. All seven fields must exist: opening_stock_g, incoming_g, other_inflow_g, material_output_g, residue_output_g, other_outflow_g, closing_stock_g. Unit must be g. Each quantity is a nonnegative integer or explicit null. Reject booleans, floats, strings, negative numbers, missing keys and extra keys. Unit conversion and rounding require a separately reviewed adapter.

The fictional mechanical-sorting account assumes zero other inflows and outflows. Real processes may need such streams, measured on the same basis. Do not use them as balancing plugs. Destination acceptance, processing and actual recycling remain separate evidence.

## Arithmetic and result states

Available = opening stock + incoming + other inflows.

Accounted = material output + residue output + other outflows + closing stock.

Signed discrepancy = available - accounted.

Validate all known quantities even if another is unknown. Any null quantity returns incomplete, named missing fields and null totals/discrepancy. Zero is a known quantity. With complete quantities, exact zero is balanced. A nonzero discrepancy whose absolute value is at or below the explicit tolerance is within_tolerance; preserve its signed value. A larger absolute difference is unreconciled. Tolerance is a required nonnegative integer number of grams. The reference infers no cause and calculates no recovery percentage.

The four-case fixture uses a 1,000-gram tolerance only as an invented demonstration, not an instrument specification or recommended operating target:

- Balanced: 120 kg opening + 1,000 kg incoming = 620 kg material output + 230 kg residue + 270 kg closing. Other flows zero.
- Missing stock: closing is unknown; no numeric discrepancy is reported.
- Small discrepancy: closing 269.5 kg gives +0.5 kg, retained despite being within the fixture tolerance.
- Excess assigned output: material output 630 kg gives -10 kg, unreconciled.

Opening stock and closing inventory prevent assigning outputs to a particular incoming cohort without more evidence. The balance establishes arithmetic consistency only. Even a perfect balance can contain incorrect, incomplete-scope or fabricated underlying records.

## Reproduce

Python 3.10 or newer, standard library only, from repository root:

```sh
PYTHONDONTWRITEBYTECODE=1 python3 public/research/waste-digital-twin-protocol/preparation/material_balance.py
PYTHONDONTWRITEBYTECODE=1 python3 public/research/waste-digital-twin-protocol/preparation/test_material_balance.py -v
```

Keep both Python files and synthetic-material-accounts.json in the same directory if downloading separately. Fourteen tests cover fixed cases, inventory/other-flow terms, signed differences, zero versus unknown, exact tolerance edges, invalid inputs, unit enforcement, field completeness, non-mutation and arbitrary-size integer precision. They check software behavior, not field effectiveness. The release gate runs them alongside all existing references.

## Primary sources and interpretation

- UNEP/UNSD/UNITAR, SDG 12.5.1 metadata, updated 24 May 2024: https://unstats.un.org/sdgs/metadata/files/Metadata-12-05-01.pdf — national scope, measurement points and losses along the recycling chain. This local reference does not calculate that indicator.
- US EPA, The U.S. Recycling System, updated 22 January 2026: https://www.epa.gov/circulareconomy/us-recycling-system — collection, processing and remanufacturing are distinct stages. No US compliance or completed downstream recycling is claimed for the fictional design.

Reviewed 6 November 2026. The equation, field contract, case quantities and tolerance treatment are original demonstration choices, not a prescribed official reporting method. AI assistance was used in preparation. No scholarly identifier, peer review or Scholar indexing is claimed.

## Next evidence

Authorized facility records; verified physical/time boundaries, scales and stock methods; justified uncertainty/tolerances; traceable external movements and downstream records; accountable review; and an implemented review workflow. Policy simulation and field evaluation remain separate. All previous collection-ledger and observation-evidence materials are preserved.