hypermind 1.7.0__tar.gz → 1.7.7__tar.gz

{hypermind-1.7.0 → hypermind-1.7.7}/.gitignore

@@ -43,7 +43,6 @@ TODO.private.md
 .codebase/
 .cursor/
 .vibekit/
-CLAUDE.md
 CLAUDE.local.md
 
 # -----------------------------------------------------------------------------

{hypermind-1.7.0 → hypermind-1.7.7}/CHANGELOG.md

@@ -14,6 +14,108 @@ changes only on major-version bumps.
 
 ## [Unreleased]
 
+### Fixed
+- **Gap-fix Wave 1** — mcp_tools, responders, reputation, citation_graph, tcp, anti_entropy, hypothesis, replay, evidence, topic_clustering, tool_providers, client.
+- **Gap-fix Wave 2** — loop, working_memory, evolve, orgs/sim.
+
+## [1.7.3] — 2026-07-12
+
+### Fixed
+- **Autonomous-engine Sprint 4 audit** — 10 critical integration-seam gaps closed.
+
+## [1.7.2] — 2026-07-12
+
+### Added
+- **Multi-user TCP/WebSocket MCP listener** (#601) — serves multiple concurrent MCP clients over a shared TCP/WebSocket transport.
+
+## [1.7.1] — 2026-07-12
+
+### Added
+- Revocation conformance vectors.
+
+### Fixed
+- **Autonomous-engine Sprint 3 audit** + loop test stabilisation (`load/save_loop_state` patched in loop timing tests).
+- Tickets #582–#595 — analysis, roles, pin_policy, dispute `rule_ids`, cli.
+- `hm_publish_claim` now respects `topic=` (auto-join topic room in `client.publish`).
+
+## [1.7.0] — 2026-07-12
+
+### Fixed
+- **Autonomous-engine Sprint 2 audit** — 18 gaps closed across 8 subsystems.
+
+## [1.6.9] — 2026-07-12
+
+### Fixed
+- **Full-stack autonomous-engine audit** — 21 gaps closed across 6 subsystems.
+- **Author-attribution correctness** — author identity corrected in `append_claim` / `retrieve()` (relata backend + client); attribution merge from audit agent.
+
+## [1.6.8] — 2026-07-12
+
+### Changed
+- **ruff format CI gate** fixed; format violations in `examples/` corrected.
+
+## [1.6.7] — 2026-07-12
+
+### Fixed
+- **5-gap audit** (cli, tal, responders, pin_policy) — agent list, goal submit, vouch decay, prompt caching, `compose()`.
+- `argue()` guard + lint cleanup + `__all__` sort (dispute, harness, examples).
+
+## [1.6.6] — 2026-07-12
+
+### Fixed
+- **TCP graylist pruning, FROST nonce persistence, OrgSim embedding dedup, hypothesis validation** (transport, crypto, orgs).
+- **Bounded unbounded structures + atomic FROST write** (transport, orgs, crypto).
+- 3 autonomous-engine gaps in `hm_calibration` and `hm_evolve_now` (mcp).
+
+## [1.6.5] — 2026-07-12
+
+### Fixed
+- Guard `test_issue_357` with `importorskip` — relata is not in CI `[test]` extras.
+
+## [1.6.4] — 2026-07-12
+
+### Security
+- **`oracle_resolve()` 1-of-1 quorum bypass (HM-DISPUTE-QUORUM-001)** — a single signer could satisfy the dispute resolution quorum; closed.
+- **SSRF / DNS-rebinding in `_is_safe_url`** — integrations URL-safety guard hardened.
+
+### Added
+- CLI commands: agent list, goal submit, claims list; all `HYPERMIND_*` env vars documented.
+
+### Fixed
+- Deliberator posterior merge order; `ContraClaimDisputePolicy` import resolved.
+- Autonomous-engine sprint: oracle FSM, deliberator gaps, loop calibration, missing MCP tools.
+- `HYPERMIND_LOG_ROOT` containment guard for `log_file` hooks.
+- `hm_hypothesis` wired into `HypothesisBook` lifecycle.
+- `InformationGainPlanner` removes the winning question from `working_memory` after `pick()`.
+- `from_env(sandbox=False)` — `connect_to_peer`→`connect`, `bus.start()`, TCP bus wired into world.
+- Raw `bond_topic_scope` passed to `dispute.close()` instead of SHA-256 hex.
+
+## [1.6.3] — 2026-07-12
+
+### Fixed
+- All CI failures resolved — env isolation, hook test, hybrid search stubs.
+- `hm_retrieve` SQL error; `hm_ask` Ollama model auto-detection.
+
+## [1.6.2] — 2026-07-12
+
+### Added
+- `strategy_history` wiring + full MCP tool test suite (76 tests).
+
+### Fixed
+- Autonomous-engine gaps — `GoalQueue.push()`, deliberator goals lookup, peer persistence.
+
+## [1.6.1] — 2026-07-12
+
+### Changed
+- Lint clean, coverage gate at 75%, duplicate command removed.
+
+### Fixed
+- Autonomous-engine final audit pass + verification pass — remaining critical/high gaps closed.
+- Order-dependent test failures and deprecation warnings resolved.
+
+### Docs
+- README badge counts updated for v1.6.0 (2772 tests, 52 MCP tools).
+
 ## [1.6.0] — 2026-07-11
 
 ### Added

hypermind-1.7.7/CLAUDE.md

@@ -0,0 +1,302 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`hypermind` is a Python SDK for the **HyperMind protocol** — federated agent intelligence with cryptographic chain of custody. Implements `draft-hypermind-scitt-contested-claims-profile-00` (an IETF SCITT profile that adds dispute primitives + reputation-gated registration).
+
+The repo holds two artefacts in tension:
+1. The **specification** (in `docs/spec/`, 18 normative sections) — the spec is the contract.
+2. The **reference Python SDK** (in `src/hypermind/`) — the implementation.
+
+When changes affect both, the spec is canonical. Implementation can lag the spec; spec cannot lag implementation.
+
+## Commands
+
+Activate the venv first; everything assumes Python 3.11–3.13. The repo uses Python 3.13 in `.venv/`.
+
+```bash
+# Install editable + test extras
+.venv/bin/pip install -e ".[test,dev]"
+
+# Run the full suite (always run before commit)
+.venv/bin/python -m pytest -q                                      # ~3197 passing in ~90s
+.venv/bin/python -m pytest --cov=src/hypermind --cov=src/hmctl     # coverage report
+
+# Run a single test
+.venv/bin/python -m pytest tests/test_dispute.py::test_unresolved_partition_terminal -v
+.venv/bin/python -m pytest -k "vouch_cap"                          # by name pattern
+
+# Run security regressions only (mandatory after touching crypto/wire/dispute/capability)
+.venv/bin/python -m pytest tests/test_self_heal_cycle1.py tests/test_self_heal_cycle2.py
+
+# Two-impl interop (SDK ↔ independent reference_verifier)
+.venv/bin/python -m pytest tests/test_two_impl_interop.py
+
+# Lint + format
+.venv/bin/ruff format src tests examples
+.venv/bin/ruff check src tests examples
+
+# Build the package (sdist + wheel)
+.venv/bin/python -m build
+.venv/bin/twine check dist/*
+
+# Run any example end-to-end
+.venv/bin/python -m examples.01_hello_world          # numbered tutorials
+.venv/bin/python -m examples.scenario_threat_intel   # pilot scenarios
+.venv/bin/python -m examples.full_e2e_demo           # 12-primitive demo
+
+# CLI
+.venv/bin/hmctl doctor          # smoke test
+.venv/bin/hmctl conformance     # print v0.1 conformance contract
+.venv/bin/hmctl why-blocked publish_claim    # explain a gate
+
+# SDK scenario harness (harness/)
+.venv/bin/python -m harness --list                                 # list scenarios
+.venv/bin/python -m harness --scenario threat_intel                # run canonical scenario
+.venv/bin/python -m harness --scenario threat_intel --output r.json
+
+# Parallel code review harness (review/)
+.venv/bin/python -m review src/hypermind/wire.py                   # all 4 domains
+.venv/bin/python -m review src/ --domains security,performance     # subset
+.venv/bin/python -m review src/ --output report.md                 # write markdown
+```
+
+## Architecture — the parts that matter
+
+### The wire format is the contract
+
+`src/hypermind/wire.py` defines `SignedStatement` — the COSE_Sign1 envelope every claim, dispute, and receipt rides in. **A-ALG-BOUND** is the load-bearing security property: every discriminator (`record_type`, `namespace_id`, `hlc`, `wire_version`, `signature_alg`, `envelope_schema_hash`, `pq_required`) MUST be in the protected header *and* re-encoding under canonical CBOR must equal the wire bytes. `from_bytes()` enforces this **before** signature verification — closes the JWT-`alg=none` substitution class.
+
+The independent `reference_verifier/` package (no SDK imports) re-implements verification from spec text. `tests/test_two_impl_interop.py` proves both implementations agree on every wire-format property. **Never weaken either side without updating the other.**
+
+### The agent class is the user-facing surface
+
+`HyperMindAgent` in `src/hypermind/agent.py` is the centerpiece. Key design rules:
+
+- **Async-first.** Every public verb is `async def`. Sync wrappers live in `hypermind.sync` (`SyncAgent`) for callers that can't use `await`.
+- **Three factories, three meanings:**
+  - `HyperMindAgent.sandbox()` — single agent (most common starter).
+  - `HyperMindAgent.testbed(n)` — list of N pre-vouched agents sharing a world.
+  - `testbed_cohort(n)` — async-with that yields N agents and cleans them up.
+  - `HyperMindAgent.from_env(sandbox=True)` — production entry point (currently delegates to sandbox; libp2p backend in v0.2).
+- **The `_NamespaceWorld`** (private) holds the shared bus, transparency service, reputation kernel, and registry of agents in a sandbox. It is the in-process stand-in for "the federation."
+
+### Crypto layer
+
+`src/hypermind/crypto/` is pure spec implementation:
+
+- `signing.py` — Ed25519 (PyNaCl) + Ed25519+ML-DSA-65 composite (quantcrypt). The `kid` is always the 32-byte Ed25519 public-key half so addresses survive v0.1 → v0.2 algorithm upgrade.
+- `frost.py` — RFC 9591 FROST k-of-n threshold Schnorr. **Two correctness gotchas**: nonces are *hedged-random* (RFC 9591 §4.2 — deterministic PRF mixed with fresh 32-byte `secrets.token_bytes(32)` per session, so restart cannot reopen the nonce-reuse window); the bounded `_SEEN_TRANSCRIPTS` LRU is the second-line Drijvers defence. Tests use the `reset_seen_transcripts` fixture in `conftest.py` so test order doesn't matter.
+- `hlc.py` — Hybrid Logical Clock; `merge()` clamps + rejects beyond `2 * HLC_MAX_SKEW_MS`. Used as a causal-order discriminator; numeric `(logical_ms, counter)` parsing for `audit_export(since_hlc=…)` lives in `agent._parse_hlc_for_filter`.
+- `domain.py` — domain-separation tags (the WF-DOMAIN refinement lemma). Every cryptographic operation prefixes its preimage with a single byte tag from this enum.
+
+### Knowledge layer
+
+`src/hypermind/knowledge/`:
+- `transparency.py` — RFC 6962 Merkle (pymerkle) with witness cosigning over `(root, tree_size)`. **Always use `append_and_cosign()`** — the standalone `witness_cosign()` is a footgun if anything appends between calls.
+- `reputation.py` — Beta-posterior per-(agent, topic). Smooth slashing (λ=0.02), lazy decay (H_T=180d). **`vouch()` cap**: contribution bounded at 5% of voucher's α-above-prior, NOT 5% of the vouchee's α (a previous bug had it backwards).
+
+### Mind layer
+
+`src/hypermind/mind/` is the deliberation and swarm-intelligence layer added in v0.10. Spec: `docs/spec/20-swarm-intelligence.md`.
+
+- `deliberator.py` — `Deliberator` bound to a single agent; owns a `GoalQueue` and list of `ActionPolicy` instances. Turns goals into actions via an async loop.
+- `roles.py` — Declarative role bundles (Scout, Sceptic, Generalist, Synthesist, Mediator, Oracle). Assigning a role to an agent is the fastest path to a differentiated swarm; roles compose with the existing CapToken chain.
+- `active.py` — Information-gain planning, curriculum scheduling, anti-herding. Picks the *next best question* to ask the swarm (spec §20.3).
+- `world_model.py` — Per-agent world-state snapshot used by the deliberator for goal evaluation.
+- `sybil_guard.py` — Detects Sybil clusters before swarm votes are tallied.
+- `diversity.py` — EIG/Q metrics and active-selection scoring for the swarm IQ scorecard.
+- `federation.py`, `mediator.py`, `policy.py`, `goals.py`, `records.py`, `evolve.py`, `integration.py` — Supporting primitives for federated deliberation, mediation, and policy evolution.
+
+### The `hypermind.orgs` deep-research engine
+
+The living-simulation + research engine (spec: `docs/spec/20-swarm-intelligence.md`). `OrgSim` in `orgs/sim.py` is the loop (`research → publish → cite → dispute → resolve → learn → evolve`); the rest are composable layers:
+
+- `charter.py` / `prompts.py` — a PI agent **decomposes** a question into expert `Seat`s (role/persona/tools/angle/strategy); `refine.py` (`plan_and_refine`, `score_plan`) re-plans until the decomposition scores well **before** the sim runs.
+- `strategies.py` — 12 pluggable **reasoning frameworks** (TRIZ, first-principles, morphological, FMEA, pre-mortem, dialectic, Bayesian, …); `strategy` is first-class on `Seat`, injected into the system prompt.
+- `hypothesis.py` — `HypothesisBook`: each finding is a **falsifiable hypothesis** kept in memory; citation corroborates, dispute disconfirms, oracle resolves → status `open → contested → supported/refuted`.
+- `analysis.py` — architecture-native metrics (`full_analysis`): **verifiable** (Merkle + tamper demo), **attributable** (reputation/roles), **contestable** (dispute survival), **grounded** (knowledge split + source-faithfulness vs retained raw evidence).
+- `evidence.py` — parses raw tool output into de-duplicated, corroboration-ranked **citations**; `_retrieve` grounds on real sources. Full raw output + untruncated reasoning are retained (bounded copies feed the LLM; env: `HYPERMIND_TOOL_RESULT_LLM_CHARS`, `HYPERMIND_CONTEXT_FINDING_CHARS`).
+- `replay.py` — `export_jsonl` dumps every record (signed claims as wire bytes + disputes/reputation/evidence/hypotheses); `replay_to_relata` re-inserts a run **without re-running the LLM work**.
+- `sim.stream()` / `select_experts()` — streaming **tools-off** query over learned knowledge; consults a panel ranked by relevance × earned reputation; `model=`/`client=` enable **learn-large / serve-small**.
+- `tool_providers.py` / `mcp_config.py` — per-cycle tool gateway + MCP auto-discovery. `distributed/` — TCP master/worker for horizontal scale. `templates/` — preset org factories.
+- **Storage**: real `RelataBackend` (typed HmClaim/HmDispute/HmReputation) + `RelataMemoryStore` (evidence + hypotheses). Provision the Hm types once (admin token) — see `deploy/relata-serve.sh`. Multi-node federation is real over `transport/tcp.py::TCPGossipBus`.
+
+### Other production modules
+
+- `src/hypermind/sync.py` — `SyncAgent`: thin synchronous wrapper around every `async def` public verb. For notebooks and CLIs that can't use `await`.
+- `src/hypermind/revocation.py` — `RevocationList` (CRL-shape). Federation-root operator publishes a signed list; `from_bytes()` / `verify()` pattern mirrors `wire.py`. Spec: `docs/spec/12-revocation.md`.
+- `src/hypermind/tal.py` — Trust & Access Layer: reputation-gated Rooms with per-Room minimum reputation, vouch decay (HLC-timestamped). Spec: `docs/spec/07-trust-access-layer.md`.
+- `src/hypermind/responders/` — Pluggable model backends for consult panels: `openai.py`, `anthropic.py`, `structured.py`, `router.py`. `ResponderRouter` dispatches per-panel-member to the right backend.
+- `src/hypermind/pin_policy.py` — Pin/unpin policies for namespace claims.
+- `src/hypermind/consult_bias.py` / `uncertainty.py` — Bias detection and uncertainty quantification hooks for consult results.
+
+### Transport layer
+
+`src/hypermind/transport/`:
+- `bus.py` — `GossipBus` Protocol + `InProcessBus` for sandboxes.
+- `tcp.py` — production-grade TCP with mutual identity-bound handshake. **The `_seen` cache is an LRU bounded at `SEEN_CACHE_MAX=16384`** — never replace with an unbounded set. Duplicate-kid connections must be rejected (not overwrite the existing peer).
+- `anti_entropy.py` — Bloom set reconciliation. `from_cbor()` must reject oversized `m`/`k` (DoS gate).
+
+### Dispute FSM
+
+`src/hypermind/dispute.py`. State machine: `OPEN → ARGUE → COUNTER → CLOSED | FRIVOLOUS` with `UNRESOLVED_PARTITION` as the terminal heal-merge fallback. Bonds are **topic-scoped** (`TAL-ESCROW-EXCLUSIVE`) — `close()` rejects when the topic_scope_hash doesn't match. **Never weaken this**: it's the headline-killer security property.
+
+### Capability tokens
+
+`src/hypermind/capability.py`. Biscuit-shape caveat chain with three security invariants:
+1. Only the current `subject` may attenuate (signing_keypair.kid must equal self.subject).
+2. Each attenuation carries `parent_sig` = SHA-256 hash of parent's body+sig.
+3. `verify_chain()` calls `self.verify()` first — never trust a token that hasn't validated its own signature.
+
+`Caveat.__post_init__` validates the `kind` against the closed set — silent typos (`Caveat("topik", ...)`) are now `ValueError`. Use `Caveat.topic(...)`, `Caveat.rate(...)`, etc. constructors to avoid hand-typing.
+
+### SDK scenario harness (`harness/`)
+
+A test orchestration layer that runs multi-agent HyperMind workflows with structured assertions. **Separate from `tests/` — it exercises real SDK paths end-to-end.**
+
+Key design:
+- `HarnessScenario` (ABC) — subclass with `role_specs()` + `run()`. Call `self._step(name, coro, assertions=[...], kids_emitted=kids_list)` for each logical step. `kids_emitted` / `dispute_kids` are **mutable lists passed by reference** — populate them inside the coroutine before assertions evaluate.
+- `HarnessRunner` — accepts a `RunConfig`, spins up agents via `testbed_cohort`, injects `scenario.recorder` as the **world-scoped recorder** (not `get_recorder()`), collects `DisputeOutcome` and `ReputationDelta` post-run.
+- `assertions.py` — 15 built-in hooks (`assert_kid_in_sealed`, `assert_dispute_state`, `assert_rep_increased`, `assert_event_emitted`, etc.) plus `all_of`/`any_of` combinators. All hooks are pure functions over a frozen `AssertionContext` snapshot taken post-coroutine.
+- `harness/scenarios/threat_intel.py` — canonical 4-step scenario (publish → dispute → oracle resolve → audit). Use as the reference pattern for new scenarios.
+
+### Parallel code review harness (`review/`)
+
+Runs four focused Claude sub-agents in parallel (architecture, security, performance, style) against source files and merges findings into a `ReviewReport`.
+
+Key design:
+- Each domain agent is a `claude --print --bare --allowedTools Glob,Grep,Read` subprocess with a focused, domain-exclusive prompt. Agents must return a ` ```json ``` ` block; malformed output degrades to an INFO finding.
+- `ReviewRunner.run()` uses `asyncio.gather` — all four agents start simultaneously.
+- `ReviewReport.findings` deduplicates by `(domain, file, line, title[:60])` and sorts by severity rank (critical → info).
+- Exit code from `python -m review` is `0` only when there are no critical or high findings.
+
+## Spec ↔ implementation discipline
+
+Every spec section in `docs/spec/` carries a banner: **Inherit** (from existing standards), **Extend** (HyperMind contributes a profile), or **Original** (HyperMind-original). Keep this classification accurate when you change spec text — it drives the standards-map in `docs/_meta/standards-map.md`.
+
+The `docs/expert-panel/` directory is `.gitignore`'d — it holds working notes from review cycles. **Do not add public-facing references to it.** The roadmap is in [`ROADMAP.md`](ROADMAP.md) at the project root.
+
+## Security-relevant change protocol
+
+If a change touches any of these files, the PR is automatically `security`-tagged and requires two-maintainer review:
+
+- `src/hypermind/wire.py`
+- `src/hypermind/crypto/`
+- `src/hypermind/capability.py`
+- `src/hypermind/dispute.py`
+- `src/hypermind/knowledge/transparency.py`
+- `src/hypermind/transport/tcp.py` (peer identity handshake, anti-DoS caches, graylist)
+
+For these PRs:
+1. Add at least one positive test (the new property holds when used correctly).
+2. Add at least one negative test (an attacker cannot bypass the property).
+3. Pin the regression in `tests/test_self_heal_cycleN.py` if it closes a known finding.
+
+The `tests/test_self_heal_cycle1.py` and `tests/test_self_heal_cycle2.py` files pin specific vulnerability fixes. Never delete or weaken them without a written rationale on the PR.
+
+## Testing patterns
+
+- **Coverage gate**: 95% locally, 99% in release CI. Coverage cannot drop on a PR.
+- **No timing-based test theatre**: tests that use `await asyncio.sleep(0.05)` to wait for delivery are flagged as flaky. Use `asyncio.Event` patterns instead.
+- **No coverage-by-mutation tests**: `object.__setattr__` to reach a defensive line means the production path that reaches that line is untested. Drive the branch via real input.
+- **Test isolation**: `conftest.py` resets the global `Recorder` and FROST `_SEEN_TRANSCRIPTS` between tests. Tests can rely on a clean slate. `tests/harness/conftest.py` extends these with harness fixtures; `tests/review/` tests mock `run_domain_agent` to avoid live subprocess calls.
+
+## Examples are documentation
+
+`examples/` is treated as user-facing documentation. The numbered tutorials run `01` through `29` (note: `15` is absent in the current tree); each opens with a **THE STORY** docstring before any code. `examples/README.md` is the index — keep it in sync when adding/removing files.
+
+Tutorial clusters:
+- **01–09**: Core protocol primitives (hello world → dispute → consult → oracle → synthesis → hybrid-PQ → FROST → ramp/diagnostics → audit export).
+- **10–14**: Swarm intelligence (autonomous agent, swarm deliberation, IQ scorecard, role specialisation, active learning loop).
+- **16–21**: Wire & governance (wire message, tool delegation, custom responder, governance, conformance check, revocation).
+- **22–25**: Interop & tracing (agent card, task delegation, MCP tool call, swarm trace).
+- **26–27**: Mind layer — goals and safety (submit_goal + GoalHandle, safety policy stack: SybilGuard, DiversityGuard, AntiHerdingPolicy).
+- **28–29**: Storage and simulation quick-starts (Relata connection, zero-dependency sandbox research sim).
+
+The scenarios divide into three groups:
+
+- **Pilot-shaped demonstrations**: `scenario_threat_intel.py`, `scenario_namespace_trust.py`, `scenario_information_pipeline.py`.
+- **Federated-learning, community, and namespace mechanics** (the "how do agents actually learn from each other" gap):
+  - `scenario_vouch_chain.py` — newcomer → vouched → established → voucher; the 5%-of-α vouch cap.
+  - `scenario_learning_loop.py` — `working_memory` → `checkpoint()` → peers cite → outcomes reward the cited author.
+  - `scenario_cross_namespace_federation.py` — bridge-mediated federated consult; foreign reputation is *displayed* in the synthesis payload, never silently merged.
+- **Security mechanics & dispute lifecycle**:
+  - `scenario_capability_attenuation.py` — CapToken mint → attenuate → authorize, with all 3 negative tests (wrong signer, widening rejected, out-of-scope rejected).
+  - `scenario_dispute_lifecycle_async.py` — `on_dispute(callback)` vs. `next_dispute(timeout)`; FSM driven OPEN → ARGUE → COUNTER → CLOSED.
+
+The `08_ramp_and_diagnostics.py` tutorial is the canonical reference for the structured-refusal contract: `why_blocked()` returns a `BlockReason` whose `rule_id` is the stable programmatic key (e.g. `ADMIT-RAMP-INCOMPLETE`). Test code keys off `rule_id`, never the human message.
+
+When changing a public verb, check that every example in `examples/` still runs end-to-end. CI does not yet enforce this — run them locally. The `consult → synthesize` chain (`05_consult_to_synthesis.py`) is the canonical exercise of the federated-learning loop and should never regress.
+
+## Active milestone
+
+As of 2026-07-12, the SDK is at **1.7.3** on the **engineering GA** line (engineering GA shipped 2026-07-09 as 1.0.0; SemVer is binding on the 1.x line). The protocol core, the full swarm-intelligence / mind layer, and the `hypermind.orgs` deep-research engine (decomposition + self-refine, reasoning strategies, hypothesis lifecycle, architecture-native metrics, evidence retention + citations, streaming query, full-run replay, real Relata ledger + TCP federation) have all landed. Remaining gates are **ecosystem, not code** — IETF I-D submission, IANA early-allocation, OpenSSF Sandbox/Incubating acceptance, third-party security audit, full Tamarin/ProVerif proofs, NLnet/Alpha-Omega awards, ≥2 non-ZySec maintainers, ≥3 pilot MOUs, 7-day chaos-test green run, side-channel CT 30d-green. See [ROADMAP.md](ROADMAP.md) for item-numbered status.
+
+When working in this codebase, treat GA as "ship-quality, tests cover it, docs reference it" — not "audited / foundation-accepted." The real libp2p Rust shim (an *optional* backend; TCP federation is the shipped real transport) and foundation acceptance are out-of-scope for engineering changes. (Cloud-KMS signing was removed in 1.0.0 — `LocalSigner` is the shipped backend; a custom `Signer` can be supplied for HSM/KMS.)
+
+<!-- codebase:start -->
+## Project Context (auto-generated by codebase)
+
+**Contents:** [Session Start](#session-start) · [Commands](#commands) · [Rules](#rules)
+
+**hypermind** — Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile
+**Stack:** python, markdown, json, yaml, toml
+
+### Project Commands
+| Task | Command |
+|---|---|
+| `test` | `make test` |
+| `lint` | `make lint` |
+| `format` | `make fmt` |
+
+**This project uses `codebase` for AI context. Run commands below instead of exploring files.**
+
+### Session Start
+```
+npx codebase brief
+```
+Returns: project identity, tech stack, commands, structure, current status, next task, blockers, decisions — everything you need in one call.
+
+### Commands (your interface — use these, don't read files)
+| Command | What it returns |
+|---|---|
+| `npx codebase brief` | Full project briefing — **run this first** |
+| `npx codebase next` | Highest-priority task + what's in progress |
+| `npx codebase status` | Kanban board, priorities, milestones |
+| `npx codebase query <path>` | Any data point (e.g. `stack.languages`, `commands.test`) |
+| `npx codebase query stack.languages` | example dot-path query |
+| `npx codebase issue create "title"` | Track a bug, feature, or TODO |
+| `npx codebase issue close <n> --comment "why"` | Close an issue after fixing it |
+| `npx codebase handoff` | Generate HANDOFF.md — session transfer for next agent |
+| `npx codebase tokens` | Show token budget report for this project |
+
+### Maintenance
+| Command | What it does |
+|---|---|
+| `codebase doctor` | Health check — diagnose broken setup |
+| `codebase fix` | Auto-repair issues found by doctor |
+| `codebase skills` | List installed skills and their capabilities |
+
+### Rules
+- **Never explore the codebase to discover stack/commands/structure** — it's already in `brief`
+- **Check `next` before starting work** — don't duplicate in-progress tasks
+- **Create issues for bugs/TODOs you find** — keep the project brain alive
+- **Close issues when you fix them** — with a reason so the team knows why
+- **If any command fails, run `codebase doctor` then `codebase fix`** — self-heal before asking for help
+
+### Workflow Tips
+- **Subagents for isolation**: use Task tool for large refactors — keeps main session clean
+- **Session hygiene**: keep sessions focused; start fresh rather than pushing through context limits
+- **Commit often**: detailed commit messages serve as memory between sessions
+- **End of session**: run `codebase handoff` before closing to save state for the next agent
+- **Model selection**: Opus for architecture/security decisions; Sonnet for implementation/iteration
+- **Rewind mistakes**: ESC ESC after a bad edit — reverts and lets you try a different approach
+
+### Where to Find More
+- Vibekit loop: see `.claude/commands/` for /simulate, /build, /launch
+- MCP tools: call `list_commands` or `list_skills` via MCP server
+- Browser automation: see `~/.claude/skills/simulate.skill`
+<!-- codebase:end -->

{hypermind-1.7.0 → hypermind-1.7.7}/CONTRIBUTING.md

@@ -38,7 +38,7 @@ python3.13 -m venv .venv             # 3.11–3.13 supported
 Verify the suite passes before touching anything:
 
 ```bash
-.venv/bin/python -m pytest -q                                   # 740 passing in ~10s
+.venv/bin/python -m pytest -q                                   # ~3197 passing in ~90s
 .venv/bin/python -m pytest --cov=src/hypermind --cov=src/hmctl  # ≥95% coverage
 .venv/bin/python -m examples.01_hello_world                     # end-to-end demo
 ```
@@ -63,7 +63,7 @@ classification accurate when you change spec text.
 
 - **Python 3.11+** (we test against 3.11, 3.12, 3.13 in CI)
 - **Async-first** for I/O; sync wrappers belong in `hypermind.sync`.
-- **Type-annotate everything** — the project is mypy-clean (`mypy --strict`).
+- **Type-annotate everything** — `mypy` is run on `src/hypermind src/hmctl`; aim for it to pass, but note the `make typecheck` gate is currently advisory (allow-error) during the 1.x run-in.
 - **Format with `ruff`**. Run `ruff format src tests examples` before committing.
 - **Lint with `ruff check`** — fix all reported issues unless they're explicitly
   whitelisted in `pyproject.toml`.
@@ -113,7 +113,7 @@ PR checklist (the template will remind you):
 
 - [ ] Tests added/updated for the change
 - [ ] Coverage ≥ 95% (run with `--cov-fail-under=95`)
-- [ ] No regressions: `pytest tests/test_self_heal_cycle1.py tests/test_self_heal_cycle2.py` passes
+- [ ] No regressions: `pytest tests/test_self_heal_cycle1.py tests/test_self_heal_cycle2.py` passes (self-heal cycles now run 1–5; see `tests/test_self_heal_*.py`)
 - [ ] Demos in `examples/` still run (`python -m examples.01_hello_world` etc.)
 - [ ] Docs updated if the public API changed
 - [ ] CHANGELOG entry under `## [Unreleased]`
@@ -130,6 +130,7 @@ If your PR touches any of:
 - `src/hypermind/capability.py` (caveat chain, attenuation)
 - `src/hypermind/dispute.py` (FSM transitions, bond scoping)
 - `src/hypermind/knowledge/transparency.py` (Merkle tree, witness cosigning)
+- `src/hypermind/transport/tcp.py` (peer identity handshake, anti-DoS caches, graylist)
 
 …then please:
 

{hypermind-1.7.0 → hypermind-1.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 1.7.0
+Version: 1.7.7
 Summary: Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile
 Project-URL: Homepage, https://github.com/ZySec-AI/hypermind
 Project-URL: Documentation, https://github.com/ZySec-AI/hypermind/tree/main/docs
@@ -10,7 +10,7 @@ Author: HyperMind contributors
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: agents,cose,dispute,federated,intelligence,p2p,scitt
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.11
@@ -25,10 +25,12 @@ Requires-Dist: blake3>=0.4
 Requires-Dist: cbor2>=6.0.1
 Requires-Dist: click>=8.1
 Requires-Dist: cryptography>=44.0.1
+Requires-Dist: openai<2,>=1.50
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pymerkle>=6.1
 Requires-Dist: pynacl>=1.6.2
 Requires-Dist: quantcrypt>=1.0
+Requires-Dist: relata-sdk>=0.2
 Requires-Dist: rich>=13.7
 Requires-Dist: structlog>=24.1
 Provides-Extra: anthropic
@@ -55,19 +57,19 @@ Requires-Dist: mcp>=1.0; extra == 'mcp'
 Provides-Extra: migrate
 Requires-Dist: libcst>=1.1; extra == 'migrate'
 Provides-Extra: openai
-Requires-Dist: openai<2,>=1.50; extra == 'openai'
 Provides-Extra: otel
 Requires-Dist: opentelemetry-api>=1.22; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.22; extra == 'otel'
 Requires-Dist: prometheus-client>=0.20; extra == 'otel'
 Provides-Extra: relata
-Requires-Dist: relata-sdk>=0.2; extra == 'relata'
 Provides-Extra: test
 Requires-Dist: httpx>=0.27; extra == 'test'
 Requires-Dist: hypothesis>=6.100; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
 Requires-Dist: pytest-cov>=4.1; extra == 'test'
 Requires-Dist: pytest>=7.4; extra == 'test'
+Provides-Extra: websockets
+Requires-Dist: websockets>=12.0; extra == 'websockets'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -84,8 +86,8 @@ Agents share what they learn, dispute what they doubt, and build reputation over
 [![PyPI](https://img.shields.io/pypi/v/hypermind?color=4c8cff&label=pip%20install%20hypermind)](https://pypi.org/project/hypermind/)
 [![Python](https://img.shields.io/pypi/pyversions/hypermind?color=4c8cff)](https://pypi.org/project/hypermind/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-2772-brightgreen)](#status)
-[![Version](https://img.shields.io/badge/version-1.6.0-blue)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-3197-brightgreen)](#status)
+[![Version](https://img.shields.io/badge/version-1.7.3-blue)](CHANGELOG.md)
 
 **[Quickstart](#quickstart-30-seconds)** ·
 **[MCP tools](#mcp-tools-52-tools)** ·
@@ -137,7 +139,7 @@ Native adapters: **LangChain** · **CrewAI** · **AutoGen** · **LlamaIndex** ·
 
 ---
 
-## MCP tools (52 tools)
+## MCP tools (57 tools)
 
 Every tool below is available when you run `hmctl mcp install`. Read-only by default;
 `hm_publish_claim` requires `--write` (53 tools total in write mode).
@@ -316,7 +318,7 @@ ledger, and loads a default population — no API key, no internet.
 ```bash
 hmctl quickstart                       # zero-to-verifiable swarm, no config
 hmctl init my-app                      # scaffold a starter project
-hmctl mcp install                      # wire into Claude Desktop / Cursor (52 tools)
+hmctl mcp install                      # wire into Claude Desktop / Cursor (57 tools)
 hmctl mcp install --local              # fully offline (Ollama + SQLite, no API key)
 hmctl serve-endpoint                   # OpenAI-compatible endpoint on :8899
 hmctl ingest notes.md --topic research # ingest documents into the swarm
@@ -356,17 +358,17 @@ hmctl status      # shows which features are active
 
 ## Status
 
-**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **1.6.0**.
+**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **1.7.3**.
 Remaining gates are **ecosystem, not code** (see [ROADMAP.md](ROADMAP.md) §External).
 
 - **Protocol** — 30 numbered spec sections (§01–§30, §21 split) + independent [`reference_verifier/`](reference_verifier/) proving two-impl interop
-- **SDK** — async-first, fully type-hinted, **2772 tests**; hybrid PQ signing, FROST k-of-n, dispute FSM (incl. `SUSPENDED`), capability tokens, RFC 6962 transparency
-- **52 MCP tools** — knowledge & retrieval, what-if simulation, adversarial debate, goal planning, hypothesis tracking, ingest, dataset export, population management, eval suite
+- **SDK** — async-first, fully type-hinted, **3197 tests**; hybrid PQ signing, FROST k-of-n, dispute FSM (incl. `SUSPENDED`), capability tokens, RFC 6962 transparency
+- **57 MCP tools** — knowledge & retrieval, what-if simulation, adversarial debate, goal planning, hypothesis tracking, ingest, dataset export, population management, eval suite
 - **Federation** — real multi-node TCP gossip (`TCPGossipBus`); `libp2p` is an optional external Rust binding
 - **SimLab web UI** at `make run`
 
 ```bash
-make test        # 2772 tests, ~90s
+make test        # 3197 tests, ~90s
 make lint        # ruff check + format
 make run         # SimLab web UI on http://127.0.0.1:8765
 ```

{hypermind-1.7.0 → hypermind-1.7.7}/README.md

@@ -12,8 +12,8 @@ Agents share what they learn, dispute what they doubt, and build reputation over
 [![PyPI](https://img.shields.io/pypi/v/hypermind?color=4c8cff&label=pip%20install%20hypermind)](https://pypi.org/project/hypermind/)
 [![Python](https://img.shields.io/pypi/pyversions/hypermind?color=4c8cff)](https://pypi.org/project/hypermind/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-2772-brightgreen)](#status)
-[![Version](https://img.shields.io/badge/version-1.6.0-blue)](CHANGELOG.md)
+[![Tests](https://img.shields.io/badge/tests-3197-brightgreen)](#status)
+[![Version](https://img.shields.io/badge/version-1.7.3-blue)](CHANGELOG.md)
 
 **[Quickstart](#quickstart-30-seconds)** ·
 **[MCP tools](#mcp-tools-52-tools)** ·
@@ -65,7 +65,7 @@ Native adapters: **LangChain** · **CrewAI** · **AutoGen** · **LlamaIndex** ·
 
 ---
 
-## MCP tools (52 tools)
+## MCP tools (57 tools)
 
 Every tool below is available when you run `hmctl mcp install`. Read-only by default;
 `hm_publish_claim` requires `--write` (53 tools total in write mode).
@@ -244,7 +244,7 @@ ledger, and loads a default population — no API key, no internet.
 ```bash
 hmctl quickstart                       # zero-to-verifiable swarm, no config
 hmctl init my-app                      # scaffold a starter project
-hmctl mcp install                      # wire into Claude Desktop / Cursor (52 tools)
+hmctl mcp install                      # wire into Claude Desktop / Cursor (57 tools)
 hmctl mcp install --local              # fully offline (Ollama + SQLite, no API key)
 hmctl serve-endpoint                   # OpenAI-compatible endpoint on :8899
 hmctl ingest notes.md --topic research # ingest documents into the swarm
@@ -284,17 +284,17 @@ hmctl status      # shows which features are active
 
 ## Status
 
-**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **1.6.0**.
+**Engineering GA** (1.0.0, 2026-07-09; SemVer binding). Current release: **1.7.3**.
 Remaining gates are **ecosystem, not code** (see [ROADMAP.md](ROADMAP.md) §External).
 
 - **Protocol** — 30 numbered spec sections (§01–§30, §21 split) + independent [`reference_verifier/`](reference_verifier/) proving two-impl interop
-- **SDK** — async-first, fully type-hinted, **2772 tests**; hybrid PQ signing, FROST k-of-n, dispute FSM (incl. `SUSPENDED`), capability tokens, RFC 6962 transparency
-- **52 MCP tools** — knowledge & retrieval, what-if simulation, adversarial debate, goal planning, hypothesis tracking, ingest, dataset export, population management, eval suite
+- **SDK** — async-first, fully type-hinted, **3197 tests**; hybrid PQ signing, FROST k-of-n, dispute FSM (incl. `SUSPENDED`), capability tokens, RFC 6962 transparency
+- **57 MCP tools** — knowledge & retrieval, what-if simulation, adversarial debate, goal planning, hypothesis tracking, ingest, dataset export, population management, eval suite
 - **Federation** — real multi-node TCP gossip (`TCPGossipBus`); `libp2p` is an optional external Rust binding
 - **SimLab web UI** at `make run`
 
 ```bash
-make test        # 2772 tests, ~90s
+make test        # 3197 tests, ~90s
 make lint        # ruff check + format
 make run         # SimLab web UI on http://127.0.0.1:8765
 ```