kings-guard/specs/ImmuneContracts.md

title	document_id	version	status	date	repo	classification
Kings Guard Immune Contracts	KG-CONTRACTS-IMMUNE	0.1.0	Draft	2026-07-23	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

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

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.

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;
• 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;
• findings and tolerated findings;
• human-readable rationale.

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.

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.

Produced by:

• post-incident review;
• future evaluator pipelines.

Consumed by:

• future contract revisions;
• policy authors;
• future cross-run learning surfaces.

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/