hypgraph 0.7.10__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.
Files changed (108) hide show
  1. {hypgraph-0.7.10 → hypgraph-0.7.12}/AGENTS.md +6 -0
  2. {hypgraph-0.7.10 → hypgraph-0.7.12}/CHANGELOG.md +83 -0
  3. {hypgraph-0.7.10 → hypgraph-0.7.12}/PKG-INFO +7 -3
  4. {hypgraph-0.7.10 → hypgraph-0.7.12}/README.md +6 -2
  5. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/PLAN.md +31 -0
  6. hypgraph-0.7.12/docs/RELEASE-READINESS.md +106 -0
  7. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/review-2026-10-24.md +15 -0
  8. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/spec.md +9 -1
  9. hypgraph-0.7.12/docs/verification.md +83 -0
  10. {hypgraph-0.7.10 → hypgraph-0.7.12}/pyproject.toml +4 -0
  11. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/__init__.py +3 -3
  12. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/blind.py +39 -8
  13. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/bundle.py +25 -2
  14. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/cli.py +10 -5
  15. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/coord.py +38 -9
  16. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/graph.py +83 -4
  17. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/mcp.py +7 -5
  18. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/server.py +38 -9
  19. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/skill/SKILL.md +3 -1
  20. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/workflow.py +1 -2
  21. hypgraph-0.7.12/tests/test_anchoring.py +131 -0
  22. hypgraph-0.7.12/tests/test_blind_oracles.py +288 -0
  23. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_d10.py +1 -1
  24. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_engine.py +1 -1
  25. hypgraph-0.7.12/tests/test_trust_boundary.py +183 -0
  26. {hypgraph-0.7.10 → hypgraph-0.7.12}/.gitignore +0 -0
  27. {hypgraph-0.7.10 → hypgraph-0.7.12}/CITATION.cff +0 -0
  28. {hypgraph-0.7.10 → hypgraph-0.7.12}/DISCLAIMER.md +0 -0
  29. {hypgraph-0.7.10 → hypgraph-0.7.12}/LICENSE +0 -0
  30. {hypgraph-0.7.10 → hypgraph-0.7.12}/NOTICE +0 -0
  31. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/decisions/ADR-001-token-bound-authors.md +0 -0
  32. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/decisions/ADR-002-governance-profiles.md +0 -0
  33. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/profile-workflows-plan.md +0 -0
  34. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/site-plan.md +0 -0
  35. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/ui-plan.md +0 -0
  36. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/workflows/README.md +0 -0
  37. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/workflows/knowledge.md +0 -0
  38. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/workflows/optimization.md +0 -0
  39. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/workflows/scientific.md +0 -0
  40. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/workflows/software.md +0 -0
  41. {hypgraph-0.7.10 → hypgraph-0.7.12}/docs/workflows/trading.md +0 -0
  42. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/__main__.py +0 -0
  43. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/checks.py +0 -0
  44. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/demos/__init__.py +0 -0
  45. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/demos/broad_street.py +0 -0
  46. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/derive.py +0 -0
  47. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/language.py +0 -0
  48. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/plan.py +0 -0
  49. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/policy.py +0 -0
  50. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/profiles.py +0 -0
  51. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/references.py +0 -0
  52. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/refusals.py +0 -0
  53. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/report_check.py +0 -0
  54. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/schema.py +0 -0
  55. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/stats.py +0 -0
  56. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/store.py +0 -0
  57. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/__init__.py +0 -0
  58. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/atlas.css +0 -0
  59. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/atlas.js +0 -0
  60. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/hypgraph.css +0 -0
  61. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/hypgraph.js +0 -0
  62. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/hypgraph.svg +0 -0
  63. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/index.html +0 -0
  64. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/LICENSES.md +0 -0
  65. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/cose-base.js +0 -0
  66. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/cytoscape-fcose.js +0 -0
  67. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/cytoscape.min.js +0 -0
  68. {hypgraph-0.7.10 → hypgraph-0.7.12}/src/hypgraph/ui/vendor/layout-base.js +0 -0
  69. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_accept_work_kind.py +0 -0
  70. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_blind.py +0 -0
  71. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_bound_support.py +0 -0
  72. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_bundle_telemetry.py +0 -0
  73. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_cancel_releases_lease.py +0 -0
  74. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_cited_and_failed_support.py +0 -0
  75. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_coord.py +0 -0
  76. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_engine_fixes.py +0 -0
  77. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_incremental.py +0 -0
  78. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_link_translate.py +0 -0
  79. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_log_and_check.py +0 -0
  80. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_measure_questions.py +0 -0
  81. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_opposed_answers.py +0 -0
  82. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_option_lead.py +0 -0
  83. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_order_detail.py +0 -0
  84. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_profiles.py +0 -0
  85. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_profiles_041.py +0 -0
  86. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_questions_not_assertions.py +0 -0
  87. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_references.py +0 -0
  88. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_refusal_friction.py +0 -0
  89. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_refusal_results.py +0 -0
  90. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_refusals.py +0 -0
  91. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_relation_words.py +0 -0
  92. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_report_answers.py +0 -0
  93. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_rerunnable.py +0 -0
  94. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_restates_scale.py +0 -0
  95. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_server_auth.py +0 -0
  96. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_server_hosts.py +0 -0
  97. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_shape_refusals.py +0 -0
  98. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_stats_not_backtests.py +0 -0
  99. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_stats_values.py +0 -0
  100. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_surfaces.py +0 -0
  101. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_telemetry_stream.py +0 -0
  102. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_ui_app.py +0 -0
  103. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_ui_engine.py +0 -0
  104. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_uncorrected_effect.py +0 -0
  105. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_unnamed_inputs.py +0 -0
  106. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_versions_not_figures.py +0 -0
  107. {hypgraph-0.7.10 → hypgraph-0.7.12}/tests/test_vocabulary_friction.py +0 -0
  108. {hypgraph-0.7.10 → 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,88 @@
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
+
62
+ ## 0.7.11 — 2026-10-30: a sealed checker can't learn the answer by asking
63
+
64
+ An adversarial test on a local HypMesh planted a 5-digit reading and 12-digit tags in a lead's sealed nodes and
65
+ attacked every route as the blind checker. Nothing leaked directly, but the checker could tell a right guess from a
66
+ wrong one, and 60 requests recovered the reading exactly. Fixed:
67
+
68
+ - **Errors no longer mark a right guess.** Answers scrubbed only the numbers the sealed material carries, so a route
69
+ that echoes its input (`resolve`, `node`, `why`, `order`, `check_work`, a refused write) answered "no node
70
+ '[sealed]'" for a right guess and "no node '48220'" for a wrong one. While a reader is sealed, every number in an
71
+ error is now blanked, secret or not; the MCP seat does the same.
72
+ - **A write is answered with the view after it.** The checker's own new numbers were scrubbed with the view from
73
+ before the write, so a result carrying the right reading came back "[sealed]".
74
+ - **No check reads sealed material for a sealed writer.** A claim bound to the sealed result was refused with an
75
+ unbound number for a wrong guess and passed that check for the right one, and the auto-bind looked the guess up
76
+ in the sealed results without any id given. A sealed writer may now link to a sealed node only to say its own work
77
+ supports, challenges or tests a hypothesis; binding to, resting on, reviewing, revising or ordering work on sealed
78
+ nodes is refused with one message before any check runs, and a seat holding a blind order issues no orders.
79
+ `Graph.sealed_from(hide)` lets a host apply its reader's view to writes, so writing under another name doesn't
80
+ escape the seal.
81
+ - **The leak check at issue skips what is sealed from the issuer**, which would otherwise answer the issuer's guesses.
82
+
83
+ `tests/test_blind_oracles.py` asks every request with the right and a wrong guess on fresh records and requires the
84
+ same answer; 14 of its 23 tests fail on 0.7.10.
85
+
3
86
  ## 0.7.10 — 2026-10-30: fixes from the first live blind run
4
87
 
5
88
  Claude led a question on a HypMesh and issued a blind order; Codex took the order through its seat and counted the
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: hypgraph
3
- Version: 0.7.10
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`. The method is in [AGENTS.md](https://github.com/voodoomods/hypgraph/blob/main/AGENTS.md); the short version is
177
- [llms.txt](https://hypgraph.com/llms.txt).
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`. The method is in [AGENTS.md](https://github.com/voodoomods/hypgraph/blob/main/AGENTS.md); the short version is
145
- [llms.txt](https://hypgraph.com/llms.txt).
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
 
@@ -162,6 +165,11 @@ Implementations must derive these, never store them:
162
165
  - Nobody officially reviews their own node.
163
166
  - Writes into an `archived` or `published` investigation are refused (reserved authors excepted).
164
167
  - Only the importer may set a write's time. Everyone else's comes from the writer's clock.
168
+ - A writer sealed from nodes (it holds an open blind work order, or a host passes its reader's view with
169
+ `Graph.sealed_from`) may link to a sealed node only to say its own work `supports`, `challenges` or `tests` a
170
+ hypothesis. It may not bind a measurement to a sealed result, rest a claim on sealed work, review or revise a sealed
171
+ node, or issue a work order on sealed work, and a seat holding a blind order issues no orders. These are refused
172
+ with one message, before any check reads the sealed material, so that no answer depends on what is sealed.
165
173
 
166
174
  ## 7. Claim checks
167
175
 
@@ -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.
@@ -55,3 +55,7 @@ pythonpath = ["src"]
55
55
 
56
56
  [tool.ruff]
57
57
  line-length = 120
58
+
59
+ [tool.ruff.lint]
60
+ # pyflakes: undefined names, unused imports and variables, shadowed definitions. CI runs it on src and tests.
61
+ select = ["F"]
@@ -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.10"
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__"]
@@ -21,6 +21,11 @@ The record enforces what it can see:
21
21
  wrote a node. ``hypgraph serve`` and the Python API read the whole record: a file is only as blind as whoever
22
22
  holds it.
23
23
 
24
+ A sealed reader can't learn what is sealed by asking either: an error that echoes its request has every number
25
+ blanked (not only the secret ones, which would mark a right guess), a write is answered with the view after it, and a
26
+ sealed writer's writes may not rest on sealed nodes, so no check reads them on its behalf (``graph.sealed_from``).
27
+ ``tests/test_blind_oracles.py`` asks every request with a right and a wrong guess and requires the same answer.
28
+
24
29
  It cannot see reads. A seat that read the record before its order was issued has already seen what is now sealed;
25
30
  give a checker its order first.
26
31
  """
@@ -275,6 +280,26 @@ class View:
275
280
  return [self.scrub(v) for v in x]
276
281
  return x
277
282
 
283
+ def blank(self, x: Any) -> Any:
284
+ """Every significant number replaced, secret or not: for answers that may echo what the reader sent (errors,
285
+ refusals). Scrubbing only the secret ones there would mark a right guess as "[sealed]" and leave a wrong one
286
+ as written — an oracle (an adversarial run found six routes that did, 2026-10-30)."""
287
+ if not self:
288
+ return x
289
+ if isinstance(x, str):
290
+ return _NUM.sub(lambda m: "[number]" if _significant(canon(m.group(0))) else m.group(0), x)
291
+ if isinstance(x, dict):
292
+ return {k: self.blank(v) for k, v in x.items()}
293
+ if isinstance(x, list):
294
+ return [self.blank(v) for v in x]
295
+ return x
296
+
297
+ def answer(self, status: int, out: Any) -> Any:
298
+ """A response as this reader gets it: redacted, and with every number blanked when it is an error."""
299
+ if not self:
300
+ return out
301
+ return self.blank(self._walk(out)) if status >= 400 else self.apply(out)
302
+
278
303
  def node(self, d: dict) -> dict:
279
304
  """A sealed node as a reader sees it: what it is and where, not what it says."""
280
305
  code = self.hide.get(d.get("id"), "")
@@ -378,26 +403,32 @@ def dispatch(g, method: str, path: str, *, query: dict | None = None, body: dict
378
403
  parts = [p for p in path.strip("/").split("/") if p]
379
404
  head, arg = (parts[0] if parts else ""), (parts[1] if len(parts) > 1 else "")
380
405
  if method == "POST" and head == "write":
381
- status, out = plain(g, method, path, query=query, body=body, **kw)
382
- return status, v.apply(out)
406
+ # the write is checked as this reader: nothing it may not see is read on its behalf (graph.sealed_from); its
407
+ # answer is redacted with the view after the write, in which its own new numbers are no longer secret
408
+ with g.sealed_from(v.hide):
409
+ status, out = plain(g, method, path, query=query, body=body, **kw)
410
+ return status, (view_for(g.snapshot(), keep) or v).answer(status, out)
383
411
  if not v.allows(method, head):
384
- return 409, {"detail": v.message(f"/{head}"), SEALED: v.because()}
412
+ return 409, v.blank({"detail": v.message(f"/{head}"), SEALED: v.because()})
385
413
  if head in ("order", "node", "why", "impact", "neighborhood") and arg:
386
414
  try:
387
415
  nid = g.resolve(arg)
388
416
  except Exception:
389
417
  nid = arg
390
418
  if head == "order" and nid in v.hide:
391
- return 409, {"detail": v.message(f"order {arg}"), SEALED: v.because()}
419
+ return 409, v.blank({"detail": v.message(f"order {arg}"), SEALED: v.because()})
392
420
  status, out = plain(g, method, path, query=query, body=body, **kw)
393
421
  if head == "search" and status == 200 and isinstance(out, dict) and isinstance(out.get("results"), list):
394
422
  out = out | {"results": v.search(out["results"])}
395
- return status, v.apply(out)
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
425
+ return status, v.answer(status, out)
396
426
 
397
427
 
398
- def leaks(s: D.Snap, w: Window, texts: list[str]) -> dict[str, list[str]]:
399
- """Numbers an order's own text quotes that only the material it would seal carries: number → codes holding it."""
400
- hide = scope(s, w)
428
+ def leaks(s: D.Snap, w: Window, texts: list[str], skip: dict | set | None = None) -> dict[str, list[str]]:
429
+ """Numbers an order's own text quotes that only the material it would seal carries: number → codes holding it.
430
+ ``skip``: material sealed from the issuer, left out (comparing against it would answer the issuer's guesses)."""
431
+ hide = scope(s, w) - set(skip or ())
401
432
  visible: set[str] = set()
402
433
  for i, n in s.nodes.items():
403
434
  if i not in hide:
@@ -135,8 +135,31 @@ def derive_views(g: "Graph", invs: list[str]) -> dict:
135
135
  return views
136
136
 
137
137
 
138
- def verify_bundle(b: dict) -> dict:
139
- """Check a bundle string-for-string: the chain, then every row against the event that wrote it."""
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. Head {str(res.get('head', ''))[:16]}…" if ok else f"✗ {target}: {res.get('problem')}")
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 non-reserved); "
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])")