Kinetic Trust Library

Kinetic Trust Library implements selected deterministic KTP v2.1.0 protocol primitives in Python. It returns immutable protocol values and factual results, not product instructions.

Kinetic Trust Library and Kinetic Trust Service share a major.minor compatibility series; patch releases advance independently for each component. The first paired series is 2.1: Library 2.1.0 and Service 2.1.0 can receive component-local patch releases without changing that shared series.

Package major.minor follows the implemented KTP RFC series, while package patch versions may advance independently. kinetic-trust-library==2.1.0 profiles the immutable release with KTP_SPEC_TAG == "v2.1.0" and KTP_SPEC_COMMIT == "15520035267546e1035aad7beea0cc3cf9ef8f2c". The pinned source is KTP v2.1.0, not upstream main or informative website text.

Choosing Library or Service

Kinetic Trust Library is the semantic layer. Kinetic Trust Service is an optional Python package of synchronous composition helpers built on Library; despite its name, it is not a server or daemon. There is no Service-only path: Service depends on Library and delegates KTP semantics to it.

If you are unsure, start with Library and add Service only when EvidenceHost or Issuer removes composition code you would otherwise maintain. Service is replaceable without changing KTP semantics. Neither package alone establishes application or deployment conformance, and neither is an enforcement point. A Trust Proof is not permission to perform an action.

Building a conforming KTP application

Conformance applies to a named, versioned application and its deployment, not to Library or Service by themselves. Neither package has a Basic, Standard, or Full mode, and the levels are cumulative: Standard includes Basic, and Full includes Standard. The Library contract matrix states what Library actually implements; the immutable KTP-Conformance v2.1.0 defines the controlling requirements. This table is orientation, not a complete requirements, certification, or remaining-gap checklist.

Service can reduce synchronous composition code; it does not satisfy or waive any conformance obligation. Package tests and released vectors establish only the named package behaviors. An unqualified Basic, Standard, or Full claim requires satisfying every applicable requirement and passing 100% of the required tests for that level. Under v2.1.0, documented deviations support only a clearly identified partial-compliance claim.

The tagged v2.1.0 corpus has cross-document inconsistencies affecting level boundaries, including Basic inputs and Soul, recorder chaining, proof lifetimes, Standard HSM requirements, Full post-quantum timing, and the relationship between six weighted factors and the independent Soul veto. Upstream issues #154 and #155 propose a single Core semantic contract and component-scoped conformance claims. Until those proposals are adopted in an immutable specification, an application must assess the complete v2.1.0 tag, document its interpretations, and avoid representing this summary as certification evidence.

Looking ahead (non-normative): Upstream issue #182 is an open proposal for KTP v3.0.0 ("Ostrom"), with a planned—not committed—tag date of December 10, 2026. Its proposed release set includes the still-open #154 and #155 work. The tag is intended to wait until applicable review floors clear, required pull requests are green, and required release evidence is complete. Until an immutable v3 tag exists and these projects separately review and adopt it, they remain pinned to KTP v2.1.0.

Specification scope

Exact released vectors exercised by the Library:

• spec/v2.1.0/conformance/aggregation-empty-window-v1.json
• spec/v2.1.0/conformance/ros2-reference-v0.1.json

Informative Python reference library for selected KTP v2.1.0 protocol primitives. The Library is not an official KTP SDK, a complete KTP deployment, an enforcement point, or a certification claim.

Products own sensing, storage, keys, transport, failure handling, retries, human interaction, action, and enforcement. Neither Library nor Service supplies those operational responsibilities.

Requirements and installation

The tested support set is CPython 3.11 through 3.15. The commands below use the virtual-environment support included with Python, so they do not modify a system or Homebrew-managed Python installation.

When a release appears on the PyPI project page, create a local virtual environment and install the latest available base library with:

python3 -m venv .venv
.venv/bin/python -m pip install kinetic-trust-library

Install the optional cryptography extra only when the consuming application wants the PyCA adapter supplied in the same wheel:

.venv/bin/python -m pip install 'kinetic-trust-library[cryptography]'

On Windows PowerShell, use the corresponding environment-local interpreter:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install kinetic-trust-library
.\.venv\Scripts\python.exe -m pip install "kinetic-trust-library[cryptography]"

For unreleased changes—or until the first release appears on PyPI—change into the kinetic-trust-library source-checkout root (the directory containing pyproject.toml) and replace the package name above with . or '.[cryptography]'. The dot identifies the package in the current directory, so source installation fails when run elsewhere. Activating the virtual environment is optional when invoking its interpreter directly as above.

The base installation has no third-party runtime dependencies.

validate_absolute_uri(value, *, name) exposes the bounded, value-preserving generic RFC 3986 absolute-URI syntax used by Library's KTP fields. It is scheme-neutral: it does not enforce registered URN or DID grammars, allowlist schemes, or establish whether dereferencing a URI is safe. For example, urn://a and did://a satisfy this generic syntax even if a scheme-specific consumer rejects them. Products may layer scheme-specific policy; this validator does not parse or normalize identifiers for them.

The Library returns facts and failures through Python APIs; the consuming product decides how to enforce, retry, persist, or present them.

The optional PyCA adapter is present in the same wheel but is activated only when a consumer installs the cryptography extra. The extra installs cryptography>=50.0.0,<51; it is not a dependency of the base library. KMS, HSM, and remote cryptographic services can instead implement the provider protocols without using the supplied adapter.

Run the examples

The runnable examples are available from a repository checkout or an unpacked source distribution; they are intentionally not installed in the wheel. Run them from that source root after completing the base installation above.

Examples 01–03 need only the dependency-free base installation. On macOS or Linux, run:

.venv/bin/python examples/01_core_and_envelope_evaluation.py
.venv/bin/python examples/02_fail_closed_evaluation_outcomes.py
.venv/bin/python examples/03_observations_from_application_apis.py

On Windows PowerShell, run:

.\.venv\Scripts\python.exe examples\01_core_and_envelope_evaluation.py
.\.venv\Scripts\python.exe examples\02_fail_closed_evaluation_outcomes.py
.\.venv\Scripts\python.exe examples\03_observations_from_application_apis.py

After installing the optional cryptography extra shown above, run Example 04 with:

.venv/bin/python examples/04_trust_proof_issue_and_verify.py

Or on Windows PowerShell:

.\.venv\Scripts\python.exe examples\04_trust_proof_issue_and_verify.py

See the KTP v2 examples catalogue for the paired guides. These scripts stop after displaying values computed or authenticated by the library. They do not provide application storage, transport, enforcement, or evidence of deployment-level conformance.

How the library fits into an application

application-owned APIs and evidence sources
                 |
                 v
 immutable KTP declarations and EvaluationRequest
                 |
                 v
      kinetic_trust_library.core.evaluate(...)
                 |
        +--------+--------+
        |                 |
 RejectedRequest    EvaluationBundle
                          |
              Core Capacity Result + Kinetic Envelope Result
                          |
              +-----------+-----------+
              |                       |
     optional Trust Proof       application records and
        issue/verify             enforces the real action

Deterministic Library evaluation performs no provider I/O. It evaluates values already supplied by the application. Trust Proof operations call only the signer, verifier, and trusted key source injected by the application. After the library returns, the application decides how to store results and how to enforce them.

Evaluate an action

A complete evaluation starts from product-owned declarations. The application obtains those declarations through its own APIs, then asks the library to validate and evaluate them.

from kinetic_trust_library import (
    DeploymentProfile,
    EvaluationBundle,
    EvaluationRequest,
    RejectedRequest,
    ValidatedActionDemand,
)
from kinetic_trust_library.core import evaluate

# These declarations and the UTC cutoff come from application-owned APIs.
profile = DeploymentProfile.validate(profile_declaration)
action = ValidatedActionDemand.validate(
    action_declaration,
    profile=profile,
    capability=capability_declaration,
    cutoff=cutoff,
)

# Standing, observations, and Soul responses are also application-owned facts.
request = EvaluationRequest(
    operation_id="operation:example",
    profile=profile,
    action=action,
    standing=standing_declaration,
    observations=tuple(observation_declarations),
    soul_responses=tuple(soul_response_declarations),
    cutoff=cutoff,
    previous_trust=None,  # Or the application's previous TrustSnapshot.
)

outcome = evaluate(request)

if isinstance(outcome, RejectedRequest):
    # Deterministic input validation failed. The application chooses how to
    # report, record, or otherwise handle the rejection.
    print(outcome.failed_stage, outcome.rationale)
else:
    bundle: EvaluationBundle = outcome
    if bundle.core_capacity is None:
        print("core_capacity=unevaluated")
    else:
        print(bundle.core_capacity.relation)
        print(bundle.core_capacity.within_capacity)
    envelope = bundle.envelope
    print(envelope.supervision)
    print(envelope.environmental_capacity)
    print(envelope.margin)
    print(envelope.tightened_constraints)

This is an integration skeleton rather than a toy policy. A real request must contain a complete validated Deployment Profile and action, standing facts, the observations required by that profile, and one current Soul response for each configured framework. The library deliberately does not invent missing product facts or silently turn missing evidence into measured zero.

One evaluation returns two bound facts: bundle.core_capacity is the exact KTP-Core relation, and bundle.envelope is separate Kinetic Envelope supervision and constraints. within_capacity is numerical, not permission.

Exact equality A == E_trust is AT_CAPACITY with within_capacity is True. The released zero-veto-threshold Envelope has margin == 0 and SILENT_VETO at that same equality. The released Envelope policy code KINETIC_CAPACITY_EXCEEDED is the Envelope's specified veto code, not a claim that KTP-Core equality is above capacity. The Envelope may tighten a within-capacity result but cannot weaken an above-capacity result. Products decide the operational consequence of these facts.

A Soul veto still returns an EvaluationBundle, but downstream standing, evidence, risk, trust, and velocity values are absent; core_capacity is None means unevaluated, never invented zero trust. The Envelope still returns Soul-constrained SILENT_VETO. A RejectedRequest represents deterministic request-validation failure and is not an exception. Operational exceptions from application code are allowed to propagate back to the application.

Issue and verify a Trust Proof

Trust Proof issuance requires a complete EvaluationBundle returned by evaluate() whose Soul assessment is CLEAR. The caller supplies a ProofIntent with a requested lifetime of one through ten seconds. The Library derives issuance time from the evaluation's exact whole-second UTC cutoff and tightens expiration to the whole-second end of a current or non-renewable root. A non-positive effective lifetime is rejected before provider access.

The proof derives subject and the canonical action digest from the validated evaluation, and decision_id from its operation ID. The caller supplies resource, context_hash, and trajectory_id in ProofIntent. These authenticated binding members are a Library implementation-profile extension to the unchanged, pinned KTP v2.1.0 RFC. Verification requires them, so older unbound proofs are rejected.

The following example uses an application-provided signer and trusted-key source. They may be backed by a KMS, HSM, remote service, or the optional local adapter.

from datetime import timedelta
from hashlib import sha256

from kinetic_trust_library.adapters.cryptography import cryptography_proof_crypto
from kinetic_trust_library.models.proof import ProofIntent
from kinetic_trust_library.proofs import TrustProofs

# bundle is the complete, CLEAR EvaluationBundle returned above. signer and
# trusted_key_source are application-owned provider implementations.
proofs = TrustProofs(cryptography_proof_crypto())

resource = "urn:resource:example:document-42"
context_hash = "sha256:" + sha256(b'{"environment":"example"}').hexdigest()
trajectory_id = "trajectory:example:001"
proof_intent = ProofIntent(
    proof_id="proof:example",
    resource=resource,
    context_hash=context_hash,
    trajectory_id=trajectory_id,
    lifetime_seconds=10,
)

token = proofs.issue(
    bundle,
    proof=proof_intent,
    signer=signer,
)

verified = proofs.verify(
    token.raw,
    cutoff=bundle.cutoff + timedelta(seconds=1),
    keys=trusted_key_source,
)

expected_binding = (
    bundle.action.subject,
    bundle.action.digest,
    resource,
    context_hash,
    bundle.cutoff,
    token.expires_at,
    trajectory_id,
    bundle.operation_id,
)
actual_binding = (
    verified.claims.subject,
    verified.claims.action,
    verified.claims.resource,
    verified.claims.context_hash,
    verified.claims.issued_at,
    verified.claims.expires_at,
    verified.claims.trajectory_id,
    verified.claims.decision_id,
)
if actual_binding != expected_binding:
    raise ValueError("verified proof does not bind the intended decision")
assert token.expires_at <= bundle.cutoff + timedelta(seconds=10)

print(verified.claims.issuer)
print(verified.claims.subject)
print(verified.claims.effective_trust)

The optional adapter exports ES256LocalSigner, Ed25519LocalSigner, and their native asynchronous counterparts. Applications remain responsible for loading private keys, constructing the signer's OracleSigningIdentity, and supplying trusted key lifecycle facts.

The issuer value parsed from a presented token is untrusted input. A VerificationKeySource must independently anchor trust and return a key with the correct issuer, key ID, algorithm, purpose, validity window, and revocation facts.

A VerifiedTrustProof authenticates only the claims carried by the token. It does not recreate an EvaluationBundle or KineticEnvelopeResult, and it does not authorize or enforce an action. Before using it, the application must compare the authenticated subject, action, resource, context hash, times, trajectory ID, and decision ID with the decision it intends to rely on, as in the example above.

Proof is not permission. It attests evaluated claims, including for a complete Soul-clear evaluation whose Envelope supervision is non-autonomous. It does not assert acceptance, action execution, enforcement, storage, or persistence.

For native asynchronous providers, use AsyncTrustProofs with async_cryptography_proof_crypto(), AsyncProofSigner, and AsyncVerificationKeySource. The asynchronous facade performs native awaits; it does not create hidden threads or nested event loops.

Provider interfaces and failures

Provider contracts live in kinetic_trust_library.protocols:

• ProofSigner and AsyncProofSigner sign canonical proof input;
• SignatureVerifier and AsyncSignatureVerifier verify one algorithm; and
• VerificationKeySource and AsyncVerificationKeySource resolve trusted key facts for one verification cutoff.

Providers use three explicit signals:

• ProviderUnavailable: the provider definitely did not accept the operation;
• ProviderFailure: the provider definitely produced no usable result; and
• SigningOutcomeUnknown: a signing operation may have completed externally.

The proof facade translates those signals into typed public errors. In particular, OutcomeUnknownError carries the proof ID, signing-input digest, and optional provider reference needed for application-owned reconciliation. The library does not retry, select a fallback provider, or decide whether an operation is safe to repeat.

Asynchronous read-only waits propagate native asyncio.CancelledError, including verification-key resolution, incoming signature verification, and issuance self-verification after the signer has returned an exact signature. Cancellation before signer dispatch is also native. Cancellation while a dispatched signer has no definite return raises OutcomeUnknownError instead: the external signing effect may have completed. No cancelled or outcome-unknown issuance releases a token. Native read-only cancellation lets application-owned asyncio.timeout() contexts produce TimeoutError normally.

Presented proof failures derive from InvalidProofError. Configuration and provider-operation failures derive from ProofOperationError. Invalid local declarations raise ValidationError; deterministic evaluation rejection is returned as RejectedRequest.

Public API map

Focused record and proof imports are:

from kinetic_trust_library.models.proof import ProofIntent
from kinetic_trust_library.models.record import DecisionRecord
from kinetic_trust_library.core.record import (
    build_decision_record,
    require_validated_decision_record,
)
from kinetic_trust_library.proofs import AsyncTrustProofs, TrustProofs

kinetic_trust_library.models and kinetic_trust_library.adapters are namespace-only aggregates. Proof facades, provider protocols, and Trajectory names are intentionally not exported from the package root. Import each value from its owning module as shown above.

build_decision_record(bundle) returns deterministic data for any valid evaluation, including a Soul short path; a RejectedRequest is not an evaluation and cannot produce a record. require_validated_decision_record structurally revalidates that representation. DecisionRecord uses the project-owned ktp-python-decision-record-v1 projection because KTP v2.1.0 defines no canonical Decision Geometry JSON schema. It is not the RFC Trajectory Chain transaction record and introduces no new decision semantics.

The record carries core_capacity_digest and capacity_relation, both None on a Soul short path, alongside the separate Envelope facts. The record is returned data: it does not assert persistence, proof issuance, acceptance, action, or enforcement. DecisionRecord and ProofToken remain separate, correlated by evaluation operation ID / proof decision_id. Record digests establish represented coherence, not source authenticity or completeness.

Parse Soul Constraint documents

kinetic_trust_library.soul_constraint validates an already-decoded mapping against the official KTP v2.1.0 Soul Constraint document shape:

from kinetic_trust_library.soul_constraint import parse_soul_constraint

constraint = parse_soul_constraint(
    {
        "soul": 1,
        "constraint_type": "care",
        "authority": "https://example.org/sovereignty-framework",
        "community": "Example community",
    }
)

print(constraint.soul)
print(constraint.constraint_type)
print(constraint.authority)

The result is detached and immutable. Missing optional members and explicit JSON null both project to None. Parsing does not establish that the source is authentic, that the authority is trusted, that the constraint applies to an action, or that a product must enforce it. It does not convert the document into an evaluation declaration or proof claim. JSON decoding, duplicate-member handling, transport, persistence, authority selection, and enforcement remain product responsibilities.

Service does not wrap this independent parser; products call the focused Library module directly.

Parse and assess Trajectory Transactions

kinetic_trust_library.trajectory provides official v2.1.0 semantic parsing, detached immutable values, and partial pairwise structural continuity. Parsing is not authentication: the product supplies trusted release context and owns record authentication, reporting, persistence, acceptance, recovery, and enforcement.

The official post-action Trajectory Transaction records an action and its execution outcome. It is distinct from the project-owned pre-action DecisionRecord; neither evaluation nor a veto synthesizes a Trajectory Transaction.

With two product-supplied mappings, the focused operations are:

from kinetic_trust_library.trajectory import (
    assess_trajectory_link,
    parse_trajectory_transaction,
)

previous = parse_trajectory_transaction(previous_mapping)
current = parse_trajectory_transaction(current_mapping)
findings = assess_trajectory_link(previous, current)
finding_codes = tuple(finding.value for finding in findings)

The parser is the validation boundary and raises ValidationError for malformed input. It preserves open-object extensions as owned immutable semantic data, not original JSON bytes. Obtain validated values through the parser; the ordinary frozen value constructors do not validate fields. The module exposes TrajectoryTransaction, TrajectoryAgentState, TrajectoryAction, TrajectoryOracleAttestation, and TrajectoryLinkFinding alongside the two operations, only from this focused module.

The assessor trusts parsed values and returns an ordered tuple of Library-local findings for chain identifier, sequence, supplied hash reference, timestamp order, and typed semantic state continuity. Same-chain checking and typed state equality are Library-local structural interpretations, not closed RFC comparison rules. An empty tuple establishes only these supplied-pair relations; it is not authenticity, acceptance, or deployment conformance. Hashes and signatures remain opaque exact strings.

Strict RFC 3339 calendar/range checking of both timestamp fields is a documented Library rule for safe pairwise ordering over the schema's annotation-oriented date-time format, not a requirement imposed by the schema alone. Ordinary root timestamps compare as exact UTC instants across offsets and arbitrary fractional precision, including -00:00. Conservative positive-leap syntax is accepted without an IERS occurrence table; when either root timestamp uses it, assessment returns TIMESTAMP_ORDER_UNDEFINED instead of a non-increasing-time finding.

This capability does not provide:

• genesis validation;
• canonical serialization or hash preimages;
• hash calculation or authentication;
• signature inputs or verification;
• chain persistence or append operation;
• whole-chain validation;
• record acceptance;
• retention, query, or investigation;
• Oracle/agent operation; or
• action execution or enforcement.

Physical continuity, violation response, and recovery policy also remain outside this contract. Genesis-shaped records may be parsed, but genesis is not assessed. See the maintained Library-contract matrix for focused evidence and explicit boundaries.

Library, Service, and product responsibilities

Service's EvidenceAdapter returns complete Library-owned ObservationDeclaration values through a direct synchronous evidence seam. Service's Issuer composes evaluation, record projection, and proof issuance. These are replaceable, non-normative conveniences; consumers may call Library directly without losing KTP semantics. Neither library supplies product infrastructure.

The runtime package will not provide a database, HTTP middleware, web server, daemon, background service, retry loop, approval queue, operator UI, or enforcement implementation.

Input and resource boundaries

Trust Proof parsing applies explicit protocol/profile safety caps. Evaluation has selected implementation caps, but the Library imposes no universal quota over every finite Proof of Resilience (PoR) or root history. Soul Constraint and Trajectory parsers accept already-decoded mappings; they do not inherit Trust Proof byte, nesting-depth, or string limits.

Products own ingress controls: serialized request/body size, decoder depth, collection cardinality, concurrency, deadlines, and availability policy. The Library's validation and typed failures do not replace these product controls.

Current limitations

The scope matrix above is the public implementation contract. Operational Oracle systems, key lifecycle, advanced cryptographic schemes, Flight Recorder storage, trajectory-chain operations, and deployment-level verification are outside the Library. Passing the released vectors does not certify a product. Package publication and provenance are separate from protocol and product conformance.

Contributing and security

Kinetic Trust Library is an independent implementation. It is not an official KTP SDK. NMCITRA does not certify, maintain, or endorse it.

Read CONTRIBUTING.md before proposing a change. Participation is governed by the Contributor Covenant, and suspected vulnerabilities must follow the private route in SECURITY.md. Questions that would change the KTP specification belong in official KTP Discussions, not in an implementation-only change.

Verify a checkout

Run the authoritative base suite directly from the source tree with CPython 3.11 through 3.15 and the standard library. The wrapper also runs Examples 01-03:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src .venv/bin/python \
  tools/run_required_tests.py --start-dir tests/unit --top-level-dir .

Verify that the checked-in catalogue matches the pinned KTP v2.1.0 material:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src .venv/bin/python tools/compile_catalog.py --check

After installing the optional cryptography extra, run its separate evidence lane:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src .venv/bin/python \
  tools/run_required_tests.py --start-dir tests_crypto --top-level-dir .

Run the reusable provider evidence lane separately:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src .venv/bin/python \
  tools/run_required_tests.py --start-dir tests_provider --top-level-dir .

The canonical Core and Trust Proof vectors protect protocol behavior, including exact bytes where the protocol requires them. They are not evidence of package provenance.

Project documentation

• Maintained Library-contract matrix
• Ordinary release procedure
• Project terminology