Implement canon conformance and maintenance optimizations
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a06e82-3e08-7042-a79d-438ac6eed8db
This commit is contained in:
parent
a2e7f22d8d
commit
b081d39da1
64 changed files with 4491 additions and 373 deletions
|
|
@ -0,0 +1,214 @@
|
|||
---
|
||||
id: itc-emission-cadence:EmissionCadenceDeclaration
|
||||
title: InfoTechCanon Emission Cadence Standard
|
||||
short_name: ITC-EMISSION-CADENCE
|
||||
type: standard
|
||||
standard_family: InfoTechCanon
|
||||
repository_context: info-tech-canon
|
||||
recommended_path: standards/emission-cadence/InfoTechCanonEmissionCadenceStandard.md
|
||||
status: draft
|
||||
version: 0.1.0
|
||||
schema_version: "0.1"
|
||||
canonical_owner: InfoTechCanonEmissionCadenceStandard
|
||||
namespace: itc-emission-cadence
|
||||
classification: standard
|
||||
primary_cluster: observability-contract
|
||||
imports:
|
||||
- InfoTechCanonCore
|
||||
- InfoTechCanonObservabilityModel
|
||||
- InfoTechCanonGovernanceModel
|
||||
related:
|
||||
- InfoTechCanonSecurityModel
|
||||
owned_concepts:
|
||||
- EmissionCadenceDeclaration
|
||||
- EmissionCadenceForm
|
||||
- ExpectedRateCadence
|
||||
- HeartbeatCadence
|
||||
- ReconciliationCadence
|
||||
provenance:
|
||||
source_version: 0.1.0
|
||||
source_file: infospace/assimilation/emission-cadence/source/EmissionCadenceDeclaration.md
|
||||
assimilation: assimilation/emission-cadence
|
||||
decision: GH-DEC-2026-004
|
||||
created_at: "2026-09-04"
|
||||
updated_at: "2026-09-04"
|
||||
---
|
||||
|
||||
# InfoTechCanon Emission Cadence Standard
|
||||
|
||||
**Short Name:** `ITC-EMISSION-CADENCE`
|
||||
**Document Status:** Draft
|
||||
**Version:** 0.1.0
|
||||
**Schema Version:** `0.1`
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This standard defines `EmissionCadenceDeclaration`: a machine-readable,
|
||||
source-authored claim about when records of an event class are expected to be
|
||||
emitted. It lets an observer evaluate a stream's silence separately from the
|
||||
contents and richness of records that did arrive.
|
||||
|
||||
The declaration describes intended emission. It is not a measurement, a health
|
||||
result, or proof that every event was emitted.
|
||||
|
||||
## 2. Ownership boundary
|
||||
|
||||
InfoTechCanon owns the generic forms, fields, validation semantics,
|
||||
compatibility rules, and evolution of this contract.
|
||||
|
||||
Other owners retain their own responsibilities:
|
||||
|
||||
- a source owns each declaration instance and the behavior it declares;
|
||||
- an observer owns measurement, evaluation, and resulting findings;
|
||||
- an importing profile owns domain policy: which classes must declare cadence,
|
||||
which form is required, and any stronger combination or threshold rules;
|
||||
- ITC-OBS owns `Event`, `EventType`, `EventSource`, and missing-signal semantics;
|
||||
- ITC-GOV owns `Finding` and its lifecycle.
|
||||
|
||||
In particular, this standard does not define `attributive` or `load-bearing`
|
||||
evidence, does not require cadence for any security class, and does not require
|
||||
heartbeat and reconciliation together. Those are NetKingdom security-profile
|
||||
rules, not ecosystem-wide semantics.
|
||||
|
||||
## 3. Declaration envelope
|
||||
|
||||
A declaration contains:
|
||||
|
||||
| Field | Requirement | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `schema_version` | required | Contract version understood by the producer. This draft uses `0.1`. |
|
||||
| `declaration_id` | required | Stable identifier for the declaration instance. |
|
||||
| `source` | required | Source system that owns the emission claim. |
|
||||
| `stream_id` | optional | Stable stream identifier when the source publishes more than one stream. |
|
||||
| `sources` | required | One or more event-class cadence entries. The name is retained from the handed-over 0.1 draft. |
|
||||
| `extensions` | optional | Namespaced, profile-owned data that does not change generic field meanings. |
|
||||
|
||||
Every entry in `sources` has a stable `source_id`, an `event_class`, and exactly
|
||||
one generic `form`. A declaration must not contain duplicate `source_id` values.
|
||||
|
||||
## 4. Forms
|
||||
|
||||
### 4.1 `expected-rate`
|
||||
|
||||
`ExpectedRateCadence` says that at least `expected_min` records of an event class
|
||||
are expected in each `window`.
|
||||
|
||||
```yaml
|
||||
source_id: example.audit
|
||||
event_class: audit.recorded
|
||||
form: expected-rate
|
||||
window: PT24H
|
||||
expected_min: 1
|
||||
drop_below: finding
|
||||
```
|
||||
|
||||
The window may be an ISO 8601 duration (`PT24H`) or a positive compact duration
|
||||
using `s`, `m`, `h`, or `d` (`24h`). A producer that cannot use duration strings
|
||||
may provide `window_seconds` instead, but must not provide both.
|
||||
|
||||
Evaluation is performed per complete window unless an importing profile defines
|
||||
a grace rule. A count below `expected_min` satisfies the condition named by
|
||||
`drop_below`. The string names an observer-owned outcome; it does not create or
|
||||
change the ITC-GOV Finding concept.
|
||||
|
||||
### 4.2 `heartbeat-or-reconciliation`
|
||||
|
||||
This form describes one or both of the following mechanisms:
|
||||
|
||||
- `heartbeat`: a positive assertion expected within an interval, so the
|
||||
assertion can itself be missing;
|
||||
- `reconciliation`: references to source-side and observer-side counts whose
|
||||
divergence is evaluated.
|
||||
|
||||
At least one mechanism is required by the generic contract. An importing
|
||||
profile may require both.
|
||||
|
||||
```yaml
|
||||
source_id: example.denials
|
||||
event_class: audit.denied
|
||||
form: heartbeat-or-reconciliation
|
||||
heartbeat:
|
||||
event_class: audit.heartbeat
|
||||
interval: PT24H
|
||||
assertion: nothing-to-report
|
||||
missing: finding
|
||||
reconciliation:
|
||||
compare_local: source_transition_counts.audit.denied
|
||||
compare_observed: evidence_counts.audit.denied
|
||||
divergence: finding
|
||||
undrained_local: lag-not-divergence
|
||||
```
|
||||
|
||||
`heartbeat.interval` follows the same duration rules as the expected-rate
|
||||
window; `interval_seconds` is the alternative integer representation.
|
||||
`compare_local` and `compare_observed` are owner-defined references. This draft
|
||||
does not define a query language for them.
|
||||
|
||||
## 5. Extensions and profiles
|
||||
|
||||
Generic objects are closed: unknown fields fail schema validation. Additional
|
||||
profile data belongs in an `extensions` mapping keyed by an owner-controlled
|
||||
namespace. For example:
|
||||
|
||||
```yaml
|
||||
extensions:
|
||||
netkingdom:
|
||||
evidence_class: load-bearing
|
||||
rate_monitoring: forbidden
|
||||
```
|
||||
|
||||
An extension may narrow use of the generic contract. It must not redefine a
|
||||
generic field, change the meaning of a form, or make an instance that fails the
|
||||
generic schema valid.
|
||||
|
||||
## 6. Validation semantics
|
||||
|
||||
The normative machine contract is
|
||||
`infospace/schemas/emission-cadence.schema.yaml`.
|
||||
|
||||
A conforming generic declaration:
|
||||
|
||||
1. validates against that schema;
|
||||
2. has at least one cadence entry;
|
||||
3. has unique `source_id` values;
|
||||
4. uses one duration representation for each window or interval;
|
||||
5. supplies only expected-rate fields for `expected-rate` entries;
|
||||
6. supplies heartbeat, reconciliation, or both for
|
||||
`heartbeat-or-reconciliation` entries; and
|
||||
7. carries profile-owned data only under a namespaced `extensions` key.
|
||||
|
||||
Schema validation establishes declaration shape, not operational truth.
|
||||
Observers must not infer that a stream is complete merely because its
|
||||
declaration is valid.
|
||||
|
||||
## 7. Compatibility and evolution
|
||||
|
||||
The document version and `schema_version` use semantic versioning with the
|
||||
schema's major and minor represented on the wire.
|
||||
|
||||
- Patch releases clarify prose or validation without changing accepted data.
|
||||
- Minor releases add optional fields or forms. Producers may opt in; consumers
|
||||
must not silently interpret an unknown form as a known one.
|
||||
- Major releases may rename, remove, or change field semantics and require an
|
||||
explicit migration note.
|
||||
|
||||
During the `0.x` draft period, incompatible changes remain possible but must be
|
||||
recorded in the repo changelog and accompanied by migration guidance. A
|
||||
consumer must reject an unsupported `schema_version`; it must not guess.
|
||||
|
||||
## 8. Worked example
|
||||
|
||||
`examples/qonto-assistant.yaml` is a schema-valid transformation of the King's
|
||||
Guard handover example. It demonstrates both forms and the profile-extension
|
||||
boundary. It is not the source-owned `qonto-assistant` declaration and makes no
|
||||
claim about live emission or observation.
|
||||
|
||||
## 9. Conformance
|
||||
|
||||
A producer conforms to this standard when its published declaration validates
|
||||
against the named schema and accurately identifies the source and event class
|
||||
it owns. A consumer conforms when it preserves the generic semantics, rejects
|
||||
unsupported versions and forms, and keeps observation results separate from
|
||||
the source's declaration.
|
||||
|
||||
Profile conformance is additional and is assessed by the profile owner.
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# Worked example only. qonto-assistant owns its live declaration; this file
|
||||
# makes no claim that this cadence is currently emitted or observed.
|
||||
schema_version: "0.1"
|
||||
declaration_id: qonto-assistant.audit.example
|
||||
source: qonto-assistant
|
||||
stream_id: qonto-assistant.audit
|
||||
sources:
|
||||
- source_id: qonto-assistant.audit.allow
|
||||
event_class: audit.allow
|
||||
form: expected-rate
|
||||
window: PT24H
|
||||
expected_min: 1
|
||||
drop_below: finding
|
||||
extensions:
|
||||
netkingdom:
|
||||
evidence_class: attributive
|
||||
completeness_claimed: false
|
||||
example_only: true
|
||||
- source_id: qonto-assistant.audit.deny
|
||||
event_class: audit.deny
|
||||
form: heartbeat-or-reconciliation
|
||||
heartbeat:
|
||||
event_class: audit.heartbeat
|
||||
interval: PT24H
|
||||
assertion: nothing-to-report
|
||||
missing: finding
|
||||
reconciliation:
|
||||
compare_local: source_transition_counts.audit.deny
|
||||
compare_observed: evidence_counts.audit.deny
|
||||
divergence: finding
|
||||
undrained_local: lag-not-divergence
|
||||
extensions:
|
||||
netkingdom:
|
||||
evidence_class: load-bearing
|
||||
rate_monitoring: forbidden
|
||||
completeness_claimed: true
|
||||
Loading…
Add table
Add a link
Reference in a new issue