net-kingdom/tools/emission-cadence-profile/README.md

# Emission Cadence Security Profile Checker

This checker applies the NetKingdom security overlay in
`canon/standards/emission-cadence-security-profile_v0.1.md` only after the
declaration passes an explicitly supplied InfoTechCanon contract schema.

It deliberately contains no fallback copy of the generic schema. The event
classes passed with `--load-bearing`, `--rare-load-bearing`, and
`--attributive` come from the source's authoritative inventory; the checker
does not infer them from names, payloads, or observed traffic.

## Assessment modes and results

A security-profile assessment requires at least one source-owned class
assertion. For example, to check local-identity's documented rare classes:

```bash
python3 tools/emission-cadence-profile/emission_cadence_profile.py \
  --contract-schema ../info-tech-canon/infospace/schemas/emission-cadence.schema.yaml \
  --rare-load-bearing serve/token.token_issued \
  --rare-load-bearing revoke-token \
  local-identity/emission-cadence.yaml
```

This declaration currently fails both heartbeat obligations. To intentionally
check only its structure against the imported JSON Schema:

```bash
python3 tools/emission-cadence-profile/emission_cadence_profile.py \
  --contract-schema ../info-tech-canon/infospace/schemas/emission-cadence.schema.yaml \
  --schema-only local-identity/emission-cadence.yaml
```

| Invocation/result | `contract_valid` | `profile_assessed` | `conformant` | Exit |
| --- | --- | --- | --- | --- |
| Valid schema, no inventory, default mode | true | false | null | 2 |
| Valid schema, explicit `--schema-only` | true | false | null | 0 |
| Invalid schema/declaration, either mode | false | false | null | 1 |
| Supplied inventory, profile passes | true | true | true | 0 |
| Supplied inventory, profile fails | true | true | false | 1 |

`assessment_scope` is `schema-only`, `inventory-missing`, or
`supplied-inventory`. The report includes the exact sorted `inventory`
assertions. Profile results cover only those assertions: the checker cannot
prove that the caller supplied a complete inventory or that events are emitted
and observed. `contract_valid` means JSON Schema validity, not every semantic
rule in the generic standard; duplicate source IDs are checked during profile
assessment.

`--schema-only` cannot be combined with class assertions or `--fail-on-should`.
Blank class arguments are rejected. Invalid CLI options and unreadable input
also exit 2. SHOULD findings remain advisory unless `--fail-on-should` is used.

**Compatibility:** callers that previously omitted class arguments must now
choose schema-only validation or supply an inventory. `conformant` can be null;
automation claiming profile success must require `profile_assessed == true`
and `conformant == true`, rather than merely checking for no findings or an
exit code of zero. No evidence classification is inferred from the document.

## Verification

Run its tests with:

```bash
make emission-cadence-profile-test
```

Supply `../info-tech-canon/infospace/schemas/emission-cadence.schema.yaml`
with `--contract-schema`. The canon profile records its version and SHA-256.
Security fields are under each entry's `extensions.netkingdom` namespace.

The test suite runs contract integration tests directly against a sibling
InfoTechCanon checkout; these tests explicitly skip when it is unavailable.
The small unit-test schema is a test double, not a fallback contract.

The profile is proposed: current approval-engine and qonto-assistant owner
instances still require migration. Passing a worked example is not adoption.