Kinetic Trust Protocol¶

New in 1.2.0. ShadowClaw emits the KTP v2.0.0 inputs it can honestly observe, alongside everything else, on the paths telemetry already takes.

Spec version2.0.0

Risk Factors emitted4 of 6

Declared feeds11

Supervision levels5

Reporting, not deciding¶

No trust score is computed on the endpoint. No action is authorised. Nothing in the KTP package is consulted by detection. A Trust Oracle that wants these reads them; the sensor does not know one exists and holds no address for one.

That separation is enforced rather than intended. tests/test_ktp_envelope.py fails the build if a detection module so much as imports the envelope, and tests/test_ktp_zero_dependency.py fails if anything under shadowclaw/ imports a third-party module.

Two things, at two different scopes¶

Pass one

Risk Factors

The environment. Four stress terms in [0,1], emitted once per poll.

adversarial_pressure
evidence_density
trust_trend
update_resistance

One rule, which is the whole thing¶

Every Risk Factor value is a stress term: 1 is maximum stress, 0 is its absence, and anything the detector could not observe is 1.0, never 0.

That direction is not a convention, it is the safety property.

If an unobserved term read as zero, silence and calm would be the same number

A deployment could then raise its own trust score by switching sensors off. So a poll that successfully observed nothing reports 0 — a measurement — while a poll that could not look reports 1.

Endpoint Security being down does not read as a quiet machine. It reads as a machine nobody can see.

Which is ShadowClaw's own claim arriving from the other direction. The detector already refuses to let a dark plane look like a clean one, and KTP's aggregation boundary demands the same discipline one layer up.

test_a_dark_host_plane_does_not_read_as_quiet is the pin. KTP v1 shipped the opposite behaviour as defects SN-001 and SN-002.

Coverage travels with the values¶

sensor_health accompanies every snapshot, keyed per input, with feeds_active and feeds_total plus a degraded_inputs list. So a consumer can tell a factor at 1.0 because the environment is hostile from a factor at 1.0 because nothing could observe it.

That per-input form is deliberate. An aggregate fraction would destroy exactly the information that matters: two hosts each down one plane are not interchangeable, and only the per-input form can say so. See why a single coverage fraction was removed.

Two factors it will not produce¶

Factor	Why not
`moment_criticality`	Supplied by the action request, not measured.
`attestation_coverage`	Measures who is watching the deployment, not what the detector covers.

Both read like something a sensor could produce and are not, so ShadowClaw omits them and a consumer supplies them or takes 1.0. A panel expecting six series will find four; that is correct, not a gap.

Settings¶

Setting	Default	Effect
`emit_ktp_risk_factors`	`true`	Emit the four Risk Factor inputs.
`ktp_risk_factor_log`	`true`	Also append to `ktp-risk-factors.jsonl`.
`emit_ktp_envelope`	`true`	Emit a Kinetic Envelope receipt per attributed action.
`ktp_envelope_log`	`true`	Also append to `ktp-envelope.jsonl`.

Where it lands¶

Both a metric and a log event, emitted independently:

ktp.risk_factor.adversarial_pressure   0.31   gauge, [0,1]
ktp.risk_factor.evidence_density       0.08
ktp.risk_factor.trust_trend            0.25
ktp.risk_factor.update_resistance      0.17
ktp.aggregation.silent_processes       2

Independence matters because the documented route into Grafana posts straight to Loki with --no-otlp-metrics — a deployment that takes only logs still gets the values.

Snapshots also append to ktp-risk-factors.jsonl beside the ledger, and receipts to ktp-envelope.jsonl, so a consumer can read what the detector measured with no collector in the path.

Why not rows in the ledger¶

Deliberately separate files rather than rows in the hash-chained events table. That table records conclusions about processes, and a periodic environmental measurement is not one — nor is a per-action supervision receipt.

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

Neither file rotates

ktp-risk-factors.jsonl grows with uptime. ktp-envelope.jsonl grows with agent activity, so on a host running agents continuously it is the faster of the two. Ship them off-box or rotate with newsyslog.

Documentation in the repository¶

File	Contents
`docs/ktp/declared-profile.md`	The Kinetic Envelope software-agent profile v1 — demand magnitudes, capacity reducers, thresholds, and the `capacityKnown` condition.
`docs/ktp/deployment-profile.md` and `.json`	The six-factor deployment profile, with weights summing to 1.0 and mandatory placeholders.
`docs/ktp/pass-two-sketch.md`	Design notes for the Envelope provider.
`docs/ktp/upstream-notes.md` and `docs/ktp/filings/`	Three documented KTP spec defects and one contribution offer.

Next¶

Risk FactorsThe four terms, their feeds, and the dashboard rule.

Kinetic EnvelopeDemand, capacity, margin, and the supervision floor.

The optional oracleA sidecar that turns this telemetry into Trust Proofs.

Event schemasThe exact wire shape of both KTP events.