hypgraph 0.7.11__tar.gz → 0.7.12__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.12}/AGENTS.md +6 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/CHANGELOG.md +59 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/PKG-INFO +7 -3
- {hypgraph-0.7.11 → hypgraph-0.7.12}/README.md +6 -2
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/PLAN.md +31 -0
- hypgraph-0.7.12/docs/RELEASE-READINESS.md +106 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/review-2026-10-24.md +15 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/spec.md +4 -1
- hypgraph-0.7.12/docs/verification.md +83 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/pyproject.toml +4 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/__init__.py +3 -3
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/blind.py +2 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/bundle.py +25 -2
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/cli.py +10 -5
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/coord.py +23 -3
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/graph.py +2 -2
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/mcp.py +2 -2
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/server.py +38 -9
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/skill/SKILL.md +3 -1
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/workflow.py +1 -2
- hypgraph-0.7.12/tests/test_anchoring.py +131 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_blind_oracles.py +98 -1
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_d10.py +1 -1
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_engine.py +1 -1
- hypgraph-0.7.12/tests/test_trust_boundary.py +183 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/.gitignore +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/CITATION.cff +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/DISCLAIMER.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/LICENSE +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/NOTICE +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/decisions/ADR-001-token-bound-authors.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/decisions/ADR-002-governance-profiles.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/profile-workflows-plan.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/site-plan.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/ui-plan.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/workflows/README.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/workflows/knowledge.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/workflows/optimization.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/workflows/scientific.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/workflows/software.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/docs/workflows/trading.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/__main__.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/checks.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/demos/__init__.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/demos/broad_street.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/derive.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/language.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/plan.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/policy.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/profiles.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/references.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/refusals.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/report_check.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/schema.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/stats.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/store.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/__init__.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/atlas.css +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/atlas.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/hypgraph.css +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/hypgraph.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/hypgraph.svg +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/index.html +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/LICENSES.md +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/cose-base.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/cytoscape-fcose.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/cytoscape.min.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/layout-base.js +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_accept_work_kind.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_blind.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_bound_support.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_bundle_telemetry.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_cancel_releases_lease.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_cited_and_failed_support.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_coord.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_engine_fixes.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_incremental.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_link_translate.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_log_and_check.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_measure_questions.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_opposed_answers.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_option_lead.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_order_detail.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_profiles.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_profiles_041.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_questions_not_assertions.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_references.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_refusal_friction.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_refusal_results.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_refusals.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_relation_words.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_report_answers.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_rerunnable.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_restates_scale.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_server_auth.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_server_hosts.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_shape_refusals.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_stats_not_backtests.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_stats_values.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_surfaces.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_telemetry_stream.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_ui_app.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_ui_engine.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_uncorrected_effect.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_unnamed_inputs.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_versions_not_figures.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/tests/test_vocabulary_friction.py +0 -0
- {hypgraph-0.7.11 → hypgraph-0.7.12}/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,64 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.12 — 2026-10-31: the trust boundary, verification and docs, reviewed before launch
|
|
4
|
+
|
|
5
|
+
A pre-launch review of who may write as whom, through every interface. Each fix has a test that failed first
|
|
6
|
+
(`tests/test_trust_boundary.py`).
|
|
7
|
+
|
|
8
|
+
- **A page on another port can't write.** `hypgraph serve` compared a write's `Origin` by host name only, so a page
|
|
9
|
+
served from another port of the same machine (a dev server, an agent-built page) could write to a server running
|
|
10
|
+
without tokens. A browser write must now come from the exact host and port the server was reached at;
|
|
11
|
+
`Origin: null` is refused. Clients that send no `Origin` are unaffected.
|
|
12
|
+
- **A `*` token can't write as a reviewer.** `--token SECRET=*` covered every non-reserved name, reviewers included,
|
|
13
|
+
so an agent holding one could review its own work officially under a reviewer's name. A name on a review board
|
|
14
|
+
(the policy's reviewers, or the ones an investigation names) must now be named on a token. Tokens that name their
|
|
15
|
+
authors are unchanged.
|
|
16
|
+
- **Only an order's issuer directs it.** `accept_work`, `rework` and `settle` didn't check who called them, so a
|
|
17
|
+
worker (through its MCP seat, say) could rework its own order with an easier `done_when`, meet it and accept it.
|
|
18
|
+
Now only the author who issued an order, or a curator, accepts or reworks it, and `settle` settles only the
|
|
19
|
+
orders its caller issued. HypSwarm's scheduler and lead (which act as the harness that issued the orders) and
|
|
20
|
+
HypMesh pass their suites unchanged.
|
|
21
|
+
- **A bad `Content-Length` is a 400.** A non-numeric one crashed the request handler and a negative one held its
|
|
22
|
+
thread until the client hung up.
|
|
23
|
+
- **A refused write gets its refusal.** The server read a write's body only after the origin check, and closing on
|
|
24
|
+
an unread body reset the connection on Windows, so a client saw "connection aborted" instead of the 403.
|
|
25
|
+
- **More blind adversarial tests:** graph operations on sealed nodes (link, retract, withdraw, revise, lease), the
|
|
26
|
+
work-order lifecycle as the checker (return, accept, rework, cancel, settle), every enumeration route, 25 guesses
|
|
27
|
+
in a row on one record, and eight MCP tools. The chain head is no longer shown to a sealed reader (`/verify`, the
|
|
28
|
+
MCP `verify` tool): it is a hash over sealed bodies, and a reader that is sealed has no use for it.
|
|
29
|
+
- **SECURITY.md rewritten** for what the record enforces, which interface is trusted, what tokens do and don't
|
|
30
|
+
protect (writes, not reads), what blind orders protect and where they don't apply, and what verification shows.
|
|
31
|
+
|
|
32
|
+
Verification against a published head, and a clean-install walkthrough in CI:
|
|
33
|
+
|
|
34
|
+
- **`hypgraph verify --head HEX`** (and `verify_bundle(b, head=...)`, `anchored(res, head)`) fails unless the chain
|
|
35
|
+
ends at a head published elsewhere. A chain only shows it is consistent with itself: whoever can write a record can
|
|
36
|
+
change a claim and recompute every hash, or cut the record short, and it still verifies. `tests/test_anchoring.py`
|
|
37
|
+
does both and shows each verifying on its own and failing against the published head. `verify` now prints the full
|
|
38
|
+
head, the thing to publish.
|
|
39
|
+
- **[docs/verification.md](docs/verification.md)** separates the four guarantees (internal consistency, not
|
|
40
|
+
rewritten since published, provenance of the evidence, truth of a claim) and shows how to publish and sign a head
|
|
41
|
+
with tools readers already have (a paper, a signed tag, `ssh-keygen -Y sign`, a timestamp).
|
|
42
|
+
- **`dev/e2e_install.py`** installs HypGraph into a fresh environment and does what the README and `--help` say, as
|
|
43
|
+
someone who has never seen the repository: a record, an experiment and its result, a claim accepted and one refused
|
|
44
|
+
with the honest version, a review, an export, and verification elsewhere with no graph file. CI runs it on the
|
|
45
|
+
built wheel (with the MCP extra) and on the sdist, on Ubuntu and Windows; the release job runs it before
|
|
46
|
+
publishing.
|
|
47
|
+
|
|
48
|
+
Docs reconciled, GitHub Releases, a linter in CI:
|
|
49
|
+
|
|
50
|
+
- **Docs match the code.** `docs/review-2026-10-24.md` gets a status table: each finding checked against 0.7.11 by
|
|
51
|
+
running it, with the evidence (eight resolved, one in part). `docs/PLAN.md` says what is done, what moved
|
|
52
|
+
(authentication, anchoring) and where HypGraph ends and HypSwarm, HypMesh and HypDMZ begin. The README lists the
|
|
53
|
+
work-order tools and points to SECURITY.md. AGENTS.md, the Agent Skill and llms.txt tell an agent holding a work
|
|
54
|
+
order to start with `my_work()`, and that a blind order's sealed tools are expected, not an error.
|
|
55
|
+
- **GitHub Releases.** The release job creates one for each tag after PyPI has the files: the changelog's section,
|
|
56
|
+
how to install, and where to check provenance (`dev/release_notes.py`, which you can run to preview).
|
|
57
|
+
- **[docs/RELEASE-READINESS.md](docs/RELEASE-READINESS.md):** the pre-launch review's findings, what was fixed and
|
|
58
|
+
tested, the limitations accepted, what is deferred, and the recommendation (conditional go).
|
|
59
|
+
- **pyflakes in CI** (`ruff check`, rules `F` only): undefined names and dead imports, not style. Five unused imports
|
|
60
|
+
and one unused variable removed.
|
|
61
|
+
|
|
3
62
|
## 0.7.11 — 2026-10-30: a sealed checker can't learn the answer by asking
|
|
4
63
|
|
|
5
64
|
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.12
|
|
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,12 @@ 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).
|
|
178
182
|
|
|
179
183
|
## Wire it into your system
|
|
180
184
|
|
|
@@ -141,8 +141,12 @@ 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).
|
|
146
150
|
|
|
147
151
|
## Wire it into your system
|
|
148
152
|
|
|
@@ -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.12 (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,106 @@
|
|
|
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
|
+
## Recommendation: CONDITIONAL GO
|
|
8
|
+
|
|
9
|
+
HypGraph is ready for a public developer preview once #59, #60 and #61 are merged with green CI and released as one
|
|
10
|
+
version. The review found five defects at the trust boundary and two gaps in verification. Each is fixed in those
|
|
11
|
+
PRs, with a regression test that failed first. No confirmed security, integrity or correctness defect remains open.
|
|
12
|
+
The conditions are small, and the limitations below are documented where a user will meet them.
|
|
13
|
+
|
|
14
|
+
**Conditions**
|
|
15
|
+
|
|
16
|
+
1. Merge #59, then #60, then #61, each with green CI. They all touch the top of the changelog, so main gets merged
|
|
17
|
+
into the next one in line.
|
|
18
|
+
2. Release them as one version through the usual release PR, tag and PyPI check. That release is the first to create
|
|
19
|
+
a GitHub Release by itself.
|
|
20
|
+
3. Make the `ui`, `install` and `lint` jobs required checks in the `protect main` ruleset. Today only the 12 `test`
|
|
21
|
+
jobs are required. This is a repository setting, so it's the operator's call.
|
|
22
|
+
|
|
23
|
+
**Where the conditions stand.** 1: #59, #60 and #61 are merged, each with green CI; on main after the merges the
|
|
24
|
+
suite is 343 passed. 2: released as 0.7.12. 3: open, for the operator.
|
|
25
|
+
|
|
26
|
+
## What was reviewed
|
|
27
|
+
|
|
28
|
+
The threat model is in [SECURITY.md](../SECURITY.md):
|
|
29
|
+
- **Trusted callers:** the Python API and the CLI. Whoever holds the file owns the record.
|
|
30
|
+
- **Untrusted callers:** agents at `hypgraph serve` and `hypgraph mcp`.
|
|
31
|
+
- **The host's job:** who can read the port or the file, who holds which token, and where a record's head is
|
|
32
|
+
published.
|
|
33
|
+
|
|
34
|
+
Interfaces examined: the Python API, the CLI, the HTTP server (`server.py`), the MCP server (`mcp.py`), blind work
|
|
35
|
+
orders (`blind.py`, `coord.py`), and bundle export and verification (`bundle.py`, `store.py`).
|
|
36
|
+
|
|
37
|
+
## Findings
|
|
38
|
+
|
|
39
|
+
| # | Finding | Class | Status | Evidence |
|
|
40
|
+
|---|---|---|---|---|
|
|
41
|
+
| 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` |
|
|
42
|
+
| 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` |
|
|
43
|
+
| 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. |
|
|
44
|
+
| 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` |
|
|
45
|
+
| 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 |
|
|
46
|
+
| 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` |
|
|
47
|
+
| 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. |
|
|
48
|
+
| 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` |
|
|
49
|
+
| 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 |
|
|
50
|
+
| 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 | — |
|
|
51
|
+
| 11 | No GitHub Releases for 24 tags. | Release process | Fixed in #61 for future tags | `dev/release_notes.py` |
|
|
52
|
+
| 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 |
|
|
53
|
+
| 13 | No linter. | Release process | pyflakes rules in CI in #61; 6 findings fixed | — |
|
|
54
|
+
| 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. |
|
|
55
|
+
|
|
56
|
+
Checked and holding, with no change needed:
|
|
57
|
+
- reserved names need a token that names them;
|
|
58
|
+
- official self-review is refused through every interface;
|
|
59
|
+
- the HTTP write takes no time, attribution, id or code from the writer;
|
|
60
|
+
- the MCP seat can't start as a reserved name;
|
|
61
|
+
- only the lease holder releases a lease, and only a link's author, a reviewer or the operator retracts a link;
|
|
62
|
+
- the release job checks the tag against the version;
|
|
63
|
+
- PyPI publishing is trusted and carries a provenance attestation;
|
|
64
|
+
- every tool name in the agent docs exists on the MCP server, and every hypgraph.com page the README links answers.
|
|
65
|
+
|
|
66
|
+
## Verification report
|
|
67
|
+
|
|
68
|
+
| | Result |
|
|
69
|
+
|---|---|
|
|
70
|
+
| Full suite, each branch, Windows 11, Python 3.13 | #59: 338 passed · #60: 320 passed · #61: 315 passed. 0.7.11 had 315. |
|
|
71
|
+
| 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. |
|
|
72
|
+
| Clean install of the built wheel with the MCP extra | 21 of 21 documented steps |
|
|
73
|
+
| Clean install of the sdist | 20 of 20 |
|
|
74
|
+
| Clean install of `hypgraph==0.7.11` from PyPI | 19 of 20. The failing step is `verify --head`, which is new in #60. |
|
|
75
|
+
| 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. |
|
|
76
|
+
| Downstream | HypSwarm 119 passed, 6 skipped; HypMesh 37 passed, both against #59 |
|
|
77
|
+
|
|
78
|
+
## Accepted limitations
|
|
79
|
+
|
|
80
|
+
These are documented in SECURITY.md and docs/verification.md, where a user meets them.
|
|
81
|
+
|
|
82
|
+
- **Names aren't people.** The record can't tell that two author names are one agent. Review independence holds
|
|
83
|
+
only as far as names are authenticated: named tokens, or one MCP seat per agent. A server with `--writable` and
|
|
84
|
+
no tokens authenticates nobody.
|
|
85
|
+
- **Reads aren't authenticated.** `hypgraph serve` serves every `GET` to whoever can reach the port. Keep it on
|
|
86
|
+
loopback, or behind a proxy that authenticates readers.
|
|
87
|
+
- **Blind orders need a host that seals.** The MCP seat and HypMesh seal; plain `hypgraph serve` and the Python API
|
|
88
|
+
don't. Reads made before the order can't be undone. The leak check catches numbers quoted by accident, not a lead
|
|
89
|
+
leaking on purpose. Timing isn't hidden.
|
|
90
|
+
- **A head is only as good as where it's published.** `verify --head` proves the record is the one that was
|
|
91
|
+
published. Who published that head is for the signature, the paper or the tag to establish.
|
|
92
|
+
- **A single-number blind check is never marked as agreeing.** Results restate each other only when they carry two
|
|
93
|
+
or more numbers, a guard against coincidence. A blind check of one count is recorded as written blind, but not as
|
|
94
|
+
`agrees_blind`. It's documented in the changelog, not yet changed.
|
|
95
|
+
|
|
96
|
+
## Deferred until after launch
|
|
97
|
+
|
|
98
|
+
- **Comparative evaluation.** Does recording through HypGraph reduce unsupported claims in agents' final reports?
|
|
99
|
+
The design: the same model, tools, tasks and budget, with and without the record, scored against criteria fixed
|
|
100
|
+
in advance by a scorer that isn't HypGraph. The measures would be unsupported claims, wrong numbers, overstated
|
|
101
|
+
certainty, honest claims wrongly refused, completion and cost. It needs a preregistration and a budget decision,
|
|
102
|
+
and no result is claimed until it has run.
|
|
103
|
+
- **Coverage reporting.** The security-sensitive paths have targeted tests: the trust boundary, the blind oracles,
|
|
104
|
+
anchoring, the bundle negatives. A coverage percentage would add little to that.
|
|
105
|
+
- **GitHub Releases for the 24 past tags.** `dev/release_notes.py` can write the notes for each; publishing them is
|
|
106
|
+
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
|
|
@@ -118,7 +118,10 @@ keep it in a record of its own.
|
|
|
118
118
|
|
|
119
119
|
**Anchoring.** A bundle proves only its own consistency. To prove it wasn't rebuilt from scratch, publish its `head`
|
|
120
120
|
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.
|
|
121
|
+
passes through that hash can't have rewritten anything before it. A verifier given a published head (the full hash,
|
|
122
|
+
or a prefix of at least 16 hex characters) fails unless the chain ends there: `hypgraph verify FILE --head HEX`,
|
|
123
|
+
`verify_bundle(b, head=HEX)`. A bundle without a `head` field is checked for consistency only. How a head is
|
|
124
|
+
published and signed, and what each check does and doesn't show: [verification.md](verification.md).
|
|
122
125
|
|
|
123
126
|
## 5. Derived standing (normative)
|
|
124
127
|
|
|
@@ -0,0 +1,83 @@
|
|
|
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, and every node, version, link, withdrawal and retraction matches the event that wrote it. | `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.
|
|
28
|
+
head 565123f3a7ac06ed18ab555935fde0457ebb6a302dc188fc83dbf36af579623f
|
|
29
|
+
consistent with itself; to rule out a rewrite, check it against a published head (--head)
|
|
30
|
+
$ hypgraph verify study.bundle.json --head 565123f3a7ac06ed
|
|
31
|
+
✓ study.bundle.json: 59 events verified — chain intact, every row matches the event that wrote it.
|
|
32
|
+
head 565123f3a7ac06ed18ab555935fde0457ebb6a302dc188fc83dbf36af579623f
|
|
33
|
+
matches the anchored head: not rewritten or cut short since it was published
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
(Your head will differ: node ids and times are part of what is hashed.)
|
|
37
|
+
|
|
38
|
+
Publish that head somewhere you don't control after the fact. Any of these is enough, and none needs new
|
|
39
|
+
infrastructure:
|
|
40
|
+
|
|
41
|
+
- **In the paper, preregistration or report** that relies on the record: "Record head: `565123f3a7ac…`".
|
|
42
|
+
- **As a release asset or in a signed tag** of the repository that holds the work: `git tag -s study-v1 -m "head 565123f3…"`.
|
|
43
|
+
- **Signed with a key your readers already trust**, using tools they already have:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
hypgraph verify study.bundle.json --json | python -c "import json,sys; print(json.load(sys.stdin)['head'])" > study.head
|
|
47
|
+
ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n hypgraph-head study.head # writes study.head.sig
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
and a reader checks the signature, then the record against it:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
ssh-keygen -Y verify -f allowed_signers -I you@example.org -n hypgraph-head -s study.head.sig < study.head
|
|
54
|
+
hypgraph verify study.bundle.json --head "$(cat study.head)"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
- **With a third-party timestamp** (an RFC 3161 service, or any public notarisation) over `study.head`, if you need
|
|
58
|
+
to show *when*.
|
|
59
|
+
|
|
60
|
+
A record keeps growing. Publish the head of each version you rely on; a later bundle still verifies, and its chain
|
|
61
|
+
passes through every earlier head (an earlier head is the `hash` of one of its events).
|
|
62
|
+
|
|
63
|
+
## Checking without HypGraph
|
|
64
|
+
|
|
65
|
+
The bundle stores every event and every version body as the exact string that was hashed. A verifier only runs
|
|
66
|
+
SHA-256 over strings and compares: no JSON canonicalisation to reimplement. The record format, including the bundle
|
|
67
|
+
and the verifier's rules, is in [spec.md](spec.md). The site checks bundles in the browser with WebCrypto, from a
|
|
68
|
+
separate implementation.
|
|
69
|
+
|
|
70
|
+
## Scoped bundles and references
|
|
71
|
+
|
|
72
|
+
- `hypgraph export --inv INV` writes one investigation. Events outside it are redacted to their hash, so the chain
|
|
73
|
+
still verifies, but their content can't be checked; the verifier says how many. The full record rules out a change
|
|
74
|
+
hidden among them.
|
|
75
|
+
- A source that pins another record's node checks that the cited body still hashes to the pinned version. It doesn't
|
|
76
|
+
check the cited record's history: for that, verify that record against its own published head.
|
|
77
|
+
|
|
78
|
+
## Try it
|
|
79
|
+
|
|
80
|
+
`dev/e2e_install.py` installs HypGraph into a fresh environment and walks the whole path: a record, a claim accepted
|
|
81
|
+
and one refused, a review, an export, and verification in another directory with no graph file, on its own and
|
|
82
|
+
against the head, and failing on an edited copy. `tests/test_anchoring.py` rewrites a record (changing a claim and
|
|
83
|
+
recomputing every hash) and cuts one short: both verify on their own, and both fail against the published head.
|
|
@@ -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.12"
|
|
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__"]
|
|
@@ -420,6 +420,8 @@ def dispatch(g, method: str, path: str, *, query: dict | None = None, body: dict
|
|
|
420
420
|
status, out = plain(g, method, path, query=query, body=body, **kw)
|
|
421
421
|
if head == "search" and status == 200 and isinstance(out, dict) and isinstance(out.get("results"), list):
|
|
422
422
|
out = out | {"results": v.search(out["results"])}
|
|
423
|
+
if head == "verify" and status == 200 and isinstance(out, dict) and "head" in out:
|
|
424
|
+
out = out | {"head": SEALED} # a hash over sealed bodies: no use to a sealed reader, so not shown
|
|
423
425
|
return status, v.answer(status, out)
|
|
424
426
|
|
|
425
427
|
|
|
@@ -135,8 +135,31 @@ def derive_views(g: "Graph", invs: list[str]) -> dict:
|
|
|
135
135
|
return views
|
|
136
136
|
|
|
137
137
|
|
|
138
|
-
def
|
|
139
|
-
"""
|
|
138
|
+
def anchored(res: dict, head: str) -> dict:
|
|
139
|
+
"""A verification held against a head published elsewhere (a paper, a signed tag, a release asset, a timestamp).
|
|
140
|
+
A chain only shows it is consistent with itself: whoever can write the record can rewrite it and recompute every
|
|
141
|
+
hash, or cut it short. Matching a head its holder can't change since rules both out. ``head`` is the full hash or a
|
|
142
|
+
prefix of at least 16 hex characters."""
|
|
143
|
+
want = str(head or "").strip().lower()
|
|
144
|
+
if not want or not res.get("ok"):
|
|
145
|
+
return res
|
|
146
|
+
if len(want) < 16 or any(c not in "0123456789abcdef" for c in want):
|
|
147
|
+
return {**res, "ok": False, "problem": "the anchor must be the head's hash, or at least its first 16 hex characters"}
|
|
148
|
+
got = str(res.get("head") or "")
|
|
149
|
+
if not got.startswith(want):
|
|
150
|
+
return {**res, "ok": False, "anchored": False,
|
|
151
|
+
"problem": f"the chain ends at {got[:16]}…, not at the anchored head {want[:16]}…: this is not the "
|
|
152
|
+
"record that was published (rewritten, cut short, or another record)"}
|
|
153
|
+
return {**res, "anchored": True}
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def verify_bundle(b: dict, head: str = "") -> dict:
|
|
157
|
+
"""Check a bundle string-for-string: the chain, then every row against the event that wrote it. With ``head``,
|
|
158
|
+
also that the chain ends at that published head (see ``anchored``)."""
|
|
159
|
+
return anchored(_verify_bundle(b), head)
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _verify_bundle(b: dict) -> dict:
|
|
140
163
|
if not isinstance(b, dict) or b.get("format") != BUNDLE_FORMAT:
|
|
141
164
|
return {"ok": False, "problem": f"not a {BUNDLE_FORMAT} bundle"}
|
|
142
165
|
prev, checked, red = GENESIS, 0, 0
|
|
@@ -30,7 +30,7 @@ import sys
|
|
|
30
30
|
from pathlib import Path
|
|
31
31
|
|
|
32
32
|
from . import __version__
|
|
33
|
-
from .bundle import verify_bundle
|
|
33
|
+
from .bundle import anchored, verify_bundle
|
|
34
34
|
from .graph import Graph, GraphError
|
|
35
35
|
from .schema import TYPES, describe
|
|
36
36
|
from .store import verify_file
|
|
@@ -276,12 +276,15 @@ def cmd_report(args) -> int:
|
|
|
276
276
|
def cmd_verify(args) -> int:
|
|
277
277
|
target = args.target or args.db
|
|
278
278
|
if str(target).endswith(".json"):
|
|
279
|
-
res = verify_bundle(json.loads(Path(target).read_text(encoding="utf-8")))
|
|
279
|
+
res = verify_bundle(json.loads(Path(target).read_text(encoding="utf-8")), head=args.head)
|
|
280
280
|
else:
|
|
281
|
-
res = verify_file(target)
|
|
281
|
+
res = anchored(verify_file(target), args.head)
|
|
282
282
|
ok = res.get("ok")
|
|
283
283
|
text = (f"✓ {target}: {res.get('checked')} events verified — chain intact, every row matches the event that "
|
|
284
|
-
f"wrote it
|
|
284
|
+
f"wrote it.\n head {res.get('head', '')}" if ok else f"✗ {target}: {res.get('problem')}")
|
|
285
|
+
if ok:
|
|
286
|
+
text += ("\n matches the anchored head: not rewritten or cut short since it was published" if res.get("anchored")
|
|
287
|
+
else "\n consistent with itself; to rule out a rewrite, check it against a published head (--head)")
|
|
285
288
|
if res.get("warning"):
|
|
286
289
|
text += "\n note: " + res["warning"]
|
|
287
290
|
_out(args, res, text)
|
|
@@ -505,6 +508,8 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
505
508
|
s.add_argument("-o", "--output", default="")
|
|
506
509
|
s = cmd("verify", cmd_verify, "check a graph file or a bundle")
|
|
507
510
|
s.add_argument("target", nargs="?", default="")
|
|
511
|
+
s.add_argument("--head", default="", help="the head published for this record (or its first 16+ hex characters): "
|
|
512
|
+
"fail unless the chain ends there")
|
|
508
513
|
s = cmd("export", cmd_export, "write a verifiable bundle")
|
|
509
514
|
s.add_argument("--inv", default="", help="one investigation (events outside it are redacted)")
|
|
510
515
|
s.add_argument("-o", "--output", default="")
|
|
@@ -546,7 +551,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
546
551
|
help="a swarm's telemetry sidecar to stream (default: <db>.telemetry.jsonl, picked up when it appears)")
|
|
547
552
|
s.add_argument("--no-telemetry", action="store_true", help="don't serve or stream telemetry")
|
|
548
553
|
s.add_argument("--token", action="append", metavar="SECRET[=AUTHORS]",
|
|
549
|
-
help="bind writes to a bearer token: SECRET=a,b (those authors) or SECRET=* (any
|
|
554
|
+
help="bind writes to a bearer token: SECRET=a,b (those authors) or SECRET=* (any name not reserved and not on a review board); "
|
|
550
555
|
"repeatable; $HYPGRAPH_TOKEN adds one. With tokens, unauthenticated writes are 401.")
|
|
551
556
|
s.add_argument("--token-file", default="", help="a file with one SECRET[=AUTHORS] per line")
|
|
552
557
|
s = cmd("mcp", cmd_mcp, "an MCP server for agents (needs hypgraph[mcp])")
|
|
@@ -490,10 +490,28 @@ def return_work(g: "Graph", *, author: str, order: str, note: str = "") -> dict:
|
|
|
490
490
|
return check_work(g, order)
|
|
491
491
|
|
|
492
492
|
|
|
493
|
+
def directs(s: D.Snap, author: str, order: str) -> bool:
|
|
494
|
+
"""Who may accept, rework or settle an order: the author who issued it, or a curator (operator, importer). An
|
|
495
|
+
assignee reworking its own order could rewrite what counts as done, meet that and accept it."""
|
|
496
|
+
return author == s.nodes[order]["created_by"] or author in s.policy.curators
|
|
497
|
+
|
|
498
|
+
|
|
499
|
+
def _must_direct(s: D.Snap, author: str, order: str, what: str) -> None:
|
|
500
|
+
from .graph import GraphError
|
|
501
|
+
if not directs(s, author, order):
|
|
502
|
+
raise GraphError(f"only {s.nodes[order]['created_by']}, who issued {_code(s, order)}, or the "
|
|
503
|
+
f"{s.policy.operator} {what} it")
|
|
504
|
+
|
|
505
|
+
|
|
493
506
|
def accept_work(g: "Graph", *, author: str, order: str, reason: str = "", text: str = "") -> dict:
|
|
494
507
|
"""Accept an order whose predicates are all met: a decision settling it, based_on the claims and results that
|
|
495
|
-
met them (pinned to their versions, so the decision is flagged REVISIT if they change).
|
|
508
|
+
met them (pinned to their versions, so the decision is flagged REVISIT if they change). Only its issuer (or a
|
|
509
|
+
curator) accepts it."""
|
|
496
510
|
from .graph import GraphError
|
|
511
|
+
s0 = g.snapshot()
|
|
512
|
+
if not _is_order(s0, order):
|
|
513
|
+
raise GraphError(f"{order} is not a work order")
|
|
514
|
+
_must_direct(s0, author, order, "accepts")
|
|
497
515
|
chk = check_work(g, order, text)
|
|
498
516
|
if not chk["all_met"]:
|
|
499
517
|
missing = "; ".join(c["why"] or c["p"] for c in chk["predicates"] if not c["met"])
|
|
@@ -520,6 +538,7 @@ def rework(g: "Graph", *, author: str, order: str, missing: str, done_when: list
|
|
|
520
538
|
s = g.snapshot()
|
|
521
539
|
if not _is_order(s, order):
|
|
522
540
|
raise GraphError(f"{order} is not a work order")
|
|
541
|
+
_must_direct(s, author, order, "reworks")
|
|
523
542
|
if len(missing.strip()) < 10:
|
|
524
543
|
raise GraphError("missing: say what the return lacked")
|
|
525
544
|
b = s.nodes[order]["body"]
|
|
@@ -843,10 +862,11 @@ def question_board(g: "Graph", inv: str) -> list[dict]:
|
|
|
843
862
|
|
|
844
863
|
def settle(g: "Graph", *, author: str, inv: str) -> list[dict]:
|
|
845
864
|
"""Accept every returned order whose predicates are all met — the mechanical half of the lead's job, done by
|
|
846
|
-
the record. Returns what it accepted."""
|
|
865
|
+
the record. Only the orders this author issued (every order, for a curator). Returns what it accepted."""
|
|
847
866
|
out = []
|
|
867
|
+
s = g.snapshot()
|
|
848
868
|
for o in orders(g, inv, status="returned"):
|
|
849
|
-
if check_work(g, o["id"])["all_met"]:
|
|
869
|
+
if directs(s, author, o["id"]) and check_work(g, o["id"])["all_met"]:
|
|
850
870
|
a = accept_work(g, author=author, order=o["id"], reason="settled by the record: every predicate met")
|
|
851
871
|
out.append({"order": o["code"], "assignee": o["assignee"], "decision": a["decision"]})
|
|
852
872
|
return out
|
|
@@ -22,9 +22,9 @@ import sqlite3
|
|
|
22
22
|
import sys
|
|
23
23
|
import threading
|
|
24
24
|
from collections import defaultdict
|
|
25
|
-
from datetime import datetime, timedelta
|
|
25
|
+
from datetime import datetime, timedelta
|
|
26
26
|
from pathlib import Path
|
|
27
|
-
from typing import
|
|
27
|
+
from typing import Callable, Optional
|
|
28
28
|
|
|
29
29
|
from . import profiles
|
|
30
30
|
from . import derive as D
|
|
@@ -26,7 +26,6 @@ from pathlib import Path
|
|
|
26
26
|
from typing import Any, Optional
|
|
27
27
|
|
|
28
28
|
from . import blind as B
|
|
29
|
-
from . import profiles
|
|
30
29
|
from . import __version__
|
|
31
30
|
from .graph import Graph, GraphError, file_sha256
|
|
32
31
|
from .schema import TYPES, describe
|
|
@@ -482,7 +481,8 @@ def build(graph: Graph | str, author: Optional[str] = None, files_root: str | No
|
|
|
482
481
|
def verify() -> str:
|
|
483
482
|
"""Recompute the hash chain and check every stored version and link against the event that wrote it."""
|
|
484
483
|
v = g.verify()
|
|
485
|
-
|
|
484
|
+
head = "sealed while your blind order is open" if sealed() else f"{v['head'][:16]}…" # a hash over sealed bodies
|
|
485
|
+
return (f"Verified {v['checked']} events: chain intact, every row matches its event (head {head})."
|
|
486
486
|
if v["ok"] else f"VERIFY FAILED: {v['problem']}")
|
|
487
487
|
|
|
488
488
|
@tool
|