72 lines
3.4 KiB
Markdown
72 lines
3.4 KiB
Markdown
|
# Adopting the Emission Cadence contract as a source owner
|
||
|
|
|
||
|
|
The Emission Cadence standard is at **candidate** (document `0.2.0`, wire schema
|
||
|
|
version `0.1`). Candidate means the contract is specified and machine-checkable.
|
||
|
|
It asserts nothing about adoption: no source has implemented it.
|
||
|
|
|
||
|
|
This page is what a source owner needs in order to change that. It asks for a
|
||
|
|
declaration you own, not for a change to your system.
|
||
|
|
|
||
|
|
## What the contract is for
|
||
|
|
|
||
|
|
A source declares how often it emits an event class, so that an observer can
|
||
|
|
tell **silence that means nothing happened** from **silence that means the source
|
||
|
|
stopped**. Without a declared cadence, an absent event is unreadable. The
|
||
|
|
standard keeps the two roles apart: the source declares, the observer evaluates,
|
||
|
|
and a declaration is never evidence that the emission actually happens.
|
||
|
|
|
||
|
|
## What a source owner supplies
|
||
|
|
|
||
|
|
1. **A declaration you own**, valid against
|
||
|
|
`infospace/schemas/emission-cadence.schema.yaml`, published in your own
|
||
|
|
repository. It states your `source`, your `stream_id`, and one entry per
|
||
|
|
event class you own, in one of the declared forms:
|
||
|
|
- `expected-rate` — at least N events in a window, below which a finding is raised;
|
||
|
|
- `heartbeat-or-reconciliation` — either a heartbeat asserting
|
||
|
|
`nothing-to-report`, or a comparison between your own counts and the
|
||
|
|
observer's.
|
||
|
|
2. **The contract digest you implemented against**, so the declaration is pinned
|
||
|
|
to a fixed reading of the contract rather than to whatever the canon says
|
||
|
|
later. Current digest: `972c0b6701d1693f`
|
||
|
|
(`info_tech_canon export-emission-contract <path.tar>` regenerates it).
|
||
|
|
3. **Nothing else.** No deployment, no runtime proof, no conformance claim. A
|
||
|
|
declaration is a statement of intended cadence.
|
||
|
|
|
||
|
|
Validate before publishing:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
info_tech_canon emission-review path/to/your-declaration.yaml
|
||
|
|
```
|
||
|
|
|
||
|
|
It returns `ok` plus `operational_truth_assessed: false` — the command checks
|
||
|
|
your declaration against the schema and deliberately says nothing about whether
|
||
|
|
your system emits at that cadence.
|
||
|
|
|
||
|
|
`infospace/standards/emission-cadence/examples/qonto-assistant.yaml` shows both
|
||
|
|
forms. It is a worked example and explicitly not a source-owned declaration.
|
||
|
|
|
||
|
|
## What an observer supplies
|
||
|
|
|
||
|
|
Separately from any source: a result produced by evaluating a source's declared
|
||
|
|
cadence against events you actually observed, with the comparison references the
|
||
|
|
declaration names. An observer result from the declaring source does not count —
|
||
|
|
the point is that two parties read the same declaration the same way.
|
||
|
|
|
||
|
|
## What this repository does with it
|
||
|
|
|
||
|
|
Validates submitted declarations, records them as adoption evidence, and reports
|
||
|
|
any incompatibility found in the attempt. It does not operate your system,
|
||
|
|
observe your events, or certify your conformance.
|
||
|
|
|
||
|
|
Two source-owned declarations from independent owners, plus one third-party
|
||
|
|
observer result, plus a recorded incompatibility or a recorded absence of one,
|
||
|
|
are what the standard's section 10 requires to move from candidate to stable.
|
||
|
|
|
||
|
|
## What is honestly uncertain
|
||
|
|
|
||
|
|
The contract has never been implemented by anyone. The most useful thing a first
|
||
|
|
adopter can report is **where it does not fit** — a cadence your system has that
|
||
|
|
neither form expresses, a window semantics mismatch, an event class that needs
|
||
|
|
more than one entry. A recorded incompatibility is a successful outcome of this
|
||
|
|
exercise, not a failure of it.
|