pqc-reasoning-ledger

PQC-signed neurosymbolic reasoning ledger. Sign chain-of-thought steps in real time during AI inference. Produces legally defensible, quantum-safe reasoning trails for regulated industries where the reasoning chain itself must survive a decade of adversarial review.

As AI is used for high-stakes reasoning (legal analysis, medical diagnosis, financial risk, regulatory decisions), courts and regulators are asking "how did the model reach this conclusion?" This library records every step of the model's thought process as a hash-chained, Merkle-rooted, ML-DSA-65 signed reasoning trace that is tamper-evident end-to-end and verifiable by third parties without any trust in the original recorder.

Install

pip install pqc-reasoning-ledger

Quick start

from quantumshield.identity.agent import AgentIdentity
from pqc_reasoning_ledger import ReasoningRecorder, TraceVerifier

identity = AgentIdentity.create("legal-advisor-signer")
rec = ReasoningRecorder(identity)
rec.begin_trace(
    model_did="did:pqaid:gpt-legal",
    model_version="2.1",
    task="contract-review",
    domain="legal",
)

rec.record_observation("Contract contains a liquidated damages clause capping at $1M.")
rec.record_retrieval("NY CPLR 3215; Truck Rent-A-Center v. Puritan Farms 2nd (1977).")
rec.record_hypothesis("Clause is likely enforceable if sum is reasonable relative to harm.")
rec.record_deduction("Given $1M cap and projected $1.2M harm, clause is reasonable.")
rec.record_self_critique("Should also check whether plaintiff must mitigate damages.")
rec.record_decision("Recommend signing with carve-out for force-majeure events.")

sealed = rec.seal()

# External verifier, days or years later:
result = TraceVerifier.verify(sealed)
assert result.fully_verified

The sealed value is a self-contained, post-quantum-signed proof of the exact sequence of reasoning steps the model took. Altering any step, adding a step, dropping a step, reordering steps, or forging the signature will all cause TraceVerifier.verify() to return valid=False with a specific error string.

Architecture

  +---------------------+    record_*    +---------------------+
  |   Model inference   | -------------> |  ReasoningRecorder  |
  |   (chain-of-thought)|                |                     |
  +---------------------+                |  ReasoningTrace     |
                                         |   step_1  --+       |
                                         |   step_2  --+ hash  |
                                         |   step_3  --+ chain |
                                         |    ...              |
                                         +---------+-----------+
                                                   | seal()
                                                   v
                                  +----------------+-----------------+
                                  |          SealedTrace             |
                                  |  final_chain_hash                |
                                  |  merkle_root (over step_hashes)  |
                                  |  ML-DSA-65 signature             |
                                  |  signer public key               |
                                  +----------------+-----------------+
                                                   | transport / archive
                                                   v
                                  +----------------+-----------------+
                                  |  TraceVerifier (independent)     |
                                  |   1. chain integrity             |
                                  |   2. merkle root                 |
                                  |   3. ML-DSA signature            |
                                  +----------------------------------+
                                                   |
                                                   v
                                       fully_verified: True / False

Each step records SHA3-256(previous_step_hash || canonical_bytes(step)), so tampering with any intermediate step breaks every downstream hash. The merkle_root over step hashes enables selective disclosure: you can prove a single step was in the trace (e.g. "the model considered case law X") via ReasoningProver.prove_step() without revealing the other steps.

Step kinds

The symbolic vocabulary for reasoning steps (StepKind):

Cryptography

All signatures are produced via quantumshield.core.signatures.sign and verify via quantumshield.core.signatures.verify, so the verification path has no dependency on the original signer process.

Threat model

What is not in scope: confidentiality of reasoning steps (this library is about integrity, not secrecy - encrypt separately if needed), and mitigations against a compromised signer (rotate and revoke via your identity infrastructure).

API reference

ReasoningRecorder(identity: AgentIdentity)

• begin_trace(model_did, model_version, task="", actor_did="", session_id="", domain="")
• record(kind, content, references=None, confidence=1.0, metadata=None)
• record_thought(content, **kw) / record_observation / record_hypothesis / record_deduction / record_retrieval / record_tool_call / record_tool_result / record_self_critique / record_refinement / record_decision
• seal() -> SealedTrace

ReasoningTrace

• metadata: TraceMetadata, steps: list[ReasoningStep], sealed: bool
• current_hash -> str (chain-tip hash)
• append(step) - raises ChainBrokenError / TraceSealedError on violation
• to_dict() -> dict

SealedTrace

• Dataclass with metadata, steps, final_chain_hash, merkle_root, step_count, sealed_at, signer_did, algorithm, signature, public_key
• to_dict() / to_json() / from_dict() / from_json()
• canonical_bytes() -> bytes (deterministic payload that is signed)

TraceVerifier

• verify(sealed) -> VerificationResult with valid, signature_valid, chain_intact, merkle_root_valid, step_count, error, and fully_verified
• verify_or_raise(sealed) - raises SignatureVerificationError on failure

ReasoningProver

• prove_step(sealed, step_id) -> StepInclusionProof
• verify_proof(proof) -> bool

Why PQC for reasoning trails

AI liability law is accelerating. The EU AI Act, NYC Local Law 144, the FDA's AI/ML Software Pre-Cert guidance, and state-level medical and insurance rules all push toward retrospective explainability of AI decisions. A signed reasoning trace has to remain verifiable for the full litigation horizon - often 6-10+ years - which is well inside the timeline where cryptographically relevant quantum computers become a risk to classical-signature archives. ML-DSA-65 is NIST-standardized (FIPS 204) and provides integrity guarantees that outlive the archival window, without requiring re-signing the corpus under a new algorithm.

This library is ahead of the curve: the reasoning trails it produces today will still be defensible evidence when quantum-capable adversaries exist.

Examples

• examples/legal_contract_review.py - 6-step legal reasoning trace
• examples/medical_diagnosis.py - 7-step medical reasoning with inclusion proof
• examples/tamper_detection.py - demonstrate detection of a flipped byte

License

Apache 2.0 - see LICENSE.