The optional oracle¶
integrations/ktp-oracle/ is a Trust Oracle sidecar that consumes ShadowClaw's KTP telemetry and issues Trust Proofs.
It is optional, versioned separately, and deletable. Remove the directory and ShadowClaw is unchanged.
Why it is separate¶
The sensor stays standard-library-only on the Python macOS ships. The oracle needs Python 3.11+ and, for signed proofs, the kinetic-trust SDK — none of which reaches the sensor.
That separation is enforced rather than intended. tests/test_ktp_zero_dependency.py fails the build if anything under shadowclaw/ imports a third-party module, checked both by walking the source and by importing the sensor in a fresh interpreter to see what actually loaded.
Install¶
cd integrations/ktp-oracle
python3.11 -m venv .venv
.venv/bin/pip install -e .
# Optional: signed Trust Proofs
.venv/bin/pip install -e '.[signing]' # kinetic-trust>=2.0.0
Run¶
| Flag | Effect |
|---|---|
--ledger PATH |
Risk Factor JSONL to read. |
--profile PATH |
Deployment profile to evaluate against. |
--issuer URI |
Trust Proof issuer identity. |
--subject URI |
Trust Proof subject identity. |
--e-base 0..100 |
Base environmental score. |
--follow |
Tail the file. |
--once |
Evaluate a single window and exit. |
--version |
Print the sidecar version. |
The deployment profile¶
docs/ktp/deployment-profile.md and deployment-profile.json declare a six-factor profile with weights summing to 1.0.
ShadowClaw supplies four of the six. The other two are substituted conservatively:
| Factor | Source |
|---|---|
adversarial_pressure |
ShadowClaw |
evidence_density |
ShadowClaw |
trust_trend |
ShadowClaw |
update_resistance |
ShadowClaw |
moment_criticality |
Substituted at 1.0 — supplied by an action request, not measured. |
attestation_coverage |
Substituted at 1.0 — measures who is watching the deployment. |
The shipped profile contains REPLACE-ME placeholders
They are mandatory deployment values — issuer, subject, and environment identity. The profile is a template, not a working configuration.
What it does not do¶
Nothing feeds back into detection. The oracle reads what the sensor wrote. There is no return path, no callback, and no address the sensor holds for it.
That is the same boundary the Envelope respects, and it exists for the same reason: a detector whose scoring can be influenced by a downstream trust decision is a detector whose findings are no longer independent evidence.
Upstream spec work¶
docs/ktp/upstream-notes.md records three documented KTP specification defects and one contribution offer, with ready-to-file issue bodies under docs/ktp/filings/:
| Filing | Subject |
|---|---|
| 01 | Hibernation threshold mismatch. |
| 02 | Obsolete factor names in the conformance v1 document. |
| 03 | Missing Hibernation tier in the trust-tier glossary. |
| 04 | Wave-two coverage contribution offer. |