Kinetic Envelope¶

The Risk Factors describe the environment. The Envelope asks whether this particular action fits inside it.

For every action the host plane attributes to an agent, ShadowClaw computes an autonomy demand A, an environmental capacity E, and emits a receipt:

shadowclaw.ktp.envelope

autonomy_demand         0.42    what this action reaches
environmental_capacity  0.71    how well it can be seen right now
margin                  0.41
supervision             metacognitive
capacity_known          true

margin = 1 - A/E

Autonomy demand rises with five things an action can reach¶

Magnitude	Rises with
`privilege`	Privilege escalation (1.0) and identity creation (0.8) tactics; acting outside the user's own tree (0.8).
`reachability`	Public egress (0.9); a local model server (0.6).
`irreversibility`	Graded per event: `unlink` and `rename` at 1.0, launch items and profiles at 0.9, `create` at 0.7, `write` at 0.5, `exec` at 0.4, `open` at 0.1. An event with no ladder entry takes 1.0.
`credential_reach`	A credential-access tactic (1.0); a credential path touched (0.8).
`configuration_reach`	Agent-config persistence (1.0); system persistence (0.8).

Note the direction on irreversibility: an unrecognised event takes maximum, not minimum. A new event type nobody has laddered yet must not read as harmless.

Environmental capacity falls with four things that obscure it¶

Reducer	Falls with
`observation_coverage`	Lost planes. Endpoint Security down is the big one.
`attribution_confidence`	Weaker lineage. `attributed` scores 1.0, `boot_persistent` 0.4, `orphaned` 0.0, and each level of process depth costs 0.1.
`process_novelty`	An executable this host has not seen before. Up to 20,000 executables are tracked.
`adversarial_pressure`	The pass-one Risk Factor reading, carried straight in.

Supervision levels¶

Five, in order.

Level	Meaning
`stable`	Observed, attributed, unremarkable — inventory, not a finding.
`metacognitive`	Worth the agent's own attention; no human needed.
`assisted`	A human should see this before it settles.
`regulated`	This needs review now.
`silent_veto`	Demand met or exceeded capacity; the gateway should refuse.

Declared thresholds, from the shadowclaw-software-agent-v1@1 profile:

Threshold	Margin
`m_allow`	0.50
`m_metacognitive`	0.33
`m_assisted`	0.15
`m_veto`	0.00

They are a floor, not an instruction¶

ShadowClaw denies nothing

A gateway may raise its authorization tier to meet a supervision level and may never lower a tier already set. silent_veto says the gateway should refuse — the sensor emits it and stops.

Nothing derived from a receipt re-enters detection, and tests/test_ktp_envelope.py fails the build if a detection module so much as imports the envelope.

Read `capacity_known` before reading a level¶

When Endpoint Security is unavailable, the margin is not a measurement. So supervision is clamped to at least assisted however comfortable the number looks, and the receipt sets clamped to say the level was raised rather than measured.

That is the one-rule substitution again — an unknown environment reads as low capacity, not high — arriving through the decision contract instead of the stress scale.

Field	Read it as
`capacity_known: true`	The margin is a measurement. The level means what it says.
`capacity_known: false`	The margin is a bound. The level is a floor imposed by blindness.
`clamped: true`	The level was raised because capacity was unknown.
`vetoed: true`	Demand met or exceeded capacity. Evidence carries `KINETIC_CAPACITY_EXCEEDED`.

The arithmetic is deliberately not published¶

The Envelope interface defines a conformant provider by six properties and by the decisions it produces, not by a formula. Publishing the arithmetic would invite implementations that match the numbers and miss the contract.

What is declared lives in docs/ktp/declared-profile.md, and the properties are checked over the whole input grid by tests/test_ktp_envelope_properties.py.

The receipt file¶

Receipts append to ktp-envelope.jsonl beside the ledger, so they are readable with no collector in the path — exactly as Risk Factor snapshots are.

Both files carry a flat record. No nested object and no array, evidence included, because Grafana parses the line with | json, which reaches neither.

One line per action, not per poll

This file grows with agent activity rather than with uptime, so on a host running agents continuously it is the faster of the two KTP files. It does not rotate — ship it off-box or rotate it with newsyslog.

Why this is not in the ledger¶

The hash-chained events table records conclusions about processes. A per-action supervision receipt is not one. Same reasoning as the Risk Factor snapshots. See The local ledger.

Settings¶

Setting	Default	Effect
`emit_ktp_envelope`	`true`	Emit a receipt per attributed agent action.
`ktp_envelope_log`	`true`	Also append to `ktp-envelope.jsonl`.

Receipts require the host plane, so an unprivileged sensor produces few or none — and the ones it does produce carry capacity_known: false.

Next¶

Risk FactorsPass one: the environment, per poll.

The optional oracleWhat consumes a receipt.

Agent kill chainThe actions receipts are emitted for.

Event schemasEvery field on ktp.envelope.