hypgraph 0.3.0__tar.gz → 0.4.0__tar.gz

{hypgraph-0.3.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.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.3.0 → hypgraph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hypgraph
-Version: 0.3.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/
@@ -132,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

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

@@ -100,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

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.

hypgraph-0.4.0/docs/review-2026-10-24.md

@@ -0,0 +1,206 @@
+# HypGraph, read fresh: what it is, what to fix, what it could become
+
+*An assessment written on 2026-10-24 after reading the engine, the checks, the coordination layer, the agents'
+instructions, and what the agents actually did in the two pilots. Every number here comes from those pilot
+records; each is marked with where it came from.*
+
+---
+
+## 1. What HypGraph is
+
+HypGraph is a record that agents write into and cannot flatter. Three things make it different from a database
+with a schema, and they are the three things to protect:
+
+1. **Standing is derived, never set.** Nobody, human or agent, can mark a claim "established". Review state,
+   independence of support, fallen premises and evidence strength are recomputed from the record every time it is
+   read. This is the part most people will miss and the part that matters most: it means the record can be
+   trusted by someone who doesn't trust its authors.
+2. **Refusal does the arithmetic.** A claim that says "never" from 0 of 50 is refused with the bound (5.8 %), the
+   trials needed (2,995), the exposure consequence (58,155 of a million) and the honest sentence. The agent can
+   repair in one step. Nothing else I know of does this at write time.
+3. **Every write is hash-chained**, so the record is checkable without trusting the host.
+
+The coordination layer added this week makes a fourth claim: that the record can compile each agent's context and
+accept each agent's work, so a team coordinates through the record instead of through a transcript.
+
+## 2. What is good
+
+- The derived-standing engine is sound. On Pegasus's live record (790 nodes) it reproduces the old engine's
+  standing exactly, and the incremental snapshot keeps writes at milliseconds.
+- The refusal rules are the right rules. Each exists because an agent made that mistake, and the set
+  (absolute / comparative / significance / causal / exclusion / unbound number) covers the overclaims that appear
+  in practice.
+- The final reports produced under the record condition are the best reports I have seen an agent team write.
+  F1-902-C's report: every number traceable to a code, the trap named and checked, a caveat that no individual
+  subset clears 5 %, and the honest conclusion that A is *not* shown better. That is the product.
+- The record condition was the only one that never fell for a trap across pilot 2 (0 of 4; chat 2, Pegasus-today
+  1, record-without-gates 1).
+- The preregistration discipline is real: hashes, a lock, logged deviations, pilot data excluded. Keep it.
+
+## 3. What to fix before showing the world
+
+Ranked by how much they matter, with the evidence.
+
+### 3.1 The checker refuses honest negations (a bug in the flagship feature)
+
+`checks.py` listens for "significantly" and runs the test on the bound counts, but it does not read the
+sentence. So:
+
+```
+REFUSED: "A is not significantly more accurate than B (812 of 1000 vs 800 of 1000)."  -> SIGNIFICANCE_NOT_SHOWN
+REFUSED: "A is significantly more accurate than B (812 of 1000 vs 800 of 1000)."      -> SIGNIFICANCE_NOT_SHOWN
+```
+
+The honest statement, the one the refusal message itself asks for ("say the difference and that it isn't
+significant"), is refused with the same code as the overclaim. In pilot 2, F1-903-C's analyst wrote "Trap check:
+the wording 'whether A is really better than B' is a false premise" and was refused three times. The report
+linter (`report_check._asserted`) already handles negation at sentence level; the claim checker must do the same
+for every word list, not only significance ("not caused by", "no evidence that it never…").
+
+### 3.2 Refuse less, repair more: bind the numbers the record already holds
+
+In pilot 2's record runs, **106 numbers were refused as unbound; 61 of them already sat in a result value in the
+same record**, and most of the rest were rates of bound counts (0.828010 is 337 of 407). The agent had done the
+work and registered it; it had not filled in the `measurements` list. The record can do that itself: when a
+statement's numbers all resolve against the author's own results in this investigation, bind them and accept,
+noting the bindings it added. Refuse only what it cannot find. This turns the biggest friction (63 of 91
+refusals in pilot 1) into a non-event, and it is deterministic.
+
+### 3.3 Tell every agent when it is done
+
+In F1-902-C, **8 of 9 sub-agent units ran to the 14-turn cap** and were returned on their behalf; 26 claims were
+accepted for a 4-question task. Nobody told the analyst that `claim_made` was already MET after its third write.
+`check_work` exists but only the lead calls it. After every write by an assignee, the record should evaluate the
+order's predicates and say so in the reply: *"T3: claim_made MET — you can return now."* Done-ness is a derived
+property like everything else; surface it where the work happens. This is the cheapest cost fix available: most of
+C's 4.7× cost is sub-agents grinding past done.
+
+### 3.4 The briefing is a claim dump; it should be a question board
+
+F1-902-C's briefing was 5,666 characters, of which STANDING was 3,313: twenty-six claims in a flat list, most
+"unchecked · no live support", eight of them restating the same subset numbers. And FRONTIER listed "CLn needs a
+review" for every unchecked claim, so the lead issued six review orders in ten. The orchestrator's unit of work is
+the **question**, not the claim. The briefing should show, per question: unanswered → answered (by CLx) →
+checked (by whom) → settled; and a sufficiency rule: a question with one checked answering claim is done. The
+lead should see the finish line.
+
+### 3.5 Results duplicate inside the record
+
+RS4, RS7, RS9, RS14, RS16 in F1-902-C all say "code +0.027, math 0.0, reading −0.0049". Artifacts are
+content-addressed; results are not. A write that restates an existing result's values (same keys, same numbers
+within rounding) should be refused with "this restates RS4: link to it", or linked automatically as a
+`replicates` with `same_code`. The orchestrator's ALREADY KNOWN list showed the duplicates and the agents
+re-derived anyway.
+
+### 3.6 Automate the mechanical half of the lead
+
+In F7-900-B the lead made 28 calls; in C runs the lead's `check_work` + `accept_work` calls were 13 of 28, 11 of
+19, and so on. None of those needed a model: when every predicate is met, acceptance is a rule. Accept
+automatically; bring the lead in only for NOT MET, disputes and the report.
+
+### 3.7 Smaller frictions seen in the logs
+
+- `title: say it in a full sentence` refuses a three-character title. Minimum lengths should apply to text
+  fields, not to names.
+- `ABSOLUTE_WITHOUT_COUNT` fired on "every site_b_fixed value equals site_b / 10" when the author had 68 of 68
+  in the same sentence; the count check should accept "k of n" in the statement as a bound when the result
+  carries it.
+- `register_run` requires `result_summary` to be a sentence of ten characters; fine, but the error says "needs
+  summary", not that.
+
+### 3.8 Positioning
+
+Keep the site honest to what is measured. "The evidence layer for AI research agents" is earned. "Harmony is
+cheap" is not, yet: in pilot 2 the record condition cost 4.7× chat per run. Until the fixes above are measured,
+the coordination layer stays unreleased and the site says nothing about cost.
+
+## 4. Orchestrator guidance: the record is the orchestrator
+
+The pilots show something the plan only half-said. Most of what an orchestrator does is mechanical:
+
+| Orchestrator action | Needs judgement? | Pilot evidence |
+|---|---|---|
+| What is open | no: the question board | FRONTIER already computes it |
+| Who is on what | no: leases | duplicates were refused correctly every time |
+| Is an order done | no: predicates | `check_work` was 25–40 % of lead calls |
+| Accept done work | no: a rule | `accept_work` was another 20–30 % |
+| What to stop when a premise falls | no: blast radius | `cancel_moot` worked in F7 |
+| Write the next order's objective | partly | the lead copied the question text |
+| Decide between rival approaches, judge a NOT MET, write the report | **yes** | the lead's real work |
+
+So the design: a deterministic scheduler issues default orders from the question board (one per open question,
+to the role that fits, with the default predicates), accepts them when met, cancels them when moot, and escalates
+to a judgement model only when something is NOT MET twice, when two claims conflict, or when the frontier is
+empty and the report is due. The orchestrator model's context becomes a few hundred tokens of exceptions, not
+5,000 tokens of standing. This is also the correct seed of hypswarm (§7).
+
+What the briefing should carry, in order (stable first, for the cache):
+1. mission and success test;
+2. the question board, with each question's status and the claim that answers it;
+3. exceptions: NOT MET returns, disputes, moot orders, budget;
+4. since-last delta.
+
+Everything else (the full standing list, the frontier of experiments) is available on request, not sent by default.
+
+## 5. Keeping agents true, cheaply
+
+The gates are free: they are deterministic and run at write time. **The cost is retries**, and retries have three
+causes seen in the logs: the record refusing honest sentences (§3.1), refusing numbers it already holds (§3.2),
+and nobody saying "done" (§3.3). Fix those and the cost of truth is close to zero; what remains is the cost of
+the honest version itself, which is the point.
+
+Two cheap things the refusal log makes possible that nobody else can offer:
+
+- **An honesty metric per agent and per model, with no judge model.** Refusals per claim and the fix rate are
+  deterministic numbers the record already keeps. In pilot 2, DeepSeek-V4.1-Flash had 91 refusals and 79 fixes
+  (87 %) under pilot 1's rules. Run the same task suite through several models and the record gives a leaderboard
+  of *who overclaims and who repairs*, for cents, reproducibly. That is a benchmark the community does not have,
+  and HypGraph can publish it as a by-product of its own tests.
+- **Exposure makes "never" cost what it costs.** The `exposure` field turns a bound into a consequence ("up to
+  58,155 of a million not ruled out"). Carry it one step further: a *decision* node that rests on a claim can
+  declare its stake (users, dollars, deployments), and the record reports, per premise, what is at risk if it
+  falls. Blast radius already reports dollars of work; it can report value at stake. "Never when it's 1 in
+  1,000" then has a price tag before anyone writes it.
+
+## 6. The idea you are close to
+
+**Stateless agents over a stateful record.** Pegasus's own ledger says where the money goes: 100 input tokens
+per output token, 92 % of it re-read from cache, 34,865 tokens per call. The transcript is the state, and every
+call re-reads it. HypGraph makes the state live in the record and compiles each call's context from it:
+deterministic, small, cache-stable, and auditable (the briefing carries its own hash). Taken seriously:
+
+- an agent call is `model(compile(record, role, order))`; transcripts are disposable;
+- a team is a set of stateless workers pulling orders from the record's question board and writing results back;
+- "coordination" is the record's scheduler, and the only model calls are work and judgement;
+- the whole run is reproducible from the record and the seeds, and verifiable by hash.
+
+That is not a feature of HypGraph; it is a different way to run agent teams, and HypGraph is the only piece that
+makes it possible, because it is the only shared state that refuses overclaims and derives standing. The pilot's
+reports are the first evidence it produces better output. Whether it produces it cheaper depends entirely on
+§3.2–3.6, which is why they come first.
+
+## 7. hypswarm
+
+hypswarm is that scheduler, as a harness: workers, a question board, orders, predicates, cascade, budget, and a
+judgement model at the exceptions. The study runner's condition C is already its embryo (`study_runner.run_C`
++ `_run_order`); hypswarm is that loop extracted, made parallel, and given a model-agnostic worker interface.
+
+- **Research tasks** map directly: question → hypothesis → experiment → run → result → claim → review.
+- **Building tasks** map with one change: the CI runner is the `instrument`. "The change makes the tests pass"
+  is a claim with a k/n measurement (tests passed of tests run) bound to a result the instrument filed, so it is
+  lab-recorded, not agent-reported. A requirement is a question; a design choice is a decision `based_on` the
+  claims that justify it, flagged REVISIT when one falls; a regression is a withdrawal with a blast radius. The
+  schema needs no new node types, only a `code` artifact convention (commit sha as the artifact hash).
+- **Order of work:** (1) the §3 fixes in HypGraph, measured on the same two families; (2) extract the scheduler;
+  (3) a worker protocol (order text in, writes out, return note); (4) parallel workers with leases; (5) the
+  building adapter with CI as instrument. The harmony study's confirmatory run is then the first hypswarm result.
+- **Positioning:** HypGraph is the record; hypswarm is the way to run a team on it. HypGraph stays independent
+  and usable alone (MCP, CLI, Python); hypswarm depends on HypGraph, never the reverse.
+
+## 8. What not to do
+
+- Don't publish the coordination layer, or say "cheaper", before §3 is fixed and the study rerun.
+- Don't let the record become a chat: the 26-claim run shows what happens when every thought becomes a claim.
+  Sufficiency and deduplication are part of the design, not polish.
+- Don't add a judge model to the gates. Everything that keeps agents true here is deterministic; that is what
+  makes it cheap and makes the honesty metric credible.

{hypgraph-0.3.0 → hypgraph-0.4.0}/src/hypgraph/__init__.py

@@ -16,7 +16,7 @@ Standing is derived on every read, never stored; every write is an event in a SH
 their numbers; reviews pin versions; independence is counted, not assumed. See https://hypgraph.com.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 from .bundle import verify_bundle  # noqa: E402
 from .graph import Author, Graph, GraphError, file_sha256  # noqa: E402