---
title: Kings Guard Immune Contracts
document_id: KG-CONTRACTS-IMMUNE
version: 0.2.0
status: Draft
date: 2026-09-01
repo: kings-guard
classification: Public
---

# Kings Guard Immune Contracts

## 1. Purpose

This document defines the first canonical contract layer for `kings-guard`.
The goal is to stabilize the shared vocabulary that adjacent systems can target
before a larger decision plane or runtime exists.

The contracts are deliberately:

- implementation-neutral;
- small enough to map from existing services and audit streams;
- explicit about producer and consumer responsibility;
- safe to adopt without granting `kings-guard` identity, authorization, or
  secret-custody authority.

The current reference implementation for these contracts lives in
`src/kings_guard/contracts.py`.

## 2. Contract Principles

### 2.1 Observation is not interpretation

An `immune_observation` is a normalized statement about a security-relevant
event or state. It should stay as close as possible to what a source system
knows directly.

Interpretation happens later through `security_phenotype`,
`posture_assessment`, and `immune_signal`.

### 2.2 Intent is explicit

Posture must be evaluated against a declared `security_genome`, not only
against statistical surprise.

### 2.3 Response stays bounded

`immune_signal` and `effector_request` may recommend or request response, but
they do not silently acquire authority owned by adjacent systems.

### 2.4 Memory is governed and is not a state plane

`immune_memory_entry` records reusable learning without becoming a raw secret
store or a place to centralize tenant-confidential payloads.

Under statute §3.4 rule 3, immune memory informs kings-guard's own judgment
and may be published as evidence. No engine, PEP, or workload may read it as
a runtime input. Making it one is a §4 Tooling catalog change, not a quiet
integration. The reference type carries
`runtime_input_for_other_layers: forbidden`.

### 2.5 Evidence class is declared, not inferred

Statute §9.6 attaches different obligations to load-bearing and attributive
evidence. The class is the **source's declaration**, recorded on the
`security_genome`'s `evidence_sources` and copied onto each
`immune_observation`. kings-guard does not infer the class from event
contents.

Obligation difference:

| Class | Cadence | Completeness |
| --- | --- | --- |
| **Load-bearing** | MUST declare a cadence. Volume classes use expected rate. Low-volume classes (revocations, denials, containment) use heartbeat or reconciliation — rate monitoring is the wrong form. | Absence of a required event, unmet cadence, missing heartbeat, or reconciliation divergence is a finding about the stream. |
| **Attributive** | SHOULD declare a cadence. Atomicity SHOULD be sought; a deliberate trade-away MUST be declared. | Completeness MUST NOT be claimed where atomicity was traded away. |

The emission-cadence declaration itself is a Taxonomy artifact (§17).
kings-guard drafts it and consumes it; it does not own it. See
`specs/EmissionCadenceDeclaration.md`.

## 3. Contract Map

| Contract | Meaning | Typical producers | Typical consumers |
| --- | --- | --- | --- |
| `security_genome` | Canonical healthy intent for a subject or compartment | workload/service owners, platform architects | posture evaluators, admission/review tooling |
| `immune_observation` | Normalized evidence record | services, audit streams, workload sensors, policy kernels | phenotype derivation, posture evaluators, memory pipelines |
| `security_phenotype` | Derived observable state at one moment | `kings-guard` adapters/evaluators, local sentinels | posture evaluators, signal emitters |
| `posture_assessment` | Risk/confidence judgment over current state | `kings-guard` evaluators | signal emitters, human reviewers, future responders |
| `immune_signal` | Typed coordination message about posture or response | `kings-guard` evaluators, local sentinels | local fast loops, owning services, State Hub, future coordinators |
| `effector_request` | Bounded action hint or request | signal emitters | owning services, policy gates, human operators |
| `tolerance` | Explicitly permitted deviation | workload/service owners, governance owners | posture evaluators |
| `inflammation` | Elevated defensive posture mode | posture evaluators, local loops | owning services, operators |
| `immune_memory_entry` | Durable, governed learning artifact | post-incident review, evaluators, future analytics | future evaluators, policy authors |

## 4. Contract Definitions

### 4.1 `security_genome`

The `security_genome` describes intended healthy operation for a subject or
compartment.

Minimum fields in v0.1:

- identity of the subject (`subject_id`, `tenant_id`);
- declared purpose;
- permitted capability scope;
- permitted protocols and egress destinations;
- data classifications;
- declared tolerances;
- declared evidence sources, each with an evidence class (load-bearing or
  attributive) and optional cadence form. The class is the source's
  declaration.

Produced by:

- workload/service owners;
- platform architects;
- future admission or deployment tooling.

Consumed by:

- `kings-guard` posture evaluators;
- future review, admission, or governance tooling.

### 4.2 `immune_observation`

The `immune_observation` is the normalized input record for posture work.

Minimum fields in v0.1:

- source system;
- timestamp;
- subject and actor identifiers;
- tenant context;
- capability or resource scope;
- protocol;
- decision/outcome;
- evidence class, copied from the source declaration;
- event class (for example `audit.deny`, `audit.allow`, `audit.heartbeat`);
- optional deny reason, identity-binding mode, egress destination, and policy
  version.

Produced by:

- service audit streams;
- workload sensors;
- local policy kernels;
- future platform/runtime sensors.

Consumed by:

- phenotype derivation;
- posture evaluation;
- future memory pipelines.

### 4.3 `security_phenotype`

The `security_phenotype` is the derived observable state of a subject at a
point in time.

In v0.1 it is intentionally small:

- observed capability;
- protocol and decision;
- active findings;
- tolerated findings.

Produced by:

- `kings-guard` evaluators or adapters.

Consumed by:

- posture assessment;
- signal emission;
- future visualization and debugging surfaces.

### 4.4 `posture_assessment`

The `posture_assessment` is the evaluator's judgment.

Minimum fields in v0.1:

- posture level (`healthy`, `elevated`, `inflamed`, `compromised`);
- risk score;
- confidence score — richness of the **record** received, never of the stream;
- stream completeness (`complete`, `degraded`, `unknown`) and a reason in
  words — an unmet cadence or missing heartbeat degrades this dimension, and
  a posture derived from an incomplete stream can never read as more
  trustworthy than one derived from a complete one;
- findings and tolerated findings;
- human-readable rationale, which must state completeness in words, not only
  as a number.

Stream findings (`stream:cadence_unmet`, `stream:heartbeat_missing`,
`stream:reconciliation_divergence`) are findings about the stream observed,
not about a record's contents. They MUST be distinguishable from content
findings such as `credential_exfil_probe`.

Produced by:

- `kings-guard` evaluators.

Consumed by:

- signal emitters;
- future human review or approval surfaces.

### 4.5 `immune_signal`

The `immune_signal` is a typed coordination message emitted after assessment.

Minimum fields in v0.1:

- signal id;
- signal kind;
- posture;
- summary;
- target system;
- findings;
- optional effector requests and metadata.

Produced by:

- `kings-guard` evaluators;
- future local sentinels.

Consumed by:

- owning services with local fast loops;
- State Hub for metadata-only evidence;
- future response coordinators.

### 4.6 `effector_request`

The `effector_request` is a bounded action request or hint attached to a
signal.

Minimum fields in v0.1:

- target system;
- action name;
- authority boundary;
- reason;
- whether human approval is required;
- originating observation identifier;
- originating signal identifier;
- stream-completeness state at emission;
- requested restrictive direction (`reduce_authority`, `require_step_up`,
  `request_containment`, or `none`).

These origin fields exist so the eventual decision record can name what the
proposal was rendered for (§9.2). They do not widen authority. A containment
proposal is not an authorization; kings-guard never actuates.

Produced by:

- `immune_signal` emitters.

Consumed by:

- the system that already owns the action;
- human operators when approval is required.

### 4.7 `tolerance`

A `tolerance` is an explicitly declared deviation that should not trigger an
inappropriate response on its own.

In v0.1 it is represented as a simple match rule:

- `match_field`;
- `match_value`;
- description;
- effect (`monitor` or `ignore`).

### 4.8 `inflammation`

`Inflammation` is not a standalone object in v0.1. It is represented as the
`inflamed` posture level plus one or more `immune_signal` / `effector_request`
records.

This keeps the first scaffold small while preserving the operating concept.

### 4.9 `immune_memory_entry`

An `immune_memory_entry` is the durable, governed output of defensive learning.

Minimum fields in v0.1:

- memory id;
- subject scope;
- summary;
- records it was derived from;
- recommended countermeasures;
- confidentiality class;
- `runtime_input_for_other_layers`, which is `forbidden`.

Produced by:

- post-incident review;
- future evaluator pipelines.

Consumed by:

- kings-guard's own later judgment;
- published evidence surfaces.

Not consumed by:

- any engine, PEP, or workload as a runtime input. That would make immune
  memory a state plane, which §3.4 rule 3 forbids unless the memory is
  catalogued as Tooling under §4.

## 5. Current Reference Slice

`kings-guard`'s first executable slice demonstrates these contracts with one
real pilot:

- service: `qonto-assistant`
- source evidence: audit event shaped from its current `AuditEvent`
- intent source: normalized genome derived from its existing security-genome
  record
- output: posture assessment and advisory-only signal with bounded effector
  requests

See:

- `docs/AdjacentSystemBoundary.md`
- `docs/pilots/QontoAssistantPosturePilot.md`
- `src/kings_guard/`