PivotGuard

A tamper-evident auditing layer for canonical digital state.

PivotGuard records creation and modification events as a chain of cryptographic attestations. Given the claimed state and record, an independent verifier can recompute the attestation and determine whether the state matches what was attested.

Core law: an inference may be recorded as an inference; it must not silently become a fact.

PivotGuard currently implements deterministic canonicalization, SHA-256 attestations, hash-chain continuity, verification, and an optional integrity threshold that can refuse to attest excessive declared semantic drift.

What PivotGuard does

• Canonicalizes named state channels deterministically.
• Hashes Milieu, Gravitas, and Ambience with domain separation.
• Links each accepted attestation to its predecessor.
• Recomputes attestations independently from claimed inputs.
• Returns an explicit rejection record when a declared drift metric exceeds the configured threshold.
• Uses only the Python standard library at runtime.

What PivotGuard does not claim

This release is tamper-evident, not author-authenticated. A party controlling an entire unsigned record can rebuild it. Digital signatures, trusted timestamps, persistent carrier embedding, and key management are not yet implemented.

A SHA-256 digest is not a confidentiality system. It does not expose plaintext, but low-entropy inputs may still be guessed by dictionary attack. PivotGuard also does not determine whether a semantic claim is true; its present job is to attest what state was declared and whether that declaration matches a record.

Changes are detected when they survive the documented canonicalization rules. Those rules intentionally normalize details such as dictionary key order and numeric precision.

Quick start

git clone https://github.com/PaniclandUSA/PivotGuard.git
cd PivotGuard
python -m pip install -e .
python -m unittest discover -s tests -v

from pivotguard import PivotGuardAttestor, verify_attestation

state = {
    "phi_1": 0.85,
    "phi_2": -0.30,
    "motifs": {"CARE": 0.95, "LITERACY": 0.94},
}

attestor = PivotGuardAttestor(epsilon=0.15)
record = attestor.attest_moment(
    milieu=state,
    gravitas={},
    ambience={},
    timestamp_override=1735387800,
)

result = verify_attestation(
    milieu=state,
    gravitas={},
    ambience={},
    timestamp=record.timestamp,
    attestation_hex=record.attestation.hex(),
    version=record.version,
)

assert result.ok

Tampering with a canonical value causes verification to fail:

tampered = dict(state)
tampered["phi_1"] = 0.851

result = verify_attestation(
    milieu=tampered,
    gravitas={},
    ambience={},
    timestamp=record.timestamp,
    attestation_hex=record.attestation.hex(),
)

assert not result.ok
assert result.reason == "MISMATCH"

Integrity threshold

The optional threshold compares declared input and output coordinates and adds penalties for declared conservation violations:

result = attestor.attest_moment(
    milieu=output_state,
    gravitas={},
    ambience={},
    phi_input=input_state,
    conservation_state={
        "narrative_mass_delta": 0.0,
        "emotional_energy_delta": 0.05,
    },
)

When the computed gradient exceeds epsilon, PivotGuard returns a RejectedAttestation with a zero-valued NULL_SIG. The gradient is a policy metric supplied by the application; it is not presented as universal semantic truth.

Command line

Attest a JSON object as Milieu state:

pivotguard attest state.json --timestamp 1735387800 > record.json
pivotguard verify state.json record.json

Run the built-in deterministic vector:

pivotguard self-test

Repository map

src/pivotguard/       library and CLI
tests/                deterministic unit tests and vectors
examples/             minimal use cases
docs/protocol.md      byte-level construction and canonicalization
docs/threat-model.md  guarantees, exclusions, and attack surface
docs/ethics.md        evidence-bound design doctrine

Status

v0.1.0 alpha reference implementation. Suitable for testing and integration work, not yet for claims of authorship, non-repudiation, trusted time, or adversarial record custody.

License

Apache License 2.0. See LICENSE.