railiance-telemetry/docs/signal-contract.md

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:

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.