# AM-RP-002: collection-metric preparation

Author: Anant Mishra. Prepared 29 October 2026. Version 0.1.0.

**Synthetic software fixture only.** All visits, identifiers, events, and January 2026 timestamps are invented. The dates describe a test scenario, not fieldwork. No municipal deployment, policy comparison, or service improvement is claimed.

## Reproduce the metric

Requires Python 3.10 or later; no third-party package, model, credential, or network connection is needed. From the repository root:

```sh
python3 public/research/waste-digital-twin-protocol/preparation/collection_ledger.py --as-of 2026-01-15T12:00:00Z
python3 public/research/waste-digital-twin-protocol/preparation/collection_ledger.py --as-of 2026-01-15T15:00:00Z
python3 scripts/test_collection_ledger.py -v
```

Readers downloading the files can place `collection_ledger.py` beside `synthetic-fixture.json` and run `python3 collection_ledger.py --as-of 2026-01-15T12:00:00Z`. The test suite is in the website repository at `scripts/test_collection_ledger.py`.

## Files

- `metric-contract.json`: unit, denominator, visibility and correction rules, exclusions, and expected synthetic snapshots.
- `synthetic-fixture.json`: eight fixed planned visits; seven distinct event IDs and one identical retransmission. V04 has two accepted report revisions. V02 arrives late. V05 has an event after both demonstration cutoffs.
- `collection_ledger.py`: small offline reference function and command-line entry point. The output is labelled `synthetic_software_fixture_only`.

## Counting rules

The denominator is the fixed plan's unique visit IDs. It never depends on the number of uploads. For a cutoff, use the highest accepted revision whose platform receipt time is at or before that cutoff. Accepted statuses are `completed` and `exception`. No visible report produces `unreported`, which is not a confirmed missed collection.

An identical event-ID retransmission has no additional effect. Conflicting payloads for an event ID, conflicting visit revisions, unknown visit IDs, duplicate planned IDs, naive timestamps, events outside the fixed service window, and receipts preceding event time are rejected. The end of the service window is exclusive. The entire input file is validated before a snapshot is computed; this is not a production quarantine/partial-ingestion system.

For each snapshot, completed + exception + unreported must equal planned visits. The recorded completion fraction is completed/planned. For an empty plan it is `null`, not zero or one. The two example snapshots both have a fraction of 3/8, but different visit states. These outputs follow from the invented fixture and do not estimate municipal performance.

Event time, result-generation time, and receipt time have different meanings. This reference records event and platform receipt time; it does not implement the OGC data model or assert conformance. Revision numbers represent reports accepted by a hypothetical upstream process. The function does not authenticate a reporter or verify physical collection.

## Evidence boundary and next dependencies

The local tests cover metric invariants and counterexamples. They do not validate a municipality, representative missingness rates, service deadlines, GPS, an event-ingestion service, or a complete digital twin. Live schedule changes, cancellations, population coverage, collected mass, capacity constraints, policy comparisons, and field effectiveness remain outside the reference function.

Next steps are authorised operational definitions and data, an implemented provenance/verification process, explicit plan-change rules, and the simulation's vehicle, facility, and material-balance components. Any later fixed/reactive/predictive comparison needs controlled scenarios, permitted inputs, actual execution logs, and limitations. The research protocol remains a protocol, without empirical conclusions, peer review, or a publication identifier.

## Primary references

- UN-Habitat/UNSD, SDG 11.6.1 metadata, updated 23 April 2025: https://unstats.un.org/sdgs/metadata/files/Metadata-11-06-01.pdf
- OGC SensorThings API Part 1: Sensing, version 1.1, Observation time properties: https://docs.ogc.org/is/18-088/18-088.html

Checked 29 October 2026. The operational metric and fixtures are proposed engineering choices. The sources neither prescribe this ledger nor validate its output as an official indicator. AI assistance was used in preparing the draft material and tests; no author-reviewed scholarly results release is asserted.