Metadata-Version: 2.4
Name: consensus-hardening-protocol
Version: 0.1.0
Summary: Adversarial decision hardening for multi-agent systems — R0 gate, adversary pass, human lock, signed decision record.
Author-email: Shyam Desigan <sam@cubiczan.com>
License: MIT
Project-URL: Homepage, https://github.com/icohangar-ops/consensus-hardening-protocol
Project-URL: Specification, https://github.com/icohangar-ops/consensus-hardening-protocol/blob/main/spec/CHP-v1.0.md
Keywords: ai-agents,multi-agent,governance,decision,audit,chp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: resilience
Requires-Dist: cubiczan-resilience; extra == "resilience"
Provides-Extra: cockroachdb
Requires-Dist: sqlalchemy>=2.0; extra == "cockroachdb"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Consensus Hardening Protocol

Adversarial decision hardening for multi-agent systems. An R0 entry gate, a
mandatory adversary pass, domain-dependent score floors, a human lock, and a
signed decision record — so a high-stakes decision made by agents can be
audited after the fact.

```bash
pip install consensus-hardening-protocol
```

No required dependencies. Python 3.10+.

## What it does

An agent that is confident and wrong is more dangerous than one that is slow.
CHP puts four things in the way of a decision before it is allowed to stand:

| Stage | Rule |
|---|---|
| **R0 gate** | The session cannot open unless the problem is solvable, scoped, valid and worth doing. All four, or `HALT`. |
| **Foundation** | An adversary attacks the stated assumptions and scores the foundation. The score is gated against a floor that depends on the domain — 70 general, 85 blockchain, **100 finance**. |
| **Adversary pass** | A dedicated agent argues against the emerging decision. Its findings are recorded, not summarised away. |
| **Human lock** | A provisional lock becomes a real one only when a third party confirms it. |

Every step lands in a `DecisionCase` that serialises to a signed record, so the
question "why did we do this?" has a mechanical answer.

## Quick start

```python
from chp import CHPOrchestrator, DecisionRegistry, DecisionCase, Dossier
from chp.models import FoundationAttack, FoundationDisclosure

orch = CHPOrchestrator(registry=DecisionRegistry())

case = DecisionCase(
    decision_id="fund-tier-1",
    title="Fund the enterprise tier",
    domain="capital_allocation",   # floors at 100, not 70
    created_at="2026-08-21T10:00:00Z",
    owner="cfo",
    high_stakes=True,
    dossier=Dossier(
        core_problem="Should we fund the tier?",
        goal_state=["grow ARR"],
        current_state=["18 months runway"],
        constraints=["no new raise"],
        scope=["this fiscal year"],
    ),
)

report = orch.run_initial_session(
    case=case,
    foundation_disclosure=FoundationDisclosure(
        weakest_assumptions=["Market growth continues"],
        invalidation_conditions=["Recession"],
        key_vulnerability="Revenue concentration",
    ),
    foundation_attack=FoundationAttack(
        assumption_attacks=["Market may contract"],
        vulnerability_strike="Single customer dependency",
        foundation_score=85,
    ),
)

report.foundation_verdict   # Verdict.REFRAME — 85 is below the floor of 100
report.initial_packet       # "" — nothing is emitted on a REFRAME
```

An 85 would have passed under a 70 floor. In a capital-allocation domain it does
not, and that difference is the point of the library.

## Seed a repository

```bash
chp init                 # dry run — shows what it would write
chp init --apply         # writes .chp/
```

That drops the governance kit into `.chp/` — `R0_CONFIG.yaml`, the adversarial
prompt set, the state machine, and the compliance checklist. It never replaces an
existing file unless you pass `--force`, and it is safe to re-run.

## The specification

`spec/CHP-v1.0.md` is the normative specification. It is implementation-agnostic:
any port in any language can be checked against the golden vectors.

```bash
python spec/conformance/run_conformance.py --adapter reference
# CHP v1.0 conformance — adapter: reference
#   passed  70/70
#   result  CONFORMANT
```

Ports in other languages implement a line-JSON adapter (§7.2) and run against the
same vectors:

```bash
python spec/conformance/run_conformance.py --adapter-cmd "node my-port.js"
```

Exit status is 0 only when every selected vector passes, so this drops into CI.

## Known divergences

`spec/DIVERGENCES.md` records what a survey of six shipped implementations found,
each item cited to a file and symbol, each with a conformance vector so it fails
CI rather than sitting in a comment.

The highest-severity finding, **D-A1**, was that the canonical port hardcoded a
foundation floor of 70 for every domain, so a finance decision scoring 70 cleared
a gate documented as requiring 100. That is fixed here: `chp.foundation`
resolves the floor from the domain, matches
`spec/conformance/chp_reference.py` exactly, and a test asserts the two cannot
drift apart. A domain that merely resembles a listed one — `finance_adversary`
against `finance` — still takes the default floor per spec §5.3, but logs a
warning, because reintroducing D-A1 through naming alone is too easy.

## Optional extras

```bash
pip install "consensus-hardening-protocol[resilience]"   # full retry/timeout layer
pip install "consensus-hardening-protocol[cockroachdb]"  # distributed registry
```

Without the `resilience` extra, the package uses a dependency-free retry with
exponential backoff that honours `max_attempts` but not `timeout` — bounding an
arbitrary call without threads is not portable.

`DecisionRegistry` is in-memory by default and auto-detects a CockroachDB backend
when one is reachable. The database layer ships with the Cognitive Mesh host
rather than this package.

`chp.AdversaryMeshAgent` is an adapter for that same host. It is exported lazily,
so the package imports fine without it.

## Licence

MIT.
