31 lines
2.3 KiB
Markdown
31 lines
2.3 KiB
Markdown
# Evidence reference contract v1
|
|
|
|
This contract shares metadata about a logical evidence object. It never grants object access. `owner_id` identifies the service that owns resolution; `evidence_id` is opaque to every consumer. Neither field may be interpreted as a URL or local path.
|
|
|
|
## State and degradation
|
|
|
|
- `pending`: capture was accepted but no processing started.
|
|
- `processing`: capture or encoding is in progress.
|
|
- `success`: capture completed; `content_type` and SHA-256 `integrity` are required. Access authorization is negotiated outside this payload by the machine-identity/connector work.
|
|
- `failed`: `failure.code` and `retryable` are required. Bell keeps the immutable Event and renders evidence unavailable; it must not reject or close the Alert because evidence failed.
|
|
- HTTP `404` means an unknown logical reference. `410` means expired evidence. Both degrade evidence only, not the Event.
|
|
|
|
The payload forbids arbitrary properties, so filesystem paths, camera credentials, bearer/user tokens, signed URLs, face templates and notification/Alert state fail schema validation. Do not add access URLs to v1. A short-lived download grant, if later required, needs a separately reviewed endpoint and security contract.
|
|
|
|
## Ownership
|
|
|
|
- Brain may request evidence but maps only logical metadata it actually knows.
|
|
- Sense is the default evidence owner and advances the status monotonically for a given capture attempt: `pending -> processing -> success|failed`. It must retain the same `evidence_id` while status changes.
|
|
- A relay transports the reference unchanged and must not resolve it into a path or URL.
|
|
- Bell stores the latest evidence metadata separately from its immutable Event. Evidence failure/expiry never changes Alert ack/close state.
|
|
|
|
## Compatibility and rollback
|
|
|
|
v1 consumers ignore no unknown fields because the v1 schema is closed. Additive fields therefore require a new schema revision that producers enable only after consumers accept it. Changed meaning, removed fields, or new required fields require `/v2`. Rollback disables the new producer and continues resolving stored v1 references; it never deletes Event, Receipt, Outbox, or evidence audit facts.
|
|
|
|
Run the standalone contract check from the repository root:
|
|
|
|
```powershell
|
|
python contracts/tests/evidence-v1/test_contract.py
|
|
```
|