# AM-RP-002: observation evidence contract, version 0.1

Author: Anant Mishra. Prepared 5 November 2026. Synthetic software reference only; no field data, model, review interface or policy simulation.

## Scope

Classify one already-selected container fill observation at a named decision time. The caller must resolve asset/property/procedure/units and select history correctly. The reference does not implement authentication, ingestion, sensor calibration, deduplication, historical selection, clock repair or dispatch. A current value can still be physically wrong.

The six-record fixture is invented. Its 900-second maximum age is a demonstration parameter, not a recommended service objective. The supplied accepted quality flag is an assertion, not proof of quality. Null record means absent evidence, never zero.

## Contract

Validate supplied record structure and finite numeric fill percentage in 0..100. Boolean and string values are rejected. Require an asset, accepted/suspect quality, observed/unknown time origin, offset-bearing receipt timestamp, and an offset-bearing observation timestamp when origin is observed. Known observation time after receipt is invalid under this strict clock assumption. Do not silently infer a correction.

Classification precedence after validation:

1. Absent record: missing, null value.
2. Receipt later than decision cutoff: not_yet_received, excluded.
3. Unknown observation-time origin: unknown_time, excluded even if a server timestamp exists.
4. Suspect quality: suspect, excluded.
5. Age greater than declared maximum: stale, excluded.
6. Otherwise: current, eligible only for this narrow contract.

Exactly-at-cutoff receipt is visible; exactly-at-age-limit is accepted. Known timestamps with different offsets compare by instant. Age is measured from observation time. Do not replace it with receipt age. Unknown-origin timestamps, if supplied, are parsed but never treated as known measurement times.

The output preserves the value, primary state, observation age when interpretable and eligibility flag. Consumers must honor the flag; this reference does not enforce downstream use. Secondary issues remain in the original input. A production boundary should prevent excluded records from entering a current-decision input set.

## Reproduce offline

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

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

Fixture expectation: one each of current, missing, stale, unknown_time, suspect and not_yet_received. Fourteen synthetic software tests cover fixture states, zero/missing, delayed receipt, exact cutoffs, age boundary, unknown time origin, quality, precedence, invalid values/times/contracts, offsets and input preservation. The release gate runs these tests. These are not fourteen physical observations or operational trials.

## Primary references and interpretation

- OGC SensorThings API 1.1: https://docs.ogc.org/is/18-088/18-088.html — phenomenon time, result-generation time, quality, validity and server-time defaults. Result time is not automatically application receipt time.
- W3C/OGC SSN/SOSA, 2017 Recommendation: https://www.w3.org/TR/2017/REC-vocab-ssn-20171019/ — observation, property, feature, procedure and temporal distinctions. This intentionally stable dated reference is used rather than treating later working drafts as adopted requirements.

Reviewed 5 November 2026. The six states, strict clock policy and age threshold are application choices. No standards conformance or certification is claimed. AI assistance was used in preparation.

## Remaining research

Authorized operational histories, verified sensor procedures and clock uncertainty, justified decision-specific age limits, robust history selection, an actual review interface, downstream enforcement, policy simulations and accountable review remain required. The earlier collection-ledger fixture and counting rules are preserved. No municipal outcome, DGX experiment, peer review or scholarly indexing is claimed.