hypgraph 0.7.11__tar.gz → 0.7.13__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {hypgraph-0.7.11 → hypgraph-0.7.13}/AGENTS.md +6 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/CHANGELOG.md +89 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/NOTICE +1 -1
- {hypgraph-0.7.11 → hypgraph-0.7.13}/PKG-INFO +11 -3
- {hypgraph-0.7.11 → hypgraph-0.7.13}/README.md +10 -2
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/PLAN.md +31 -0
- hypgraph-0.7.13/docs/RELEASE-READINESS.md +118 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/review-2026-10-24.md +15 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/spec.md +42 -15
- hypgraph-0.7.13/docs/verification.md +98 -0
- hypgraph-0.7.13/examples/frameworks/README.md +70 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/pyproject.toml +4 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/__init__.py +3 -3
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/blind.py +2 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/bundle.py +168 -48
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/cli.py +21 -5
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/coord.py +30 -7
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/graph.py +33 -17
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/mcp.py +2 -2
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/server.py +38 -9
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/skill/SKILL.md +3 -1
- hypgraph-0.7.13/src/hypgraph/store.py +288 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/hypgraph.js +192 -35
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/workflow.py +1 -2
- hypgraph-0.7.13/tests/test_anchoring.py +131 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_blind_oracles.py +98 -1
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_d10.py +1 -1
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_engine.py +1 -1
- hypgraph-0.7.13/tests/test_framework_examples.py +50 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_surfaces.py +1 -1
- hypgraph-0.7.13/tests/test_trust_boundary.py +183 -0
- hypgraph-0.7.13/tests/test_verify_complete.py +291 -0
- hypgraph-0.7.11/src/hypgraph/store.py +0 -139
- {hypgraph-0.7.11 → hypgraph-0.7.13}/.gitignore +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/CITATION.cff +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/DISCLAIMER.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/LICENSE +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/decisions/ADR-001-token-bound-authors.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/decisions/ADR-002-governance-profiles.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/profile-workflows-plan.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/site-plan.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/ui-plan.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/workflows/README.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/workflows/knowledge.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/workflows/optimization.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/workflows/scientific.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/workflows/software.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/docs/workflows/trading.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/__main__.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/checks.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/demos/__init__.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/demos/broad_street.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/derive.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/language.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/plan.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/policy.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/profiles.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/references.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/refusals.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/report_check.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/schema.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/stats.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/__init__.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/atlas.css +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/atlas.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/hypgraph.css +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/hypgraph.svg +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/index.html +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/vendor/LICENSES.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/vendor/cose-base.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/vendor/cytoscape-fcose.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/vendor/cytoscape.min.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/src/hypgraph/ui/vendor/layout-base.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_accept_work_kind.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_blind.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_bound_support.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_bundle_telemetry.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_cancel_releases_lease.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_cited_and_failed_support.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_coord.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_engine_fixes.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_incremental.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_link_translate.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_log_and_check.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_measure_questions.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_opposed_answers.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_option_lead.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_order_detail.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_profiles.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_profiles_041.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_questions_not_assertions.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_references.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_refusal_friction.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_refusal_results.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_refusals.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_relation_words.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_report_answers.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_rerunnable.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_restates_scale.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_server_auth.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_server_hosts.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_shape_refusals.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_stats_not_backtests.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_stats_values.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_telemetry_stream.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_ui_app.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_ui_engine.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_uncorrected_effect.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_unnamed_inputs.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_versions_not_figures.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_vocabulary_friction.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.13}/tests/test_workflows.py +0 -0
|
@@ -39,6 +39,12 @@ For HTTP: `hypgraph --db study.hypgraph --as <your-name> mcp --transport http --
|
|
|
39
39
|
You write as one author, fixed when the server starts. The names `lab`, `operator`, `importer` and `system` are
|
|
40
40
|
reserved.
|
|
41
41
|
|
|
42
|
+
**If you hold a work order, `my_work()` comes first.** It gives each order's objective, method, and what counts as
|
|
43
|
+
done. A **blind** order seals other authors' work from you until you return it: `overview()`, `report()` and the like
|
|
44
|
+
answer that they are sealed, and sealed nodes show as placeholders. That is the point, not an error. Measure it
|
|
45
|
+
yourself, record your run and result, then `return_work`. What you write meanwhile is recorded as written blind, and
|
|
46
|
+
a result that matches an earlier one is marked as agreeing blind once the order is returned.
|
|
47
|
+
|
|
42
48
|
## The method
|
|
43
49
|
|
|
44
50
|
1. **`overview()` first.** Read what's known before re-deriving anything.
|
|
@@ -1,5 +1,94 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.13 — 2026-10-31: verification checks every row, and examples for agent frameworks
|
|
4
|
+
|
|
5
|
+
- **Verification checks every row, both ways.** A pre-launch audit found that `verify_bundle`, `verify_file` and
|
|
6
|
+
the browser's `verifyBundle` only checked that each row present matched an event. A bundle or graph file with a
|
|
7
|
+
withdrawal, a version, a link, a lease or a whole table removed still verified, so a withdrawn claim could come
|
|
8
|
+
back to life through `load()`; changed authors, times, link ends, reasons and duplicated rows passed too. Now every
|
|
9
|
+
row must be written by an event and match it field by field, every row an event wrote must be present, and no key
|
|
10
|
+
may appear twice, in Python, SQLite and the browser alike (`tests/test_verify_complete.py`, which also checks the
|
|
11
|
+
browser verifier agrees on every case).
|
|
12
|
+
- **Events hash every field of the row they write.** New events carry `reason_sha` (create, revise), `why_sha`
|
|
13
|
+
(link, retract, withdraw), `note_sha` (leases), a review's `code` and `inv`, and `as` when the importer credits
|
|
14
|
+
another author. Only the importer may. Older records still verify: what their events don't cover is reported as
|
|
15
|
+
`unchecked`, field by field, instead of passing silently.
|
|
16
|
+
- **Derived views are checked; standing is labelled.** A bundle's `derived` views must agree with the verified rows
|
|
17
|
+
on every fact the rows fix (nodes, live links, titles, authors, times, withdrawn or not); an edited view fails.
|
|
18
|
+
Standing can't be checked from the rows, so the result says `standing: {checked: false}`; `hypgraph verify
|
|
19
|
+
--standing` re-derives it with the same engine version and fails on a difference. The explorer shows a separate
|
|
20
|
+
"standing as exported" badge beside the verified one, and a banner over a record that doesn't verify.
|
|
21
|
+
- **The verify page takes a published head** and lists the fields an older record doesn't cover.
|
|
22
|
+
|
|
23
|
+
- **A LangChain example** (`examples/frameworks/langchain_agent.py`): `create_agent` with the record's tools from a
|
|
24
|
+
`MultiServerMCPClient` session, the same story as the others. It runs in the `frameworks` CI job.
|
|
25
|
+
- **Examples for agent frameworks** (`examples/frameworks/`): LangGraph, PydanticAI, CrewAI, the OpenAI Agents SDK
|
|
26
|
+
and the Claude Agent SDK, each connected to a record through `hypgraph mcp`. All five tell the same story: the
|
|
27
|
+
agent claims a 1.2-point difference is significant, the record refuses with the arithmetic, and the agent writes
|
|
28
|
+
the honest claim, which is accepted. They run offline with a scripted model through each framework's own
|
|
29
|
+
tool-calling path, or with `--real` on a real model. The README covers the one setting each framework needs so a
|
|
30
|
+
refusal reaches the model instead of ending the run. A new CI job runs them all (the Claude Agent SDK, which has no
|
|
31
|
+
scripted mode, gets a wiring check).
|
|
32
|
+
|
|
33
|
+
## 0.7.12 — 2026-10-31: the trust boundary, verification and docs, reviewed before launch
|
|
34
|
+
|
|
35
|
+
A pre-launch review of who may write as whom, through every interface. Each fix has a test that failed first
|
|
36
|
+
(`tests/test_trust_boundary.py`).
|
|
37
|
+
|
|
38
|
+
- **A page on another port can't write.** `hypgraph serve` compared a write's `Origin` by host name only, so a page
|
|
39
|
+
served from another port of the same machine (a dev server, an agent-built page) could write to a server running
|
|
40
|
+
without tokens. A browser write must now come from the exact host and port the server was reached at;
|
|
41
|
+
`Origin: null` is refused. Clients that send no `Origin` are unaffected.
|
|
42
|
+
- **A `*` token can't write as a reviewer.** `--token SECRET=*` covered every non-reserved name, reviewers included,
|
|
43
|
+
so an agent holding one could review its own work officially under a reviewer's name. A name on a review board
|
|
44
|
+
(the policy's reviewers, or the ones an investigation names) must now be named on a token. Tokens that name their
|
|
45
|
+
authors are unchanged.
|
|
46
|
+
- **Only an order's issuer directs it.** `accept_work`, `rework` and `settle` didn't check who called them, so a
|
|
47
|
+
worker (through its MCP seat, say) could rework its own order with an easier `done_when`, meet it and accept it.
|
|
48
|
+
Now only the author who issued an order, or a curator, accepts or reworks it, and `settle` settles only the
|
|
49
|
+
orders its caller issued. HypSwarm's scheduler and lead (which act as the harness that issued the orders) and
|
|
50
|
+
HypMesh pass their suites unchanged.
|
|
51
|
+
- **A bad `Content-Length` is a 400.** A non-numeric one crashed the request handler and a negative one held its
|
|
52
|
+
thread until the client hung up.
|
|
53
|
+
- **A refused write gets its refusal.** The server read a write's body only after the origin check, and closing on
|
|
54
|
+
an unread body reset the connection on Windows, so a client saw "connection aborted" instead of the 403.
|
|
55
|
+
- **More blind adversarial tests:** graph operations on sealed nodes (link, retract, withdraw, revise, lease), the
|
|
56
|
+
work-order lifecycle as the checker (return, accept, rework, cancel, settle), every enumeration route, 25 guesses
|
|
57
|
+
in a row on one record, and eight MCP tools. The chain head is no longer shown to a sealed reader (`/verify`, the
|
|
58
|
+
MCP `verify` tool): it is a hash over sealed bodies, and a reader that is sealed has no use for it.
|
|
59
|
+
- **SECURITY.md rewritten** for what the record enforces, which interface is trusted, what tokens do and don't
|
|
60
|
+
protect (writes, not reads), what blind orders protect and where they don't apply, and what verification shows.
|
|
61
|
+
|
|
62
|
+
Verification against a published head, and a clean-install walkthrough in CI:
|
|
63
|
+
|
|
64
|
+
- **`hypgraph verify --head HEX`** (and `verify_bundle(b, head=...)`, `anchored(res, head)`) fails unless the chain
|
|
65
|
+
ends at a head published elsewhere. A chain only shows it is consistent with itself: whoever can write a record can
|
|
66
|
+
change a claim and recompute every hash, or cut the record short, and it still verifies. `tests/test_anchoring.py`
|
|
67
|
+
does both and shows each verifying on its own and failing against the published head. `verify` now prints the full
|
|
68
|
+
head, the thing to publish.
|
|
69
|
+
- **[docs/verification.md](docs/verification.md)** separates the four guarantees (internal consistency, not
|
|
70
|
+
rewritten since published, provenance of the evidence, truth of a claim) and shows how to publish and sign a head
|
|
71
|
+
with tools readers already have (a paper, a signed tag, `ssh-keygen -Y sign`, a timestamp).
|
|
72
|
+
- **`dev/e2e_install.py`** installs HypGraph into a fresh environment and does what the README and `--help` say, as
|
|
73
|
+
someone who has never seen the repository: a record, an experiment and its result, a claim accepted and one refused
|
|
74
|
+
with the honest version, a review, an export, and verification elsewhere with no graph file. CI runs it on the
|
|
75
|
+
built wheel (with the MCP extra) and on the sdist, on Ubuntu and Windows; the release job runs it before
|
|
76
|
+
publishing.
|
|
77
|
+
|
|
78
|
+
Docs reconciled, GitHub Releases, a linter in CI:
|
|
79
|
+
|
|
80
|
+
- **Docs match the code.** `docs/review-2026-10-24.md` gets a status table: each finding checked against 0.7.11 by
|
|
81
|
+
running it, with the evidence (eight resolved, one in part). `docs/PLAN.md` says what is done, what moved
|
|
82
|
+
(authentication, anchoring) and where HypGraph ends and HypSwarm, HypMesh and HypDMZ begin. The README lists the
|
|
83
|
+
work-order tools and points to SECURITY.md. AGENTS.md, the Agent Skill and llms.txt tell an agent holding a work
|
|
84
|
+
order to start with `my_work()`, and that a blind order's sealed tools are expected, not an error.
|
|
85
|
+
- **GitHub Releases.** The release job creates one for each tag after PyPI has the files: the changelog's section,
|
|
86
|
+
how to install, and where to check provenance (`dev/release_notes.py`, which you can run to preview).
|
|
87
|
+
- **[docs/RELEASE-READINESS.md](docs/RELEASE-READINESS.md):** the pre-launch review's findings, what was fixed and
|
|
88
|
+
tested, the limitations accepted, what is deferred, and the recommendation (conditional go).
|
|
89
|
+
- **pyflakes in CI** (`ruff check`, rules `F` only): undefined names and dead imports, not style. Five unused imports
|
|
90
|
+
and one unused variable removed.
|
|
91
|
+
|
|
3
92
|
## 0.7.11 — 2026-10-30: a sealed checker can't learn the answer by asking
|
|
4
93
|
|
|
5
94
|
An adversarial test on a local HypMesh planted a 5-digit reading and 12-digit tags in a lead's sealed nodes and
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: hypgraph
|
|
3
|
-
Version: 0.7.
|
|
3
|
+
Version: 0.7.13
|
|
4
4
|
Summary: The evidence layer for AI research agents: a hash-chained research record that checks every claim as it is written and derives how well each is known.
|
|
5
5
|
Project-URL: Homepage, https://hypgraph.com
|
|
6
6
|
Project-URL: Documentation, https://hypgraph.com/engineers/
|
|
@@ -173,8 +173,16 @@ hypgraph skill --install # +
|
|
|
173
173
|
The server writes as one author, fixed when it starts. The agent can't pass another name or write as your job runner,
|
|
174
174
|
and its verdicts count only if you name it as a reviewer. Tools: `overview`, `find`, `show`, `start_investigation`,
|
|
175
175
|
`add`, `link`, `revise`, `withdraw`, `retract_link`, `review`, `next_experiments`, `work_queue`, `claim_work`,
|
|
176
|
-
`register_run`, `bound`, `check_report`, `refusal_log`, `report`, `verify`, `schema
|
|
177
|
-
|
|
176
|
+
`register_run`, `bound`, `check_report`, `refusal_log`, `report`, `verify`, `schema`; and for a team working through
|
|
177
|
+
work orders, `my_work`, `issue_work`, `return_work`, `check_work`, `accept_work`, `rework`, `cancel_work`,
|
|
178
|
+
`settle_work`, `cancel_moot`, `briefing`, `completion`, `stage`. A blind order (`issue_work(..., blind=true)`) seals
|
|
179
|
+
the record from its checker until it is returned. The method is in [AGENTS.md](https://github.com/voodoomods/hypgraph/blob/main/AGENTS.md); the short version is
|
|
180
|
+
[llms.txt](https://hypgraph.com/llms.txt). What the server enforces, and what it leaves to you, is in
|
|
181
|
+
[SECURITY.md](https://github.com/voodoomods/hypgraph/blob/main/SECURITY.md).
|
|
182
|
+
|
|
183
|
+
Runnable examples for LangChain, LangGraph, PydanticAI, CrewAI, the OpenAI Agents SDK and the Claude Agent SDK, each
|
|
184
|
+
the same story wired a different way, are in
|
|
185
|
+
[examples/frameworks](https://github.com/voodoomods/hypgraph/tree/main/examples/frameworks).
|
|
178
186
|
|
|
179
187
|
## Wire it into your system
|
|
180
188
|
|
|
@@ -141,8 +141,16 @@ hypgraph skill --install # +
|
|
|
141
141
|
The server writes as one author, fixed when it starts. The agent can't pass another name or write as your job runner,
|
|
142
142
|
and its verdicts count only if you name it as a reviewer. Tools: `overview`, `find`, `show`, `start_investigation`,
|
|
143
143
|
`add`, `link`, `revise`, `withdraw`, `retract_link`, `review`, `next_experiments`, `work_queue`, `claim_work`,
|
|
144
|
-
`register_run`, `bound`, `check_report`, `refusal_log`, `report`, `verify`, `schema
|
|
145
|
-
|
|
144
|
+
`register_run`, `bound`, `check_report`, `refusal_log`, `report`, `verify`, `schema`; and for a team working through
|
|
145
|
+
work orders, `my_work`, `issue_work`, `return_work`, `check_work`, `accept_work`, `rework`, `cancel_work`,
|
|
146
|
+
`settle_work`, `cancel_moot`, `briefing`, `completion`, `stage`. A blind order (`issue_work(..., blind=true)`) seals
|
|
147
|
+
the record from its checker until it is returned. The method is in [AGENTS.md](https://github.com/voodoomods/hypgraph/blob/main/AGENTS.md); the short version is
|
|
148
|
+
[llms.txt](https://hypgraph.com/llms.txt). What the server enforces, and what it leaves to you, is in
|
|
149
|
+
[SECURITY.md](https://github.com/voodoomods/hypgraph/blob/main/SECURITY.md).
|
|
150
|
+
|
|
151
|
+
Runnable examples for LangChain, LangGraph, PydanticAI, CrewAI, the OpenAI Agents SDK and the Claude Agent SDK, each
|
|
152
|
+
the same story wired a different way, are in
|
|
153
|
+
[examples/frameworks](https://github.com/voodoomods/hypgraph/tree/main/examples/frameworks).
|
|
146
154
|
|
|
147
155
|
## Wire it into your system
|
|
148
156
|
|
|
@@ -108,3 +108,34 @@ claim's derived standing.
|
|
|
108
108
|
|
|
109
109
|
Multi-writer sync between graphs (bundles cover sharing), authentication (the host's job; the HTTP server binds to
|
|
110
110
|
loopback and is read-only unless started with `--writable`), and a hosted service.
|
|
111
|
+
|
|
112
|
+
## Status at 0.7.13 (2026-10-31)
|
|
113
|
+
|
|
114
|
+
All seven phases are done: the library, bundles, the server and UI, the MCP server, the website, Pegasus running on
|
|
115
|
+
the package, and releases to PyPI from tags with trusted publishing. What came after the plan, by release, is in
|
|
116
|
+
[CHANGELOG.md](../CHANGELOG.md); the main additions were profiles and their workflows (0.5), the coordination layer
|
|
117
|
+
of work orders (0.4), pinned references between records (0.7.8) and blind work orders (0.7.9–0.7.11).
|
|
118
|
+
|
|
119
|
+
Two lines above have moved:
|
|
120
|
+
|
|
121
|
+
- **Authentication** is no longer only the host's job. `hypgraph serve` binds writes to bearer tokens
|
|
122
|
+
(`--token SECRET=authors`), refuses writes from other origins, and keeps reserved and reviewer names for tokens that
|
|
123
|
+
name them. Reads stay open; see [SECURITY.md](../SECURITY.md).
|
|
124
|
+
- **Anchoring** has a verifier: `hypgraph verify --head` checks a record against a head published elsewhere
|
|
125
|
+
([verification.md](verification.md)).
|
|
126
|
+
|
|
127
|
+
Still out of scope: sync between records (bundles and pinned references cover sharing), a hosted service, and any
|
|
128
|
+
judgement by a model. The rules stay deterministic.
|
|
129
|
+
|
|
130
|
+
## Where HypGraph ends
|
|
131
|
+
|
|
132
|
+
HypGraph is useful on its own, with nothing else from the family installed:
|
|
133
|
+
|
|
134
|
+
| | Responsibility |
|
|
135
|
+
|---|---|
|
|
136
|
+
| **HypGraph** | The record: evidence, its rules, derived standing, coordination through work orders, verification. |
|
|
137
|
+
| **HypSwarm** | Running a team of agents on a record: the scheduler, seats, budgets, telemetry. |
|
|
138
|
+
| **HypMesh** | A public mesh of records, one per open question: identities, agent tokens, standing across organisations. |
|
|
139
|
+
| **HypDMZ** | Running a swarm in a locked pod: governed egress, the vaulted key, an audit chain. |
|
|
140
|
+
|
|
141
|
+
A feature belongs in HypGraph only if a single user with one record needs it.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# Release readiness: the public developer preview
|
|
2
|
+
|
|
3
|
+
*Written 2026-10-31 against 0.7.11 (`87b4c14`) and three pull requests: #59 (trust boundary), #60 (verification),
|
|
4
|
+
#61 (docs and release engineering). Everything marked as tested was run; the commands are in each PR. Nothing here
|
|
5
|
+
was taken from a changelog without being checked against the code.*
|
|
6
|
+
|
|
7
|
+
> **Superseded in part (2026-10-31, later the same day).** A second audit found that verification checked rows
|
|
8
|
+
> against events in one direction only: a bundle or graph file with a withdrawal, a version, an edge or a whole
|
|
9
|
+
> table removed still verified, as did changed authors, times, link ends and reasons, and edited derived views. That
|
|
10
|
+
> was a confirmed integrity defect, so the GO below didn't hold for 0.7.12. The fix (exhaustive row checks in the
|
|
11
|
+
> Python, SQLite and browser verifiers, events that hash every row field, derived views checked against the rows,
|
|
12
|
+
> standing reported as not covered) is in the pull request that adds `tests/test_verify_complete.py`, and ships as
|
|
13
|
+
> 0.7.13. The recommendation stands again once that is merged with green CI and released.
|
|
14
|
+
>
|
|
15
|
+
> **Where that stands.** #66 is merged with green CI (17 of 17 checks); on main the suite is 386 passed, and
|
|
16
|
+
> hypswarm, hypmesh and hypdmz pass on it. Released as 0.7.13. The required-checks setting (condition 3 below) is
|
|
17
|
+
> still open, for the operator.
|
|
18
|
+
|
|
19
|
+
## Recommendation: CONDITIONAL GO
|
|
20
|
+
|
|
21
|
+
HypGraph is ready for a public developer preview once #59, #60 and #61 are merged with green CI and released as one
|
|
22
|
+
version. The review found five defects at the trust boundary and two gaps in verification. Each is fixed in those
|
|
23
|
+
PRs, with a regression test that failed first. No confirmed security, integrity or correctness defect remains open.
|
|
24
|
+
The conditions are small, and the limitations below are documented where a user will meet them.
|
|
25
|
+
|
|
26
|
+
**Conditions**
|
|
27
|
+
|
|
28
|
+
1. Merge #59, then #60, then #61, each with green CI. They all touch the top of the changelog, so main gets merged
|
|
29
|
+
into the next one in line.
|
|
30
|
+
2. Release them as one version through the usual release PR, tag and PyPI check. That release is the first to create
|
|
31
|
+
a GitHub Release by itself.
|
|
32
|
+
3. Make the `ui`, `install` and `lint` jobs required checks in the `protect main` ruleset. Today only the 12 `test`
|
|
33
|
+
jobs are required. This is a repository setting, so it's the operator's call.
|
|
34
|
+
|
|
35
|
+
**Where the conditions stand.** 1: #59, #60 and #61 are merged, each with green CI; on main after the merges the
|
|
36
|
+
suite is 343 passed. 2: released as 0.7.12. 3: open, for the operator.
|
|
37
|
+
|
|
38
|
+
## What was reviewed
|
|
39
|
+
|
|
40
|
+
The threat model is in [SECURITY.md](../SECURITY.md):
|
|
41
|
+
- **Trusted callers:** the Python API and the CLI. Whoever holds the file owns the record.
|
|
42
|
+
- **Untrusted callers:** agents at `hypgraph serve` and `hypgraph mcp`.
|
|
43
|
+
- **The host's job:** who can read the port or the file, who holds which token, and where a record's head is
|
|
44
|
+
published.
|
|
45
|
+
|
|
46
|
+
Interfaces examined: the Python API, the CLI, the HTTP server (`server.py`), the MCP server (`mcp.py`), blind work
|
|
47
|
+
orders (`blind.py`, `coord.py`), and bundle export and verification (`bundle.py`, `store.py`).
|
|
48
|
+
|
|
49
|
+
## Findings
|
|
50
|
+
|
|
51
|
+
| # | Finding | Class | Status | Evidence |
|
|
52
|
+
|---|---|---|---|---|
|
|
53
|
+
| 1 | A page on another port of the same machine could write to a server without tokens: the cross-origin check compared host names only. | Confirmed defect | Fixed in #59 | `test_a_page_on_another_local_port_cannot_write` |
|
|
54
|
+
| 2 | A `*` token could write as a reviewer, and so review its own work officially. | Confirmed defect | Fixed in #59 | `test_a_wildcard_token_cannot_write_as_a_reviewer` |
|
|
55
|
+
| 3 | A worker could `rework` its own order with an easier `done_when`, meet it and `accept_work` it. Neither call checked the caller. | Confirmed defect | Fixed in #59 | `test_a_worker_cannot_accept_rework_or_settle_its_own_order`. HypSwarm (119) and HypMesh (37) pass unchanged. |
|
|
56
|
+
| 4 | A non-numeric `Content-Length` crashed the handler, and a negative one held a thread until the client hung up. | Confirmed defect | Fixed in #59 | `test_a_bad_content_length_is_refused` |
|
|
57
|
+
| 5 | A refused write's unread body reset the connection on Windows, so the client never saw its 403. | Confirmed defect | Fixed in #59 | Found as a flaky test; 15 of 15 runs passed after the fix |
|
|
58
|
+
| 6 | A sealed reader could see the chain head, a hash over sealed bodies. Not a practical oracle: testing a guess offline needs every other byte of those bodies, random ids included. | Security concern | Withheld in #59 | `test_enumeration_routes_carry_nothing_sealed` |
|
|
59
|
+
| 7 | Blind orders: no new oracle across graph operations on sealed nodes, the work-order lifecycle, 15 enumeration routes, 25 guesses in a row on one record, and 8 MCP tools. | Investigated | Holds | `tests/test_blind_oracles.py`, 36 tests. The oracles found earlier were fixed in 0.7.11. |
|
|
60
|
+
| 8 | Nothing checked a record against a published head. A rewritten-and-rehashed or truncated record verifies on its own. | Confirmed gap | Fixed in #60 (`verify --head`) | `tests/test_anchoring.py` |
|
|
61
|
+
| 9 | Clean install never ran the documented steps. The release job ran only the demo on the wheel, and never installed the sdist. | Release process | Fixed in #60 (`dev/e2e_install.py` in CI and in the release job) | Wheel with MCP 21/21; sdist 20/20 |
|
|
62
|
+
| 10 | SECURITY.md said "No authentication" after token-bound writes shipped, and didn't say that tokens protect writes but not reads. | Documentation | Fixed in #59 | — |
|
|
63
|
+
| 11 | No GitHub Releases for 24 tags. | Release process | Fixed in #61 for future tags | `dev/release_notes.py` |
|
|
64
|
+
| 12 | The review of 2026-10-24 and PLAN.md described an earlier state; the agent docs said "`overview()` first", which a blind checker is refused. | Documentation | Fixed in #61 | Each review finding re-run against 0.7.11 |
|
|
65
|
+
| 13 | No linter. | Release process | pyflakes rules in CI in #61; 6 findings fixed | — |
|
|
66
|
+
| 14 | The committed `site/assets/site-data.js` says 188 tests. | Documentation | Accepted | It's a generated file, and the Pages deploy regenerates it. The live site showed 310 of 310, built 2026-10-31 02:54Z. |
|
|
67
|
+
|
|
68
|
+
Checked and holding, with no change needed:
|
|
69
|
+
- reserved names need a token that names them;
|
|
70
|
+
- official self-review is refused through every interface;
|
|
71
|
+
- the HTTP write takes no time, attribution, id or code from the writer;
|
|
72
|
+
- the MCP seat can't start as a reserved name;
|
|
73
|
+
- only the lease holder releases a lease, and only a link's author, a reviewer or the operator retracts a link;
|
|
74
|
+
- the release job checks the tag against the version;
|
|
75
|
+
- PyPI publishing is trusted and carries a provenance attestation;
|
|
76
|
+
- every tool name in the agent docs exists on the MCP server, and every hypgraph.com page the README links answers.
|
|
77
|
+
|
|
78
|
+
## Verification report
|
|
79
|
+
|
|
80
|
+
| | Result |
|
|
81
|
+
|---|---|
|
|
82
|
+
| Full suite, each branch, Windows 11, Python 3.13 | #59: 338 passed · #60: 320 passed · #61: 315 passed. 0.7.11 had 315. |
|
|
83
|
+
| CI matrix | Ubuntu, macOS and Windows × Python 3.10–3.13 (12 jobs), plus the UI smoke test in Chrome. #60 adds `install` (Ubuntu, Windows) and #61 adds `lint`. All green on each PR's head: #59 13 of 13, #60 15 of 15, #61 14 of 14. |
|
|
84
|
+
| Clean install of the built wheel with the MCP extra | 21 of 21 documented steps |
|
|
85
|
+
| Clean install of the sdist | 20 of 20 |
|
|
86
|
+
| Clean install of `hypgraph==0.7.11` from PyPI | 19 of 20. The failing step is `verify --head`, which is new in #60. |
|
|
87
|
+
| Bundle verification | Passes on a demo export, in another process and directory with no graph file. Fails on an edited body, a swapped event, a changed node code, a create event forged as redacted, a swapped head, and (with `--head`) a rewritten-and-rehashed record or a truncated one. |
|
|
88
|
+
| Downstream | HypSwarm 119 passed, 6 skipped; HypMesh 37 passed, both against #59 |
|
|
89
|
+
|
|
90
|
+
## Accepted limitations
|
|
91
|
+
|
|
92
|
+
These are documented in SECURITY.md and docs/verification.md, where a user meets them.
|
|
93
|
+
|
|
94
|
+
- **Names aren't people.** The record can't tell that two author names are one agent. Review independence holds
|
|
95
|
+
only as far as names are authenticated: named tokens, or one MCP seat per agent. A server with `--writable` and
|
|
96
|
+
no tokens authenticates nobody.
|
|
97
|
+
- **Reads aren't authenticated.** `hypgraph serve` serves every `GET` to whoever can reach the port. Keep it on
|
|
98
|
+
loopback, or behind a proxy that authenticates readers.
|
|
99
|
+
- **Blind orders need a host that seals.** The MCP seat and HypMesh seal; plain `hypgraph serve` and the Python API
|
|
100
|
+
don't. Reads made before the order can't be undone. The leak check catches numbers quoted by accident, not a lead
|
|
101
|
+
leaking on purpose. Timing isn't hidden.
|
|
102
|
+
- **A head is only as good as where it's published.** `verify --head` proves the record is the one that was
|
|
103
|
+
published. Who published that head is for the signature, the paper or the tag to establish.
|
|
104
|
+
- **A single-number blind check is never marked as agreeing.** Results restate each other only when they carry two
|
|
105
|
+
or more numbers, a guard against coincidence. A blind check of one count is recorded as written blind, but not as
|
|
106
|
+
`agrees_blind`. It's documented in the changelog, not yet changed.
|
|
107
|
+
|
|
108
|
+
## Deferred until after launch
|
|
109
|
+
|
|
110
|
+
- **Comparative evaluation.** Does recording through HypGraph reduce unsupported claims in agents' final reports?
|
|
111
|
+
The design: the same model, tools, tasks and budget, with and without the record, scored against criteria fixed
|
|
112
|
+
in advance by a scorer that isn't HypGraph. The measures would be unsupported claims, wrong numbers, overstated
|
|
113
|
+
certainty, honest claims wrongly refused, completion and cost. It needs a preregistration and a budget decision,
|
|
114
|
+
and no result is claimed until it has run.
|
|
115
|
+
- **Coverage reporting.** The security-sensitive paths have targeted tests: the trust boundary, the blind oracles,
|
|
116
|
+
anchoring, the bundle negatives. A coverage percentage would add little to that.
|
|
117
|
+
- **GitHub Releases for the 24 past tags.** `dev/release_notes.py` can write the notes for each; publishing them is
|
|
118
|
+
the operator's decision.
|
|
@@ -41,6 +41,21 @@ accept each agent's work, so a team coordinates through the record instead of th
|
|
|
41
41
|
|
|
42
42
|
Ranked by how much they matter, with the evidence.
|
|
43
43
|
|
|
44
|
+
> **Status at 0.7.11, checked 2026-10-31** by running each case against the code, not from the changelog alone:
|
|
45
|
+
>
|
|
46
|
+
> | Finding | Status | Evidence |
|
|
47
|
+
> |---|---|---|
|
|
48
|
+
> | 3.1 honest negations refused | Resolved (0.7.2) | "A is not significantly more accurate than B (812 of 1000 vs 800 of 1000)" is accepted; the same sentence without "not" is refused with the test's p-value. |
|
|
49
|
+
> | 3.2 refuse less, bind more | Resolved | A claim whose number sits in the author's result is accepted with the note "bound by the record: 812 → RS1.a" (`Graph._auto_bind`). |
|
|
50
|
+
> | 3.3 tell every agent when it is done | Resolved | Every write's reply carries the author's open orders with their predicates checked (`Graph._with_orders` → `coord.done_lines`). |
|
|
51
|
+
> | 3.4 the briefing as a question board | Resolved (0.4.0) | `question_board`; the briefing is organised by question. |
|
|
52
|
+
> | 3.5 duplicate results | Resolved in part | The same author repeating a result is refused (`RESULT_RESTATES`). Another author's repeat is accepted and derived as `restates` (one line of evidence, not two), or, written blind, as `agrees_blind`. |
|
|
53
|
+
> | 3.6 automate the mechanical half of the lead | Resolved (0.4.0) | `settle` / MCP `settle_work` accepts every returned order whose predicates are all met. |
|
|
54
|
+
> | 3.7 three-character titles | Resolved | A title of "CRP" is accepted. |
|
|
55
|
+
> | 3.7 "every … (68 of 68)" refused | Resolved | The count in the sentence is accepted; a constant such as the "/ 10" in that sentence still has to be declared in the scope, as designed. |
|
|
56
|
+
> | 3.7 `register_run`'s message | Resolved | A run with no code or command is refused with "say what ran: code_paths (hashed) and/or command". |
|
|
57
|
+
> | 3.8 positioning | Holds | The site and the README make no cost claim. |
|
|
58
|
+
|
|
44
59
|
### 3.1 The checker refuses honest negations (a bug in the flagship feature)
|
|
45
60
|
|
|
46
61
|
`checks.py` listens for "significantly" and runs the test on the bound counts, but it does not read the
|
|
@@ -78,19 +78,35 @@ where `prev` is the previous event's hash (64 zeros for the first). Kinds and pa
|
|
|
78
78
|
|
|
79
79
|
| kind | ref | payload |
|
|
80
80
|
|---|---|---|
|
|
81
|
-
| `create` | the new node | `{type, code, inv, v: 1, body_sha}`; `body_sha` = sha256 of the version's stored body string |
|
|
82
|
-
| `revise` | the node | `{v, reason, body_sha}` |
|
|
83
|
-
| `review` | the reviewed node | `{review: <review node id>, verdict, on_v, official, body_sha}` |
|
|
84
|
-
| `link` | the edge's source | `{edge, rel, dst, src_v, dst_v, data_sha}`; `data_sha` = sha256 of the stored edge data string |
|
|
85
|
-
| `retract` | the edge's source | `{edge}` |
|
|
86
|
-
| `withdraw` | the node | `{why}` |
|
|
87
|
-
| `lease_take` / `lease_release` | the node | `{task, expires}` |
|
|
88
|
-
|
|
89
|
-
Any event may carry `task` in its payload: the unit of work that wrote it.
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
81
|
+
| `create` | the new node | `{type, code, inv, v: 1, body_sha, reason_sha, as?}`; `body_sha` = sha256 of the version's stored body string, `reason_sha` of its stored reason |
|
|
82
|
+
| `revise` | the node | `{v, reason, body_sha, reason_sha}`; `reason` is the first 300 characters |
|
|
83
|
+
| `review` | the reviewed node | `{review: <review node id>, verdict, on_v, official, body_sha, code, inv, as?}` |
|
|
84
|
+
| `link` | the edge's source | `{edge, rel, dst, src_v, dst_v, data_sha, why_sha}`; `data_sha` = sha256 of the stored edge data string, `why_sha` of its stored reason |
|
|
85
|
+
| `retract` | the edge's source | `{edge, why_sha}` |
|
|
86
|
+
| `withdraw` | the node | `{why, why_sha, as?}`; `why` is the first 300 characters, `why_sha` covers the stored reason |
|
|
87
|
+
| `lease_take` / `lease_release` | the node | `{task, expires, note_sha, for?}`; `for` = the agent holding the lease when it isn't the actor |
|
|
88
|
+
|
|
89
|
+
Any event may carry `task` in its payload: the unit of work that wrote it. `as` appears only when the importer
|
|
90
|
+
credits a node or withdrawal to another author; from any other actor it is invalid.
|
|
91
|
+
|
|
92
|
+
**Verifying** a record means recomputing every hash in order and checking each `prev`, then checking the rows
|
|
93
|
+
against the events **both ways**: every row was written by an event and matches it field by field, every row an
|
|
94
|
+
event wrote is present, and no key appears twice. The fields each event fixes:
|
|
95
|
+
|
|
96
|
+
| table | key | must equal |
|
|
97
|
+
|---|---|---|
|
|
98
|
+
| `nodes` | `create.ref`, `review.payload.review` | `type`, `code`, `inv` from the payload (a review: type `review`); `created_at` = the event's `at`; `created_by` = the actor, or `as` |
|
|
99
|
+
| `versions` | node + `v` | `at`, `by` = the actor, sha256 of `body` = `body_sha`, sha256 of `reason` = `reason_sha` (a review's: empty) |
|
|
100
|
+
| `edges` | `payload.edge` | `src` = ref, `rel`, `dst`, `src_v`, `dst_v`, `at`, `by` = the actor, sha256 of `data` = `data_sha`, of `why` = `why_sha` |
|
|
101
|
+
| `withdrawals` | the node | `at`, `by` = the actor or `as`, sha256 of `why` = `why_sha` |
|
|
102
|
+
| `retractions` | `payload.edge` | `at`, `by` = the actor, sha256 of `why` = `why_sha` |
|
|
103
|
+
| `leases` | in id order, one per lease event in order | `node` = ref, `agent` = `for` or the actor, `task`, `kind` (`take` / `release`), `at`, `expires`, sha256 of `note` = `note_sha` |
|
|
104
|
+
|
|
105
|
+
Records written before these fields existed (before 0.7.13) carry events without `reason_sha`, `why_sha`,
|
|
106
|
+
`note_sha`, `as`, or a review's `code` and `inv`. A verifier checks what those events do carry (a revision's or a
|
|
107
|
+
withdrawal's first 300 characters, a lease note given in full, a review's investigation from its target) and
|
|
108
|
+
reports every other non-empty field as **not covered**, by table and field, rather than passing it silently. Without
|
|
109
|
+
`as`, a row the importer wrote may credit any author; that is reported too.
|
|
94
110
|
|
|
95
111
|
## 4. Bundles — `hypgraph/1-bundle`
|
|
96
112
|
|
|
@@ -108,7 +124,7 @@ strings and compares.
|
|
|
108
124
|
"versions": [{"node": "…", "v": 1, "at": "…", "by": "…", "reason": "", "body": "<stored canonical string>"}],
|
|
109
125
|
"edges": [{"id": 1, "src": "…", "src_v": 1, "rel": "…", "dst": "…", "dst_v": 1, "data": "<stored string>", "…": "…"}],
|
|
110
126
|
"withdrawals": [], "retractions": [], "leases": [],
|
|
111
|
-
"derived": {"…": "
|
|
127
|
+
"derived": {"…": "views for viewers; their facts are checked against the rows, their standing is not"}}
|
|
112
128
|
```
|
|
113
129
|
|
|
114
130
|
A **scoped** bundle (one investigation out of a shared record) replaces events outside it with
|
|
@@ -118,7 +134,18 @@ keep it in a record of its own.
|
|
|
118
134
|
|
|
119
135
|
**Anchoring.** A bundle proves only its own consistency. To prove it wasn't rebuilt from scratch, publish its `head`
|
|
120
136
|
hash somewhere independent at the time (a paper, a preregistration, a repository tag). A later bundle whose chain
|
|
121
|
-
passes through that hash can't have rewritten anything before it.
|
|
137
|
+
passes through that hash can't have rewritten anything before it. A verifier given a published head (the full hash,
|
|
138
|
+
or a prefix of at least 16 hex characters) fails unless the chain ends there: `hypgraph verify FILE --head HEX`,
|
|
139
|
+
`verify_bundle(b, head=HEX)`. A bundle without a `head` field is checked for consistency only. How a head is
|
|
140
|
+
published and signed, and what each check does and doesn't show: [verification.md](verification.md).
|
|
141
|
+
|
|
142
|
+
**Derived views.** `derived` is a convenience for viewers, and a viewer shows it beside a verified chain, so a
|
|
143
|
+
verifier must check every fact in it that the rows fix: which investigations it covers (the scope's, or every
|
|
144
|
+
investigation node), which nodes each investigation's graph shows (all of them, unless capped at 5,000) and which
|
|
145
|
+
live (unretracted) links among them, each node's `type`, `code`, `inv`, `by`, `at`, `v`, `title` and `kind`, whether
|
|
146
|
+
it is shown as withdrawn, and each link's fields. **Standing** (review state, support, at-risk, the sentence) can't
|
|
147
|
+
be checked from the rows alone: it is what the exporting engine derived. A verifier reports it as not checked, or
|
|
148
|
+
re-derives it with the same engine version (`hypgraph verify FILE --standing`) and compares.
|
|
122
149
|
|
|
123
150
|
## 5. Derived standing (normative)
|
|
124
151
|
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Verifying a record
|
|
2
|
+
|
|
3
|
+
A HypGraph record can be checked by someone who doesn't trust whoever kept it. This page says what each check shows,
|
|
4
|
+
and the one step that turns "consistent" into "not rewritten": checking the record against a head published
|
|
5
|
+
somewhere its keeper can't change.
|
|
6
|
+
|
|
7
|
+
## Four different guarantees
|
|
8
|
+
|
|
9
|
+
| | What it shows | How | What it doesn't show |
|
|
10
|
+
|---|---|---|---|
|
|
11
|
+
| **1. Internal consistency** | The chain of events is unbroken; every node, version, link, withdrawal, retraction and lease was written by an event and matches it field by field; no row an event wrote is missing; and the facts a viewer shows beside it (which nodes and links, titles, authors, times, withdrawn or not) agree with those rows. | `hypgraph verify study.bundle.json` (or a graph file), `verify_bundle(b)` in Python, `HypGraph.verifyBundle` in the browser | That it wasn't rewritten. Whoever can write the record can change it, recompute every hash, or cut it short, and it still verifies. |
|
|
12
|
+
| **2. Not rewritten since it was published** | The record ends at the head that was published. Any change to anything before it, or a record cut short, ends somewhere else. | `hypgraph verify study.bundle.json --head <published head>`, `verify_bundle(b, head=...)`, `anchored(g.verify(), head)` | Who published that head. That's the job of where it was published (below). |
|
|
13
|
+
| **3. Provenance of the evidence** | Who recorded what, and how: a lab-recorded run (only the instrument author files those) or an agent's report, its inputs and outputs by hash, which lines of support are independent. | The record's derived standing: `hypgraph show CL1 --why`, the report | That the instrument's own files are honest. A host decides who the instrument is (the policy). |
|
|
14
|
+
| **4. That a claim is true** | Nothing. | Reviews, replications, separate implementations, new data: the evidence the record keeps and ranks | — |
|
|
15
|
+
|
|
16
|
+
A verified bundle with a matching published head proves the record is the one that was published, unchanged. The
|
|
17
|
+
claims in it stand exactly as well as the record derives, and no better.
|
|
18
|
+
|
|
19
|
+
## Publishing a head
|
|
20
|
+
|
|
21
|
+
`hypgraph verify` prints the full head:
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
$ hypgraph demo && hypgraph export -o study.bundle.json
|
|
25
|
+
Wrote study.bundle.json: 59 events, 24 nodes
|
|
26
|
+
$ hypgraph verify study.bundle.json
|
|
27
|
+
✓ study.bundle.json: 59 events verified — chain intact, every row matches the event that wrote it, and none is missing.
|
|
28
|
+
head 565123f3a7ac06ed18ab555935fde0457ebb6a302dc188fc83dbf36af579623f
|
|
29
|
+
consistent with itself; to rule out a rewrite, check it against a published head (--head)
|
|
30
|
+
standing not checked: standing (review state, support, at-risk, the sentence) is what the exporting engine derived: …
|
|
31
|
+
$ hypgraph verify study.bundle.json --head 565123f3a7ac06ed
|
|
32
|
+
✓ study.bundle.json: 59 events verified — chain intact, every row matches the event that wrote it, and none is missing.
|
|
33
|
+
head 565123f3a7ac06ed18ab555935fde0457ebb6a302dc188fc83dbf36af579623f
|
|
34
|
+
matches the anchored head: not rewritten or cut short since it was published
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
(Your head will differ: node ids and times are part of what is hashed.)
|
|
38
|
+
|
|
39
|
+
Publish that head somewhere you don't control after the fact. Any of these is enough, and none needs new
|
|
40
|
+
infrastructure:
|
|
41
|
+
|
|
42
|
+
- **In the paper, preregistration or report** that relies on the record: "Record head: `565123f3a7ac…`".
|
|
43
|
+
- **As a release asset or in a signed tag** of the repository that holds the work: `git tag -s study-v1 -m "head 565123f3…"`.
|
|
44
|
+
- **Signed with a key your readers already trust**, using tools they already have:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
hypgraph verify study.bundle.json --json | python -c "import json,sys; print(json.load(sys.stdin)['head'])" > study.head
|
|
48
|
+
ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n hypgraph-head study.head # writes study.head.sig
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
and a reader checks the signature, then the record against it:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
ssh-keygen -Y verify -f allowed_signers -I you@example.org -n hypgraph-head -s study.head.sig < study.head
|
|
55
|
+
hypgraph verify study.bundle.json --head "$(cat study.head)"
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
- **With a third-party timestamp** (an RFC 3161 service, or any public notarisation) over `study.head`, if you need
|
|
59
|
+
to show *when*.
|
|
60
|
+
|
|
61
|
+
A record keeps growing. Publish the head of each version you rely on; a later bundle still verifies, and its chain
|
|
62
|
+
passes through every earlier head (an earlier head is the `hash` of one of its events).
|
|
63
|
+
|
|
64
|
+
## Checking without HypGraph
|
|
65
|
+
|
|
66
|
+
The bundle stores every event and every version body as the exact string that was hashed. A verifier only runs
|
|
67
|
+
SHA-256 over strings and compares: no JSON canonicalisation to reimplement. The record format, including the bundle
|
|
68
|
+
and the verifier's rules, is in [spec.md](spec.md). The site checks bundles in the browser with WebCrypto, from a
|
|
69
|
+
separate implementation.
|
|
70
|
+
|
|
71
|
+
## Standing, and older records
|
|
72
|
+
|
|
73
|
+
- **Standing** (review state, support, at-risk, the one-line summary) is derived, and a bundle carries the standing
|
|
74
|
+
its exporter derived. The chain doesn't cover it. `hypgraph verify study.bundle.json --standing` replays the
|
|
75
|
+
verified rows and derives it again; it fails if the result differs. Standing rules change between releases, so it
|
|
76
|
+
only compares a bundle exported by the same version, and says so otherwise. A graph file has no stored standing:
|
|
77
|
+
it is derived on every read.
|
|
78
|
+
- **Records written before 0.7.13** have events that don't hash a few row fields (a link's reason, a retraction's
|
|
79
|
+
reason, a lease note, a revision's full reason, the credited author of an importer's node). The verifier checks
|
|
80
|
+
what those events carry and lists the rest as *not covered*, with a count per field. Rewriting one of those fields
|
|
81
|
+
in an old record isn't caught; new writes cover them all.
|
|
82
|
+
|
|
83
|
+
## Scoped bundles and references
|
|
84
|
+
|
|
85
|
+
- `hypgraph export --inv INV` writes one investigation. Events outside it are redacted to their hash, so the chain
|
|
86
|
+
still verifies, but their content can't be checked; the verifier says how many. The full record rules out a change
|
|
87
|
+
hidden among them.
|
|
88
|
+
- A source that pins another record's node checks that the cited body still hashes to the pinned version. It doesn't
|
|
89
|
+
check the cited record's history: for that, verify that record against its own published head.
|
|
90
|
+
|
|
91
|
+
## Try it
|
|
92
|
+
|
|
93
|
+
`dev/e2e_install.py` installs HypGraph into a fresh environment and walks the whole path: a record, a claim accepted
|
|
94
|
+
and one refused, a review, an export, and verification in another directory with no graph file, on its own and
|
|
95
|
+
against the head, and failing on an edited copy. `tests/test_verify_complete.py` drops, duplicates, empties and
|
|
96
|
+
edits every table and every field of a bundle and of a graph file, and edits the derived views: each one fails, in
|
|
97
|
+
Python and in the browser verifier alike. `tests/test_anchoring.py` rewrites a record (changing a claim and
|
|
98
|
+
recomputing every hash) and cuts one short: both verify on their own, and both fail against the published head.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# HypGraph with agent frameworks
|
|
2
|
+
|
|
3
|
+
One story, told once per framework, so the difference between the files is only the wiring.
|
|
4
|
+
|
|
5
|
+
An eval harness has compared two models on the same 1,000 held-out questions: model A got 812 right, model B 800.
|
|
6
|
+
An agent, connected to the record over MCP as the author `analyst`, is asked whether A is more accurate. It writes
|
|
7
|
+
"significantly more accurate". The record refuses that with the arithmetic (p ≈ 0.5) and says what to write instead.
|
|
8
|
+
The agent writes the honest claim, and it is accepted. Afterwards the script reads the record in Python and prints
|
|
9
|
+
what was refused, what was accepted, and the refusal log.
|
|
10
|
+
|
|
11
|
+
The framework doesn't need to know HypGraph exists. It sees MCP tools, and the record does the checking.
|
|
12
|
+
|
|
13
|
+
| Framework | File | Install | MCP wiring |
|
|
14
|
+
|---|---|---|---|
|
|
15
|
+
| LangChain | [langchain_agent.py](langchain_agent.py) | `langchain langchain-mcp-adapters` | `MultiServerMCPClient` session → `create_agent` |
|
|
16
|
+
| LangGraph | [langgraph_agent.py](langgraph_agent.py) | `langgraph langchain-mcp-adapters` | `load_mcp_tools(session)` into a `ToolNode` |
|
|
17
|
+
| PydanticAI | [pydantic_ai_agent.py](pydantic_ai_agent.py) | `"pydantic-ai-slim[mcp]"` | `MCPToolset(StdioTransport(...))` |
|
|
18
|
+
| CrewAI | [crewai_agent.py](crewai_agent.py) | `crewai` | `Agent(mcps=[MCPServerStdio(...)])` |
|
|
19
|
+
| OpenAI Agents SDK | [openai_agents_sdk.py](openai_agents_sdk.py) | `openai-agents` | `Agent(mcp_servers=[MCPServerStdio(...)])` |
|
|
20
|
+
| Claude Agent SDK | [claude_sdk_agent.py](claude_sdk_agent.py) | `claude-agent-sdk` | `ClaudeAgentOptions(mcp_servers={...})` |
|
|
21
|
+
|
|
22
|
+
Every example also needs `pip install "hypgraph[mcp]"`. [_story.py](_story.py) holds what they share: the record
|
|
23
|
+
before the agent arrives, the task, the server command, and the check at the end.
|
|
24
|
+
|
|
25
|
+
## Run them
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
cd examples/frameworks
|
|
29
|
+
python langgraph_agent.py # scripted model: offline, free, the same every time
|
|
30
|
+
python langgraph_agent.py --real --model gpt-4.1-mini
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
With no flags, a scripted model plays a careful agent's moves through the framework's own tool-calling path:
|
|
34
|
+
read the overview, overclaim, read the refusal, write the honest claim. That shows the wiring works, including the
|
|
35
|
+
part that matters most, a refused write getting back to the model. It can't show a model reasoning. `--real` uses a
|
|
36
|
+
real model (`OPENAI_API_KEY`, or whatever the framework's model string needs; `--model` or `MODEL` picks it). A real
|
|
37
|
+
model passes if it got a claim accepted and fixed every refusal, because a careful model may write the honest claim
|
|
38
|
+
the first time.
|
|
39
|
+
|
|
40
|
+
`--db FILE` keeps the record, so you can open it afterwards with `hypgraph --db FILE serve`.
|
|
41
|
+
|
|
42
|
+
The Claude Agent SDK drives Claude Code itself and has no scripted mode. `python claude_sdk_agent.py` is a real run
|
|
43
|
+
(Claude Code signed in, or `ANTHROPIC_API_KEY`; `--model` takes `haiku`, `sonnet` or `opus`). `--check` starts the
|
|
44
|
+
record's server from the exact options the SDK would use and confirms every allowed tool exists. That needs no model.
|
|
45
|
+
|
|
46
|
+
## What to copy
|
|
47
|
+
|
|
48
|
+
- **One server per author.** `hypgraph --db FILE --as analyst mcp` writes as `analyst` and nothing else. The agent
|
|
49
|
+
can't pass another name, and its verdicts count only if the investigation names it as a reviewer. Give each agent
|
|
50
|
+
in a team its own server, with its own author.
|
|
51
|
+
- **Let a refusal reach the model.** A refused write is an MCP tool error whose text names the problem and the fix
|
|
52
|
+
(for example `[SIGNIFICANCE_NOT_SHOWN]`). If the framework ends the run on a tool error, the agent never sees it:
|
|
53
|
+
- LangChain: `load_mcp_tools(session, handle_tool_errors=True)`, the adapter's default, returns it as the tool's
|
|
54
|
+
output, so `create_agent` needs nothing more. Hold one `client.session(...)` for the run: `client.get_tools()`
|
|
55
|
+
alone starts a server process for every tool call.
|
|
56
|
+
- LangGraph: `ToolNode(tools, handle_tool_errors=True)`.
|
|
57
|
+
- PydanticAI: the default (`tool_error_behavior="retry"`) sends it back as a retry prompt. `max_retries` bounds it.
|
|
58
|
+
- CrewAI and the OpenAI Agents SDK hand it back as the tool's output by default.
|
|
59
|
+
- Claude Code shows tool errors to the model.
|
|
60
|
+
- **Keep the agent on the record.** The Claude example passes `tools=[]` (no shell, no file edits),
|
|
61
|
+
`strict_mcp_config=True` (no other MCP servers) and pre-approves only the record's tools.
|
|
62
|
+
- **CrewAI names MCP tools after the command line** (`<command>_<args>_<tool>`, hashed past 64 characters). The
|
|
63
|
+
example runs plain `hypgraph mcp` with `HYPGRAPH_DB` and `HYPGRAPH_AUTHOR` in its environment, so the tools come out
|
|
64
|
+
as `hypgraph_mcp_add` and so on.
|
|
65
|
+
|
|
66
|
+
Frameworks that take plain Python functions as tools can skip MCP. Call `Graph` directly and return the refusal text
|
|
67
|
+
from `GraphError`; see [hypgraph.com/engineers](https://hypgraph.com/engineers/#connect).
|
|
68
|
+
|
|
69
|
+
Tested with langchain 1.4, langgraph 1.2, pydantic-ai 2.x, crewai 1.15, openai-agents 0.20 and claude-agent-sdk 0.2 (the scripted
|
|
70
|
+
runs, and the Claude `--check`, run in CI).
|
|
@@ -16,14 +16,14 @@ Standing is derived on every read, never stored; every write is an event in a SH
|
|
|
16
16
|
their numbers; reviews pin versions; independence is counted, not assumed. See https://hypgraph.com.
|
|
17
17
|
"""
|
|
18
18
|
|
|
19
|
-
__version__ = "0.7.
|
|
19
|
+
__version__ = "0.7.13"
|
|
20
20
|
|
|
21
|
-
from .bundle import verify_bundle # noqa: E402
|
|
21
|
+
from .bundle import anchored, verify_bundle # noqa: E402
|
|
22
22
|
from .graph import Author, Graph, GraphError, file_sha256 # noqa: E402
|
|
23
23
|
from .policy import Policy # noqa: E402
|
|
24
24
|
from .references import verify_reference # noqa: E402
|
|
25
25
|
from .schema import FORMAT, describe # noqa: E402
|
|
26
26
|
from .store import verify_file # noqa: E402
|
|
27
27
|
|
|
28
|
-
__all__ = ["Graph", "GraphError", "Policy", "Author", "verify_bundle", "verify_file", "file_sha256", "describe", "verify_reference",
|
|
28
|
+
__all__ = ["Graph", "GraphError", "Policy", "Author", "verify_bundle", "anchored", "verify_file", "file_sha256", "describe", "verify_reference",
|
|
29
29
|
"FORMAT", "__version__"]
|