hypgraph 0.2.0__tar.gz → 0.4.0__tar.gz

{hypgraph-0.2.0 → hypgraph-0.4.0}/.gitignore

@@ -14,3 +14,6 @@ research.hypgraph*
 .DS_Store
 Thumbs.db
 .claude/
+
+# study runs: outputs, sealed keys and records stay local until published on purpose
+studies/*/runs/

{hypgraph-0.2.0 → hypgraph-0.4.0}/AGENTS.md

@@ -65,10 +65,11 @@ reserved.
      are not;
    - `kind: "exclusion"` needs a result with `power: "demonstrated"` (a search that found a planted answer).
      Otherwise use `"inconclusive"`.
-   Each refusal ends in a code (`[ABSOLUTE_UNDERPOWERED]`) and already gives the honest sentence: use it.
+   Each refusal ends in a code (`[ABSOLUTE_UNDERPOWERED]`) and already gives the honest sentence: use it. Refusals
+   are logged per author (`refusal_log`); coming back with the honest version marks yours fixed.
 6. **Reviews.** Only reviewers named by the investigation (or the host's policy) set standing. Nobody reviews their
    own work. A revision makes earlier reviews stale.
-7. **Start summaries from `report()`.** It's generated from the record, so it can't restate a withdrawn claim. Write
+7. **Start summaries from `report()`, and run `check_report(text)` on the write-up before handing it over.** It's generated from the record, so it can't restate a withdrawn claim. Write
    your interpretation underneath it.
 
 ## Reading standing

hypgraph-0.4.0/CHANGELOG.md

@@ -0,0 +1,151 @@
+# Changelog
+
+## 0.4.0 — 2026-10-25: the coordination layer
+
+Held until the harmony study had exercised every path (pilots 1–4, a 142-run confirmatory, two follow-up rounds). Governance profiles, token-bound authors, work orders with predicates, order text that carries the target, instrument reproduction, replayable refusals.
+
+### Identity and arithmetic (2026-10-25)
+- `hypgraph serve --token SECRET[=authors]` binds writes to bearer tokens (401 without one, 403 for an author the token isn't bound to; a reserved name needs a token that names it). `--token-file`, `$HYPGRAPH_TOKEN`. Without tokens: unchanged. `Policy.extra_reserved` lets a host reserve its own names (hypswarm reserves `harness`). ADR-001.
+- **Governance profiles** (`hypgraph.profiles`, ADR-002): `scientific@1` (the default), `software@1`, `trading@1`, `knowledge@1`, `optimization@1` — each a versioned set of default predicates per target, domain predicates (`tests_pass`, `backtested_oos`, `sourced`, `feasible_bounded`), write-time refusals (`PASS_WITHOUT_INSTRUMENT_RUN`, `EDGE_WITHOUT_OOS_COSTS`, `BACKTEST_WITHOUT_COSTS`, `CLAIM_WITHOUT_SOURCE`, `OPTIMAL_WITHOUT_BOUND`, `OBJECTIVE_WITHOUT_FEASIBILITY`) and completion criteria. Pinned on the investigation (`fields.profile`); `Graph.completion(inv)`, `GET /api/graph/completion|profiles`, MCP `completion`; the briefing names the profile and its criteria. A cited source counts as a claim's evidence.
+- The order text carries the target's own content (a claim's statement, scope, measurements and the values of the results it rests on; a result's values; a question's text; an experiment's protocol), and names a replication of the author's run when one exists — the harmony confirmatory showed 11–16 `show` calls a run reading back what the reply had said.
+- `cancel_work` releases the target's lease when the order was still open, so the target can be issued to someone else at once (a resumed hypswarm run with a replaced seat found it blocked).
+- `stats.two_proportions` / `detectable` no longer divide by zero on an empty arm (undefined, p = 1, the whole range). `tests/test_stats_values.py` pins Wilson, rule-of-three, Newcombe and the z-test to reference values.
+
+
+- **Honest negations pass.** A word counts only when its sentence asserts it (`language.asserted`): "A is not
+  significantly better", "no evidence that it ever fails", "we cannot conclude that…" are accepted; the unnegated
+  overclaim is refused as before. New code `SIGNIFICANCE_CONTRADICTED`: "not significant" when the bound counts
+  are (p < 0.05). Found by the harmony pilot, where the checker refused the honest sentence its own message asked
+  for.
+- **The record binds the numbers it already holds.** A claim's loose numbers are bound to the author's own results
+  in the investigation (linked results first) before any refusal; a `derived_from` link is added to the result
+  they came from, and the reply says what was bound. Small integers (≤ 12) bind only to counts. In the pilot,
+  61 of 106 refused numbers were already in a result.
+- **The done signal.** After every write by an assignee, the reply carries its open orders with each predicate
+  MET / NOT MET, and "return_work now" when all are (`coord.done_lines`; `orders` on create / revise / review
+  results; shown by the MCP tools). In the pilot 8 of 9 sub-agents worked to their turn cap past done.
+- **Orders meetable by construction.** `done_when` accepts `predicate` / `name` / a bare string as spellings of
+  `p`, and a bad predicate's refusal shows the valid form. Each predicate in an order carries how to meet it with
+  the assignee's tools. `result_exists` and `run_registered` count what the assignee wrote while holding the
+  order, so no link vocabulary stands between an honest result and a met predicate. A third rework of an order
+  whose predicate hasn't moved is refused, with the choices spelled out.
+- **The question board.** The briefing's unit is the question: settled (a checked claim answers it), contested,
+  answered (unchecked), in progress, open; the frontier is driven by it, and one review settles a question
+  (`question_board`). `settle` / MCP `settle_work` accepts every returned order whose predicates are all met.
+  Standing in the briefing is now exceptions only (contested, at risk, fallen).
+- **Absolutes over an enumerated set pass.** "A trails B in every subset: math −2.6, code −2.2, reading −0.4",
+  "all three subsets", "over all 818 items" quantify over what the sentence lists; they are not
+  generalisations and are no longer refused. "below zero" is a number, not "never".
+- **Replay.** Refusals are logged with the whole claim body and its support, and `hypgraph replay-refusals`
+  (`Graph.replay_refusals`) runs every logged refusal through the checker as it is now: same, changed, passes.
+  A rule change is judged on the corpus of what agents wrote before it ships.
+- **A result written twice is written once.** The same author re-registering the same numbers (the multiset of
+  a result's values, rounded, keys ignored) is refused with `RESULT_RESTATES`; a declared rerun (a run that
+  `replicates`) is kept and marked; another author's restatement is kept and its standing says `RESTATES RSn`.
+  Restated results are collapsed in work-order text.
+
+- **Coordinating a team through the record** (`coord.py`). All of it is deterministic and makes no model calls.
+  - `briefing(inv)`: the orchestrator's context compiled from the record (mission, rules, roster, standing,
+    frontier, orders in flight and returned with their predicates checked, budget, what changed since the last
+    one), with a hash.
+  - Work orders are `task` nodes: `issue_work` (the target is leased to the assignee; a duplicate is refused),
+    `order_text`, `return_work`, `check_work` (each predicate MET / NOT MET with the nodes that satisfy it),
+    `accept_work` (a decision based on the evidence, only when every predicate is met), `rework`, `cancel_work`
+    and `cancel_moot`.
+  - An order's status is derived, never set: open, returned, overdue, accepted, reworked, cancelled or moot.
+    Only evidence written after the order was issued counts toward it.
+- **Schema.**
+  - `task` gains optional `objective`, `assignee`, `role`, `prediction`, `method`, `done_when`, `budget` and
+    `note`; `kanban_id` is no longer required.
+  - New relations `rests_on` (an order's pinned premises) and `settles` (a decision accepting an order).
+  - `works_on` and `rests_on` join the at-risk relations, so the blast radius of a withdrawal now lists the work
+    orders it makes moot.
+- **Surfaces.** MCP tools `briefing`, `issue_work`, `my_work`, `check_work`, `return_work`, `accept_work`,
+  `rework`, `cancel_work` and `cancel_moot`; CLI `hypgraph brief` and `hypgraph orders`.
+
+## 0.3.0 — 2026-10-24
+
+- **The refusal log.** Every refused claim is logged: author, statement, codes, messages. A later accepted claim by
+  the same author that says the same thing (same node, or ≥ 30% shared content words within 24 hours) marks the
+  refusal fixed. Append-only, with its own hash chain (`verify_refusals()`); the record's chain is untouched.
+  - API: `refusals()`, `refusal_report()`.
+  - CLI: `hypgraph refusals [--author …]`. MCP: `refusal_log`. HTTP: `GET /api/graph/refusals`.
+  - Atlas: an "Overclaims caught" card in the Work view.
+- **`hypgraph check report.md`** lints a write-up against the record (`Graph.check_text`; MCP `check_report`; HTTP
+  `POST /api/graph/check`). Exits 1 on errors (`--strict`: warnings too).
+  - Errors: citations of withdrawn nodes, settled language about unchecked, contested or at-risk work, unknown
+    codes, and unbacked never / no effect / significantly.
+  - Warnings: numbers no result contains or implies, omitted disputes, superseded citations, uncited causal
+    language.
+  - Calibrated on 24 real PegasusDMZ write-ups against its live record. That fixed negations ("cannot be proven"),
+    quoted passages under correction, instructions ("never use the eval set"), p-values given in the sentence, and
+    "results in" as a noun phrase.
+- An absolute whose statement gives its n ("no leaks in 50 prompts", "nothing in 50 of 50") is scoped to what was
+  seen and accepted; its standing still carries the bound. Without n it is refused, as before.
+- Spec draft 3 (§8 refusal log, §9 checking a write-up).
+
+## 0.2.0 — 2026-10-24
+
+**Refusal, remastered.** The claim checks now do the arithmetic the writer skipped, and every refusal says what the
+count actually supports and offers the honest sentence.
+
+- **The arithmetic of never.** "Never" / "always" / "eliminates" / "100%" need a count of what they're about with
+  k = 0 or n (`ABSOLUTE_WITHOUT_COUNT`, `ABSOLUTE_UNRELATED_COUNT`). That count needs a 95% bound under 5%
+  (`ABSOLUTE_UNDERPOWERED`: "0 of 3 only rules out more than 63%"), and the statement has to show its denominator
+  (`ABSOLUTE_HIDES_DENOMINATOR`). The bounds are exact at k = 0 (1 − 0.05^(1/n), the rule of three) and Wilson
+  otherwise.
+- **Exposure.** A claim can say how many uses, users or units it applies to (`exposure`, `exposure_unit`). Refusals
+  and the claim's standing then state how many failures the bound leaves unruled out: "up to 58,155 of 1,000,000".
+- **New rules:** `COMPARATIVE_WITHOUT_COMPARISON`, `SIGNIFICANCE_WITHOUT_TEST`, `SIGNIFICANCE_NOT_SHOWN` (the
+  record runs a two-proportion test on bound counts itself), `CAUSAL_WITHOUT_INTERVENTION`, and
+  `EXCLUSION_WITHOUT_POWER` for "no effect" however it is filed, with the smallest effect the sample could have
+  detected.
+- **True numbers pass.** Differences, ratios, percentages and relative changes computed from bound measurements are
+  accepted ("2.8 points", "81.2% vs 78.4%", "+3.6%"). Statistical quantities must be written to one decimal place, so
+  "5 points" can't borrow an interval's end.
+- **Refusals agents can act on:** a stable code on every line, and `GraphError.problems` with `code`, `message`,
+  `fix` and `words`.
+- **Blast radius.** `withdraw()`, and a review that makes a node fall, return `blast_radius`: what rests on it, by
+  type, with claims and decisions named (and spend, if metered). The CLI and MCP print it.
+- **`hypgraph bound K N --exposure X`** and the MCP tool `bound`: what a count supports, before anyone writes "never".
+- A claim's standing carries `bounds`, and `test` for "significantly" claims. Spec draft 2 (§7 rewritten).
+- Credits: made by Nicolas Houghtaling at VoodooMods LLC (README, NOTICE, CITATION.cff, package metadata, site).
+
+## 0.1.0 — 2026-10-24
+
+First release on PyPI.
+
+- **Writes cost what they touch.** A write no longer copies the whole in-memory snapshot. Tables are shallow
+  copies, and a node's list is copied only when the write appends to it. Derived standing is kept for every node the
+  write can't affect (`derive.affected_by`), so the first full read after a write no longer re-derives the graph.
+  At 10,000 nodes: building the graph took 77 s instead of 133 s, a full read after a write 0.02 s instead of
+  0.17 s, and a write at 5,000 nodes 5.8 ms instead of 12 ms. A randomized suite checks the carried standing
+  against a full rebuild after every kind of write.
+- New indexes for display codes and the rate limit (`nodes(inv, type)`, `nodes(inv, code)`, `events(actor, kind,
+  at)`). Created on open; existing records just gain them.
+- Positioning: the evidence layer for AI research agents. README and site lead with the MCP server and the Agent
+  Skill; a new engineering guide (`/engineers/`) replaces the human guide; the eval-report example replaces the
+  classroom one.
+
+### Extracted from PegasusDMZ
+
+Extracted from the PegasusDMZ research graph and verified against it: on a copy of Pegasus's live
+graph (1,357 events, 790 nodes in 5 investigations), the library reproduces the same chain head, every node's
+standing, the work queues and the next-experiment rankings.
+
+- **Engine** (stdlib only): typed nodes and edges, append-only SQLite with a SHA-256 event chain and `verify()`,
+  standing derived on read, claim checks on write, review pinned to versions, independence and evidence profile,
+  leases, next experiments, work map, digest, report.
+- **Policy**: reviewers, instrument, operator, importer and system are the host's to set (they were hardcoded in
+  Pegasus). Optional `spend` hook for cost. Injectable `clock`; only the importer may set a write's time.
+- **Bundles** (`hypgraph/1-bundle`): every event and body as the exact hashed string, so they can be verified in any
+  language. Scoped exports redact events outside the investigation and say so. A complete bundle replays row for row.
+- **CLI**: `init`, `add`, `link`, `review`, `revise`, `withdraw`, `ls`, `show --why/--impact/--history`, `next`, `work`,
+  `report`, `export`, `import`, `verify`, `demo`, `schema`, `serve`, `mcp`, `skill`.
+- **MCP server** (FastMCP, `hypgraph[mcp]`): 17 tools, 4 resources, a `method` prompt. Writes as one fixed author.
+- **Agent skill**: `SKILL.md` ships in the package; `hypgraph skill --install`.
+- **Atlas**: the framework-free explorer, with an HTTP source and a bundle source (it verifies the chain in the
+  browser). Cytoscape is vendored.
+- **Demo**: Broad Street, 1854 — a teaching reconstruction with three refusals built into the story.
+- Fixed while extracting it: a report listed stale-reviewed claims under the wrong key; claim measurements now accept
+  result codes (RS3) and store ids.

{hypgraph-0.2.0 → hypgraph-0.4.0}/CITATION.cff

@@ -13,7 +13,7 @@ authors:
     affiliation: VoodooMods LLC
   - name: VoodooMods LLC
 license: Apache-2.0
-version: 0.2.0
+version: 0.3.0
 date-released: "2026-10-24"
 url: "https://hypgraph.com"
 repository-code: "https://github.com/voodoomods/hypgraph"

{hypgraph-0.2.0 → hypgraph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hypgraph
-Version: 0.2.0
+Version: 0.4.0
 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.
 Project-URL: Homepage, https://hypgraph.com
 Project-URL: Documentation, https://hypgraph.com/engineers/
@@ -82,6 +82,33 @@ Every refusal has a stable code, the arithmetic, and the sentence that *would* b
 claim in one step. `hypgraph bound 0 50 --exposure 1e6` (or the MCP tool `bound`) answers "what does my count
 actually support?" before anyone writes the word.
 
+Every refusal is also **logged**: who tried to say what, which rules caught it, and whether they came back with
+the honest version.
+
+```text
+$ hypgraph refusals
+## Overclaims caught — 4 refused, 3 came back honest
+| author  | refused | fixed | open | most common |
+| analyst | 4       | 3     | 1    | EXCLUSION_WITHOUT_POWER ×1, ABSOLUTE_UNDERPOWERED ×1, UNBOUND_NUMBER ×1 |
+### Latest
+- analyst: “Prompt format makes no difference to accuracy.” — EXCLUSION_WITHOUT_POWER → not fixed
+- analyst: “The model never leaks training data.” — ABSOLUTE_UNDERPOWERED → fixed as CL2
+- analyst: “The fine-tune is 5 points better than the baseline.” — UNBOUND_NUMBER → fixed as CL1
+- analyst: “The fine-tune always beats the baseline.” — ABSOLUTE_WITHOUT_COUNT, COMPARATIVE_WITHOUT_COMPARISON → fixed as CL1
+```
+
+And because most hype lives in the write-up, not the record, **`hypgraph check summary.md`** lints the final report
+against the record. It catches numbers no result contains, claims called "established" that the record has as
+unchecked or contested, citations to withdrawn claims, and "never" / "no effect" / "significantly" with nothing
+behind them. It exits 1 on errors, so it can gate CI:
+
+```text
+$ hypgraph check summary.md
+summary.md:8: error REPORT_OVERSTATES_STANDING: 'established' — but CL2 is unchecked in the record …
+summary.md:9: warning REPORT_UNSOURCED_NUMBER: 700 isn't in any result, measurement, claim, scope or constant …
+summary.md:13: error REPORT_UNKNOWN_CODE: CL9 isn't in the record for this investigation — a citation to nothing.
+```
+
 And when something does fall, the record says what falls with it:
 
 ```text
@@ -105,6 +132,25 @@ Nothing in the record is ever *set* as known. How well each claim is known is **
 Every write is an event in a **SHA-256 hash chain**. A record can be handed to a reviewer, a regulator or another
 team, and they can verify it without trusting you.
 
+## One record, five disciplines
+
+The rules above are the scientific case written as code. A **profile** says what a domain means by evidence,
+acceptance and done — and the record enforces it, so it never depends on a prompt being followed. Pin one on the
+investigation (`"profile": "software@1"`); without one, the record behaves exactly as before.
+
+| profile | an order is done when… | the record refuses | the investigation is done when |
+|---|---|---|---|
+| `scientific@1` | a checked claim answers the question | numbers no result accounts for, "never" without the count, "significant" without the test | every question is settled |
+| `software@1` | **the instrument ran the tests** (`tests_pass`) and a claim states it | *"it passes"* without an instrument-recorded run | every requirement's claim rests on a passing run |
+| `trading@1` | a backtest is **out of sample and after costs** (`backtested_oos`) | a backtest without the costs it charged; *"edge"* without both | a sized paper position is a decision based on the claim |
+| `knowledge@1` | the claim **cites a source node** the record holds (`sourced`) | a factual claim with no source | every claim cites a source |
+| `optimization@1` | a result carries **objective, feasible, and a bound or gap** (`feasible_bounded`) | an objective without feasibility; *"optimal"* without a bound | a feasible incumbent with a bound exists |
+
+Profiles are versioned and frozen: a record written under `trading@1` means the same thing in a year, and a changed
+rule is `@2`. `completion(inv)` reports each criterion; the briefing names the profile and where it stands;
+`hypgraph serve` exposes `/api/graph/completion` and `/api/graph/profiles`. Adding a discipline is one `Profile` —
+vocabulary, default predicates, domain predicates, refusals, completion — and the rest of the record is unchanged.
+
 ## Connect your agent
 
 ```bash
@@ -116,7 +162,7 @@ hypgraph skill --install                                                     # +
 The server writes as one author, fixed when it starts. The agent can't pass another name or write as your job runner,
 and its verdicts count only if you name it as a reviewer. Tools: `overview`, `find`, `show`, `start_investigation`,
 `add`, `link`, `revise`, `withdraw`, `retract_link`, `review`, `next_experiments`, `work_queue`, `claim_work`,
-`register_run`, `bound`, `report`, `verify`, `schema`. The method is in [AGENTS.md](https://github.com/voodoomods/hypgraph/blob/main/AGENTS.md); the short version is
+`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
 [llms.txt](https://hypgraph.com/llms.txt).
 
 ## Wire it into your system

{hypgraph-0.2.0 → hypgraph-0.4.0}/README.md

@@ -50,6 +50,33 @@ Every refusal has a stable code, the arithmetic, and the sentence that *would* b
 claim in one step. `hypgraph bound 0 50 --exposure 1e6` (or the MCP tool `bound`) answers "what does my count
 actually support?" before anyone writes the word.
 
+Every refusal is also **logged**: who tried to say what, which rules caught it, and whether they came back with
+the honest version.
+
+```text
+$ hypgraph refusals
+## Overclaims caught — 4 refused, 3 came back honest
+| author  | refused | fixed | open | most common |
+| analyst | 4       | 3     | 1    | EXCLUSION_WITHOUT_POWER ×1, ABSOLUTE_UNDERPOWERED ×1, UNBOUND_NUMBER ×1 |
+### Latest
+- analyst: “Prompt format makes no difference to accuracy.” — EXCLUSION_WITHOUT_POWER → not fixed
+- analyst: “The model never leaks training data.” — ABSOLUTE_UNDERPOWERED → fixed as CL2
+- analyst: “The fine-tune is 5 points better than the baseline.” — UNBOUND_NUMBER → fixed as CL1
+- analyst: “The fine-tune always beats the baseline.” — ABSOLUTE_WITHOUT_COUNT, COMPARATIVE_WITHOUT_COMPARISON → fixed as CL1
+```
+
+And because most hype lives in the write-up, not the record, **`hypgraph check summary.md`** lints the final report
+against the record. It catches numbers no result contains, claims called "established" that the record has as
+unchecked or contested, citations to withdrawn claims, and "never" / "no effect" / "significantly" with nothing
+behind them. It exits 1 on errors, so it can gate CI:
+
+```text
+$ hypgraph check summary.md
+summary.md:8: error REPORT_OVERSTATES_STANDING: 'established' — but CL2 is unchecked in the record …
+summary.md:9: warning REPORT_UNSOURCED_NUMBER: 700 isn't in any result, measurement, claim, scope or constant …
+summary.md:13: error REPORT_UNKNOWN_CODE: CL9 isn't in the record for this investigation — a citation to nothing.
+```
+
 And when something does fall, the record says what falls with it:
 
 ```text
@@ -73,6 +100,25 @@ Nothing in the record is ever *set* as known. How well each claim is known is **
 Every write is an event in a **SHA-256 hash chain**. A record can be handed to a reviewer, a regulator or another
 team, and they can verify it without trusting you.
 
+## One record, five disciplines
+
+The rules above are the scientific case written as code. A **profile** says what a domain means by evidence,
+acceptance and done — and the record enforces it, so it never depends on a prompt being followed. Pin one on the
+investigation (`"profile": "software@1"`); without one, the record behaves exactly as before.
+
+| profile | an order is done when… | the record refuses | the investigation is done when |
+|---|---|---|---|
+| `scientific@1` | a checked claim answers the question | numbers no result accounts for, "never" without the count, "significant" without the test | every question is settled |
+| `software@1` | **the instrument ran the tests** (`tests_pass`) and a claim states it | *"it passes"* without an instrument-recorded run | every requirement's claim rests on a passing run |
+| `trading@1` | a backtest is **out of sample and after costs** (`backtested_oos`) | a backtest without the costs it charged; *"edge"* without both | a sized paper position is a decision based on the claim |
+| `knowledge@1` | the claim **cites a source node** the record holds (`sourced`) | a factual claim with no source | every claim cites a source |
+| `optimization@1` | a result carries **objective, feasible, and a bound or gap** (`feasible_bounded`) | an objective without feasibility; *"optimal"* without a bound | a feasible incumbent with a bound exists |
+
+Profiles are versioned and frozen: a record written under `trading@1` means the same thing in a year, and a changed
+rule is `@2`. `completion(inv)` reports each criterion; the briefing names the profile and where it stands;
+`hypgraph serve` exposes `/api/graph/completion` and `/api/graph/profiles`. Adding a discipline is one `Profile` —
+vocabulary, default predicates, domain predicates, refusals, completion — and the rest of the record is unchanged.
+
 ## Connect your agent
 
 ```bash
@@ -84,7 +130,7 @@ hypgraph skill --install                                                     # +
 The server writes as one author, fixed when it starts. The agent can't pass another name or write as your job runner,
 and its verdicts count only if you name it as a reviewer. Tools: `overview`, `find`, `show`, `start_investigation`,
 `add`, `link`, `revise`, `withdraw`, `retract_link`, `review`, `next_experiments`, `work_queue`, `claim_work`,
-`register_run`, `bound`, `report`, `verify`, `schema`. The method is in [AGENTS.md](https://github.com/voodoomods/hypgraph/blob/main/AGENTS.md); the short version is
+`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
 [llms.txt](https://hypgraph.com/llms.txt).
 
 ## Wire it into your system

hypgraph-0.4.0/docs/decisions/ADR-001-token-bound-authors.md

@@ -0,0 +1,46 @@
+# ADR-001 — Writes over HTTP are bound to tokens, and hosts can reserve their own names
+
+**Date** 2026-10-25 · **Status** accepted · **Where** `server.py`, `policy.py`, `cli.py`
+
+## Context
+
+`hypgraph serve --writable` took `author` from the request body and authenticated nobody. The MCP server fixes
+its author at start (`--as`), so an agent on MCP can't impersonate; over HTTP anyone who could reach the port
+could write as any non-reserved author. For hypswarm that included **`harness`** — the orchestrator that owns
+every order, may cancel and rework them, and settles accepted work — because `Policy.reserved` knew only the
+engine's four names (instrument, operator, importer, system).
+
+The principle at stake: the record is the authority, and authority starts with knowing who is writing.
+
+## Decision
+
+1. **`Policy.extra_reserved`**: a host may add names to the reserved set (hypswarm adds `harness`). Everything
+   that consults `policy.reserved` — the HTTP write path, the MCP `--as` check, the rate limiter, the fixed-record
+   guard — sees them. Default empty: existing policies are unchanged.
+2. **Bearer tokens on the write route.** `serve --token SECRET=a,b` binds a token to authors; `SECRET=*` (or a
+   bare secret) means any *non-reserved* author; `--token-file` and `$HYPGRAPH_TOKEN` are the same thing in other
+   places. With any token configured, a write without a known token is **401** (`WWW-Authenticate: Bearer`), a
+   write as an author the token isn't bound to is **403**, and a reserved name is accepted only from a token that
+   names it explicitly. Secrets are compared with `hmac.compare_digest`; a secret under 16 characters is refused
+   at parse time. Reads stay open (the Atlas needs them; a server exposed beyond localhost still belongs behind a
+   reverse proxy for reads).
+3. **No tokens → exactly today's behaviour**: reserved names refused, everyone else taken at their word.
+
+## Alternatives considered
+
+- Make `harness` one of the engine's fixed roles: it is a hypswarm concept; the engine shouldn't know it.
+  `extra_reserved` lets any host reserve what it needs.
+- Per-request signatures (HMAC over the body): stronger against replay, but every client would need the
+  signing code, and the threat here is identity, not tampering on a localhost link. Tokens over TLS (or a
+  reverse proxy) cover the exposure the server is documented for.
+- Authenticating reads too: left to the proxy layer for now; a `--private` flag is an easy follow-up.
+
+## Consequences
+
+- hypswarm's `HttpRecord(token=…)` sends the bearer; its one client writes as the harness and every seat, so its
+  token is bound to all of them (`SECRET=harness,analyst,…`). An outside seat (a person on MCP, another agent)
+  gets a token bound to its own name and cannot issue, cancel or settle orders.
+- `AuthError` (hypswarm) distinguishes a refused identity from a refused write.
+- Tests: `tests/test_server_auth.py` (401 / 403 / reserved / case folding / no-token path unchanged / parsing);
+  hypswarm `tests/test_auth.py` (a swarm runs on its token; outsider can't be the harness).
+- The hypgraph suite grew from 91 to 108 tests; wall time 11.4 s → 14.6 s (the new tests start real servers).

hypgraph-0.4.0/docs/decisions/ADR-002-governance-profiles.md

@@ -0,0 +1,50 @@
+# ADR-002 — Governance profiles: what a domain means by evidence, acceptance and done, pinned and versioned
+
+**Date** 2026-10-25 · **Status** accepted · **Where** `profiles.py`, hooks in `schema`, `coord`, `graph`, `server`, `mcp`
+
+## Context
+
+The engine's rules — claims bound to measured results, k/n for absolutes, a reviewer's verdict to settle a question
+— are the scientific case written as code. A software team needs "it passes" to mean *the instrument ran the
+tests*; a trading desk needs "edge" to mean *out of sample, after costs*; a research assistant needs every factual
+claim to cite what was read; an optimisation run needs "optimal" to come with a bound. Each is a different answer to
+the same three questions: what counts as evidence for a claim, when is an order's work accepted, and when is the
+investigation done. Those answers belong in the record, not in prompts (the harmony study measured that rules in
+prompts are followed inconsistently; rules the record enforces are followed always).
+
+## Decision
+
+A **profile** is a named, versioned, frozen set of: vocabulary (shown, not enforced); default predicates per target
+type; domain predicates the record can check (`tests_pass`, `backtested_oos`, `sourced`, `feasible_bounded`);
+write-time validators on claims and results (`PASS_WITHOUT_INSTRUMENT_RUN`, `EDGE_WITHOUT_OOS_COSTS`,
+`BACKTEST_WITHOUT_COSTS`, `CLAIM_WITHOUT_SOURCE`, `OPTIMAL_WITHOUT_BOUND`, `OBJECTIVE_WITHOUT_FEASIBILITY`);
+completion criteria derived from the record (`questions_settled`, `requirements_verified`, `position_recorded`,
+`all_sourced`, `incumbent_feasible`); and suggested seat templates. Five ship: `scientific@1` (the default — an
+investigation with no profile behaves exactly as before), `software@1`, `trading@1`, `knowledge@1`,
+`optimization@1`.
+
+An investigation **pins** its profile (`fields.profile = "software@1"`; an unknown id is refused at creation).
+Rules never change under a version — a changed rule is `@2` — so a record written under `trading@1` means the same
+thing in a year. `issue_work` takes the profile's default predicates; `check_work` evaluates the domain predicates
+with the same lease-window rule as the built-ins; `create` adds the profile's refusals to the claim checks and
+refuses results the profile rejects (curators excepted, as for claim checks); `completion(inv)` reports the
+criteria; the briefing's MISSION names the profile and the criteria's state; the server has `/completion` and
+`/profiles`; the MCP server has `completion`. A cited source now counts as a claim's evidence (knowledge profile).
+
+## Alternatives considered
+
+- Per-host subclasses of `Graph`: rules would live in code outside the record and couldn't be pinned or read back.
+- Prompts per domain only: the measured failure mode (see context).
+- One mutable profile per name: a record written under last month's rules would silently mean something else.
+
+## Consequences
+
+- Tests (`tests/test_profiles.py`): unknown profile refused; no profile = today's predicates and criteria; software —
+  the tester's own "positive" result does not meet `tests_pass`, the instrument's replicating lab run does, "passes"
+  is refused without it, completion needs instrument evidence; trading — a costless backtest result is refused, an
+  in-sample edge is refused, out-of-sample + fees + a reviewed claim + a sized decision completes; optimisation —
+  objective without feasibility refused, "optimal" without a bound refused; knowledge — unsourced claim refused,
+  cited claim accepted and completes; server routes. 119 tests pass.
+- hypswarm binds rosters and toolkits to these ids (hypswarm ADR-008).
+- Open: a `@2` of any profile needs a migration note in CHANGELOG; validators use the same clause-level negation
+  as the claim checks (`language.asserted`), so "no edge was found" is not refused.