Designing a Collection Ledger That Can Explain Its Numbers

The proposed decision boundary

Imagine a supervisor reviewing a fictional district's collection shift. Some crews are connected, one uploads later, and another submits a correction. The supervisor needs a list of unresolved visits and an explanation of the headline completion figure.

This design study proposes a small ledger for that purpose. Its worked fixture contains eight invented planned visits. A standard-library Python reference function exercises the counting rules locally. Neither the fixture nor its software tests represent a municipality, a commissioned system, or a demonstrated service improvement.

Choose an operational unit and hold it steady

The unit is one planned visit, identified by a stable visit ID. Multiple visits to the same collection point would have different IDs. The fixture's denominator is the eight visits in its fixed plan; it is independent of how many event rows arrive.

The output calls its ratio a recorded completion fraction. It does not calculate household access, population coverage, waste tonnage, or controlled treatment. The official SDG 11.6.1 metadata distinguishes service access from collected quantities and sets a wider waste-management boundary. That supplies context for keeping this narrower operational measure explicit. [1]

A real service would need authorised schedule revisions and rules for cancellations or additional visits. Those are outside this first reference function. Accepting a report with an unknown visit ID therefore raises an input error instead of changing the denominator.

Separate a report from a completed visit

Each synthetic report carries an event ID, visit ID, revision, event time, platform receipt time, and status. The two accepted status values are completed and exception. A visit with no visible report remains unreported.

Retransmitting the identical event ID and payload is treated as a duplicate. It creates no additional visit and no second completion. Reusing an event ID for different content is rejected. Two different payloads claiming the same visit revision also require resolution rather than an arbitrary choice.

Revisions stand for reports already accepted by the hypothetical upstream process. The function does not authenticate a reporter or determine whether their assertion is physically true. A production ingestion service would need those controls before its records could be trusted.

Reconstruct what was available at a cutoff

For a chosen cutoff, the function considers only events received by then. It selects the highest visible revision for each planned visit and returns the visit-level states with their counts. Events dated after the cutoff cannot enter that snapshot.

The design keeps event time and receipt time separate. OGC SensorThings distinguishes observation time from result-generation time; the additional receipt timestamp here records arrival at this platform. The example does not claim SensorThings conformance or equate receipt time with the standard's result time. [2]

In the fictional fixture, a completion for visit V02 arrives after noon. An earlier completion report for V04 is later corrected to an exception. Replaying noon excludes both later receipts. Replaying 15:00 admits them. The earlier report remains available in the input history.

Explain why a stable percentage can hide a change

The fixture deliberately produces three recorded completions out of eight planned visits at both cutoffs. The underlying visits differ. At noon, V04 is recorded complete and V02 is unreported. At 15:00, V02 is recorded complete and V04 is an exception.

Those are deterministic outputs from invented records, not observed municipal performance. Their purpose is to expose a reporting problem: a headline ratio can remain unchanged while the supervisor's action list changes. The view should therefore retain visit-level detail, exception counts, and unreported counts.

An unreported visit is not automatically a missed collection. The fixture has no field-verification workflow or service-deadline classifier. It preserves that uncertainty so later work can add those rules deliberately.

Test invariants before comparing policies

The preparation tests check that duplicate uploads cannot inflate completion, input ordering does not alter the result, later receipts cannot leak into an earlier snapshot, and corrections apply only once visible. They also reject conflicting identities, unknown visits, invalid time order, and duplicate plan entries.

An empty plan returns no completion fraction, rather than a fabricated zero or perfect score. For every valid snapshot, completed, exception, and unreported counts must sum to the fixed denominator. These checks protect the meaning of the measure; they do not prove that a production event pipeline is reliable.

The pack includes the metric contract, the fixed synthetic fixture, the reference function, and a guide explaining its boundaries. Local tests exercise those files without connecting to a government system or a hardware inference service.

What remains before a digital twin can use it

A broader waste digital twin still needs vehicle constraints, material conservation, facility capacities, policy implementations, and repeated seeded scenarios. This ledger supplies one small measurement component. It neither implements nor ranks fixed, reactive, and predictive collection policies.

Field transition would require authorised schedules, event provenance, reconciliation against service evidence, and agreement on deadlines, cancellations, and reporting corrections. Dispatch recommendations would need accountable human review and a separately evaluated operational baseline.

The research protocol links the preparation pack and records those dependencies. The related collection-metrics essay explains how this narrow ledger fits alongside population, mass, and facility measures without substituting for them.