kings-guard/specs/ImmuneContracts.md

title	document_id	version	status	date	repo	classification
Kings Guard Immune Contracts	KG-CONTRACTS-IMMUNE	0.2.0	Draft	2026-09-01	kings-guard	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/