Kinetic Trust Service

kinetic-trust-service 2.1.0 is a synchronous library of KTP v2.1.0 evidence and issuance composition helpers. It is not a product or a runtime service. Library owns RFC-faithful semantics and DecisionRecord; Service provides replaceable conveniences for invoking product-supplied evidence adapters and one-evaluation issuance. Consumers may call Library directly without losing KTP semantics.

This is an independently maintained composition package. It is not an official KTP SDK and is not certified, maintained, or endorsed by NMCITRA. Passing tests, package checks, vectors, or scans is evidence limited to the behavior exercised; it is not deployment or application conformance.

Choosing Library or Service

Kinetic Trust Library is the semantic layer. 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.

Install

Python 3.11 or newer is required; the routinely tested support set is CPython 3.11 through 3.15. When version 2.1.0 appears on the PyPI project page, install it in a local virtual environment; its compatible Library dependency is installed automatically:

python3 -m venv .venv
.venv/bin/python -m pip install 'kinetic-trust-service==2.1.0'

For unreleased changes—or until the first release appears on PyPI—use sibling kinetic-trust-service and kinetic-trust-library checkouts. Run from the Service checkout, installing Library first:

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

Library and Service package major.minor versions track the implemented KTP RFC series, while each package advances patch versions independently. Service 2.1.0 depends on kinetic-trust-library>=2.1.0,<2.2.0 and adds no other runtime dependencies or optional crypto dependency. Both packages remain pinned to the immutable KTP v2.1.0 specification tag; a package patch release does not imply a new KTP specification version. PyCA Cryptography is needed only when a consumer chooses Library's optional PyCA crypto adapter. The Python interpreter running the library is sufficient; no separate interpreter component is required.

Direct evidence injection

The product supplies product_declarations: a tuple of complete, product- or adapter-owned Library ObservationDeclaration values. These include source identity, sequence, class-specific measurement facts, domain, and times; see Library's declaration documentation and the declaration model. The product owns external clients, configuration, credentials, and source authenticity and completeness. Service neither creates nor repairs semantic evidence.

from datetime import datetime, timezone

from kinetic_trust_library.models.evidence import ObservationDeclaration
from kinetic_trust_service import EvidenceHost, EvidenceQuery


class ProductEvidenceAdapter:
    def __init__(
        self,
        declarations: tuple[ObservationDeclaration, ...],
    ) -> None:
        self._declarations = declarations

    @property
    def adapter_id(self) -> str:
        return "adapter:product-evidence"

    def collect(
        self,
        query: EvidenceQuery,
        /,
    ) -> tuple[ObservationDeclaration, ...]:
        return self._declarations


host = EvidenceHost((ProductEvidenceAdapter(product_declarations),))
observations = host.collect(
    EvidenceQuery(
        operation_id="operation:example:1",
        subject="urn:agent:example",
        cutoff=datetime(2026, 10, 7, 12, 0, tzinfo=timezone.utc),
    )
)

This is an integration skeleton: product_declarations must already exist. EvidenceQuery carries an operational request, not evidence. adapter_id identifies an integration and is never inferred as a declaration's source_id. EvidenceHost calls adapters in registration order and stops at the first failure, raising EvidenceAdapterError with that adapter's ID. It provides no retry, evidence repair, or source-health inference.

One-evaluation issuance

The product assembles a complete Library EvaluationRequest as request, a ProofIntent as proof_intent, and a configured Library TrustProofs facade as proofs with a caller-owned ProofSigner as signer. See Library's evaluation and proof examples. ProofIntent supplies proof ID, resource, context hash, trajectory ID, and requested lifetime; Library derives decision identity and issuance time from the evaluation and bounds expiry.

from kinetic_trust_service import (
    EvaluatedWithoutProof,
    IssuedProof,
    Issuer,
    RejectedIssuance,
)

outcome = Issuer(proofs).issue(
    request,
    proof=proof_intent,
    signer=signer,
)

if type(outcome) is RejectedIssuance:
    rejection = outcome.rejection
elif type(outcome) is EvaluatedWithoutProof:
    evaluation = outcome.evaluation
    core_capacity = evaluation.core_capacity
    envelope = evaluation.envelope
    record = outcome.record
else:
    assert type(outcome) is IssuedProof
    evaluation = outcome.evaluation
    core_capacity = evaluation.core_capacity
    envelope = evaluation.envelope
    record = outcome.record
    proof_token = outcome.proof

Issuer evaluates once. A rejected request returns RejectedIssuance without a record or proof. A valid evaluation produces Library's deterministic DecisionRecord; non-clear Soul assessments return EvaluatedWithoutProof, while Soul-clear evaluations proceed to proof issuance and return IssuedProof. Operational errors propagate to the caller, which owns recovery and retry/reconciliation.

evaluation.core_capacity (Core Capacity Result) and evaluation.envelope (Kinetic Envelope Result) are separate returned facts, not one combined decision. On the Soul short path, record.core_capacity_digest and record.capacity_relation are None.

A Soul-clear evaluation can receive a proof even when Envelope supervision is SILENT_VETO. Proof is not permission. These outcomes and returned records do not establish storage, acceptance, execution, or enforcement. The product decides whether and how to store results, recover from operational errors, enforce policy, or execute actions.

Ownership boundary

Library owns RFC-faithful KTP-Core semantics, deterministic evaluation and proof rules, and the returned DecisionRecord. Service owns only replaceable synchronous composition. The product owns source authenticity/completeness, configuration/credentials, storage/retention/transport, retry/reconciliation, observability, deployment, execution, enforcement, and human interaction.

Library provides independent Trajectory parsing and assessment; Service does not wrap it or operate a chain, and products may call Library directly.

Service provides no network server, background process, discovery mechanism, configuration system, persistence, retry loop, or action execution. See project terminology for the vocabulary and boundary.

Test a checkout

The supported checkout test installs a wheel built from the Library checkout under review; it does not add sibling Library source to PYTHONPATH:

LIBRARY_CHECKOUT=/absolute/path/to/kinetic-trust-library
WORK_DIR=$(mktemp -d)
python3 -m venv "$WORK_DIR/venv"
"$WORK_DIR/venv/bin/python" -m pip install build==1.5.0
"$WORK_DIR/venv/bin/python" -m build --wheel \
  --outdir "$WORK_DIR/library-dist" "$LIBRARY_CHECKOUT"
"$WORK_DIR/venv/bin/python" -m pip install --no-index --no-deps \
  "$WORK_DIR/library-dist/kinetic_trust_library-2.1.0-py3-none-any.whl"
PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src \
  "$WORK_DIR/venv/bin/python" -m unittest discover -s tests -t . -v

The suite does not require PyCA. Products choosing Library's optional PyCA provider install and test it separately.

Maintainers preparing a package publication must follow the PyPI release procedure.

Contributing and security

Read CONTRIBUTING.md. Community participation follows CODE_OF_CONDUCT.md. Report vulnerabilities privately as described in SECURITY.md, never in a public issue. Protocol questions belong in the official KTP Discussions area.