tegwick
cecef79f31
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a06ecb-456a-71c2-b41e-0755d336e883
72 lines
4.3 KiB
Markdown
72 lines
4.3 KiB
Markdown
# Private signal contract v1
|
|
|
|
Q2 owns carriage and visibility; producers own signal meaning. This initial
|
|
contract and CLI receiver are a local reference implementation, not a deployed
|
|
monitoring package or authenticated network service.
|
|
|
|
The stream contract pins producer, stream, exact signal names, intended local
|
|
recipient, freshness budget, heartbeat budget and retention. See
|
|
`contracts/platform-assurance.json`. Its 15-minute budgets and 30-day retention
|
|
are proposed defaults pending runtime/operator acceptance. The recipient
|
|
`railiance-platform-operator` names an intended role, not a confirmed person or
|
|
external messaging address. No notification is sent by these tools.
|
|
|
|
An event has exactly `schema` (`railiance-telemetry.signal.v1`), canonical UUID
|
|
`id`, `stream`, `producer`, timezone-aware `observed_at`, and `states`. Every
|
|
registered signal is present, with one of healthy/stale/missing/unavailable/
|
|
failed. There are no values, logs, URLs or free-text details. Duplicate JSON
|
|
keys, unknown fields, payloads over 32 KiB, wrong producer/stream/signal names,
|
|
future/expired events and out-of-order events are rejected. Local process/file
|
|
access is the trust boundary; producer names are not authentication. Do not
|
|
expose this CLI through an unauthenticated HTTP wrapper.
|
|
|
|
Acceptance commits an event and an operator notice in one SQLite transaction.
|
|
The returned receipt says `local-inbox-only`. Reusing an ID with identical data
|
|
is idempotent and does not advance liveness; changed data under that ID fails.
|
|
Equal timestamps under new IDs also fail. Retry the same event file, not a newly
|
|
translated event. Contract changes require an explicit database migration.
|
|
|
|
`check` detects both never-seen and expired emissions, based on original event
|
|
time. It suppresses repeated missing-emission notices until a new event arrives.
|
|
An independent accepted scheduler must run it. If that scheduler or this receiver
|
|
stops, these tools cannot report their own absence: runtime acceptance must add
|
|
an external receiver heartbeat check. Inbox reads never acknowledge implicitly.
|
|
`ack` records explicit local operator acknowledgment; it proves no external
|
|
notification. Run in a private directory (`umask 077`), one database per stream.
|
|
|
|
Retention is an explicit `prune` operation: retain at least the contract's days,
|
|
all unacknowledged notices/events and the latest replay/absence anchors. Pending
|
|
acknowledgments can extend retention indefinitely. At 10,000 events ingestion
|
|
fails rather than silently dropping evidence. Monitor capacity and prune through
|
|
the approved owner; no background expiry is installed. This is operational
|
|
storage, not immutable audit custody or independently backed-up evidence.
|
|
|
|
## Local workflow
|
|
|
|
Python 3.11+ standard library only. From the repository root:
|
|
|
|
```bash
|
|
python3 -m unittest discover -s tests -v
|
|
umask 077
|
|
mkdir -p /tmp/rtel-private
|
|
python3 scripts/platform_event.py --contract contracts/platform-assurance.json /path/to/fresh-platform-report.json > /tmp/rtel-private/event.json
|
|
python3 scripts/receiver.py --contract contracts/platform-assurance.json --database /tmp/rtel-private/receiver.db ingest /tmp/rtel-private/event.json
|
|
python3 scripts/receiver.py --contract contracts/platform-assurance.json --database /tmp/rtel-private/receiver.db check
|
|
python3 scripts/receiver.py --contract contracts/platform-assurance.json --database /tmp/rtel-private/receiver.db inbox
|
|
```
|
|
|
|
The platform adapter consumes the existing assurance evaluator report, preserves
|
|
`evaluated_at` as producer observation time, and carries each existing state.
|
|
Backup/restore age remains S3's classification; Q2 does not re-age those receipts.
|
|
The adapter does not change the source report's unmonitored/unsupported status.
|
|
Its signal inventory is pinned to platform source at initial review; changes
|
|
require coordinated contract review and tests.
|
|
|
|
## Required live acceptance
|
|
|
|
RTEL-WP-0002-T04 tracks runtime/package owner selection, private authenticated
|
|
execution, durable storage/backup, confirmed operator recipient, accepted cadence
|
|
and retention, independent receiver-watchdog delivery, and controlled failure /
|
|
producer-absence delivery acknowledged by that operator. Request scope already
|
|
covers reference implementation; no live scheduler or messaging authorization
|
|
is inferred. RPF-WP-0036-T04 stays open until those receipts exist.
|