hypgraph 0.4.2__tar.gz → 0.5.0__tar.gz

{hypgraph-0.4.2 → hypgraph-0.5.0}/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.5.0 — 2026-10-26: profiles carry their discipline's workflow
+
+Each discipline's method, as the record enforces it — one page each in `docs/workflows/`, taken from the method
+itself (hypothetico-deductive with preregistration; continuous integration and code review; preregistered
+backtesting and risk management; source criticism and fact-checking; operations-research practice). The `@1`
+profiles are frozen as they were; `scientific@2` … `optimization@2` add the workflow. No profile → unchanged.
+
+- **The stage is derived, never set.** `Graph.stage(question)` / `stages(inv)`, `GET /stage/{id}` / `/stages`, MCP
+  `stage`: a question is in the first stage whose gate the record does not meet, every gate MET / NOT MET with what
+  would meet it. `Profile.workflow` (`Workflow`, `Stage`) holds the stages, gates, invalidation, typed shapes.
+- **Gates double as order predicates**: `hypothesis_stated`, `preregistered` (the experiment, with its expected
+  outcome, precedes any run that executes it), `decided`, `diff_registered`, `tests_pass_current`,
+  `instance_registered`, `source_quoted`, `search_recorded`, `backtested` (out of sample, after costs, trials
+  declared), `positioned`, `still_valid`, `solved`, `result_reviewed`. The `@2` profiles' `done_when` use them.
+- **A workflow widens what counts as resting on.** `uses` (scientific, software, trading, optimization) and `cites`
+  (knowledge) join `schema.RISKY` for that profile only (`derive.EXTRA_RISKY`): a corrected data file, a superseded
+  diff or instance, a withdrawn source puts what rested on it AT RISK. Records under `@1` keep exactly the standing
+  they had.
+- **Freshness** (`derive.stale`, in every standing): a result whose run used an artifact that is now superseded or
+  withdrawn, or whose new `valid_until` has passed, is STALE; a claim is stale when every result behind it is. A
+  check on stale evidence doesn't meet `reviewed`; `requirements_verified_current` and `incumbent_verified` need
+  fresh instrument runs.
+- **Typed shapes.** `artifact.kind` + `artifact.meta` with required fields per workflow (`diff`: base_sha,
+  head_sha, files; `instance`; `prices`; `solution`: objective, feasible …) → `ARTIFACT_MISSING_FIELDS`;
+  `source.kind` primary / secondary / tertiary and `reliability`; `decision.kind` with `size`, `stop`,
+  `review_date`, `paper`, `sensitivity`. `supersedes` now joins artifacts; `corrects` joins sources.
+- **The disciplines' refusals**: `TESTS_ON_STALE_HEAD`, `REVIEW_BY_AUTHOR` (the diff's author can't check the
+  claim), `EDGE_WITHOUT_TRIALS`, `POSITION_WITHOUT_STOP`, `LIVE_ORDER` (no such path exists), `PASSAGE_MISSING`,
+  `SOLVED_WITHOUT_INSTANCE`, `OPTIMAL_ON_STALE_INSTANCE`.
+- **Report**: under an `@2` profile, `report()` adds the workflow's section — each question's stage and next gate,
+  and the evidence that has gone stale.
+- Schema additions are fields and relation endpoints only; no migration. Deferred to later phases, and said so in
+  the specs: per-workflow evidence rank (documented, not derived), the knowledge re-fetch check and
+  `NUMBER_NOT_IN_PASSAGE`, CI as the software instrument, mechanical feasibility recomputation.
+
+## 0.4.3 — 2026-10-26
+
+Five vocabulary-friction fixes from the HypSwarm discovery study, where 110 of 118 refusals were binding, naming
+and shape errors rather than overclaims — and one correct answer was refused fifteen times.
+- **A named p-value backs "significantly".** A bound field named `p`, `p_value` or `p_<test>` (an exact McNemar
+  `p_exact`), or such a field on a supporting result, satisfies the significance check; below 0.05 the word is
+  accepted, above it `SIGNIFICANCE_NOT_SHOWN` quotes it. The record's own two-proportion test stays the fallback.
+- **A bound measurement's result supports the claim.** A claim written with `measurements` that name a result gets
+  a `supports` edge from that result, so its standing counts the line of support the writer already bound.
+- **A wrong relation names the right one.** `executes can't join run → question … — a run joins a question with
+  part_of, motivated_by; the other way round, a question joins a run with …`.
+- **Enum synonyms** (`schema.SYNONYMS`): `outcome=success` → `positive`, `kind=fact` → `finding`,
+  `state=done` → `succeeded`, and more; the stored value is canonical.
+- **Small integers bind to a value the sentence names.** "produced 0 trades" binds to `oos_trades`,
+  "capacity is 7" to `capacity_total`; an unnamed small integer still binds only to a count.
+
 ## 0.4.2 — 2026-10-25
 
 - **A question is not an assertion.** `language.interrogative` / `asserted` return nothing for a sentence that ends

{hypgraph-0.4.2 → hypgraph-0.5.0}/PKG-INFO

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

hypgraph-0.5.0/docs/profile-workflows-plan.md

@@ -0,0 +1,110 @@
+# Profiles as workflows — plan
+
+*Written 2026-10-26. Status: plan. Nothing in it is built yet beyond what §1 lists as present.*
+
+## 0. The question this answers
+
+HypSwarm's trading and software profiles run on HypGraph's scientific graph with discipline labels. Is that a
+feature of HypSwarm bolted onto a scientific HypGraph, or should HypGraph itself be built from each discipline's
+method the way it is built from the scientific one?
+
+**Answer: the record's kernel should stay one thing — the general shape of justified belief, which the scientific
+method happens to be the clearest statement of — and each discipline's *workflow* should become a first-class,
+versioned object inside a HypGraph profile that the kernel enforces and HypSwarm executes.** Today the workflow
+exists only as a paragraph in the profile's notes and as a diagram on hypswarm.com. That is the gap.
+
+## 1. What a profile is today, and what it is not
+
+| a profile controls today (hypgraph 0.4.3) | a profile does not control |
+|---|---|
+| vocabulary: a meaning per node type ("experiment = a test plan") | the node types and relations (fixed, 12 + 22) |
+| `done_when` per target type (which predicates an order needs) | the **stages** a question passes through and the gate between each |
+| domain predicates: `tests_pass`, `backtested_oos`, `sourced`, `feasible_bounded` | what **invalidates** a claim later: `RISKY` is fixed to the scientific relations; `cites` is not in it, so a withdrawn source leaves a knowledge claim standing |
+| write-time validators: `PASS_WITHOUT_INSTRUMENT_RUN`, `EDGE_WITHOUT_OOS_COSTS`, … | the **evidence ranking** (`external > new_data > separate_implementation > …` is scientific replication; software needs *runs on the current code*, trading needs *out of sample, after costs, recent*) |
+| completion criteria (`requirements_verified`, `position_recorded`, …) | typed **artifacts** (a diff with its base commit, a position with size and stop, a source with the passage that says it) — all are `artifact` / `decision` / `source` with no required discipline fields |
+| suggested seats | the **report**: every profile prints "Facts from the research graph" |
+| | the **order**: HypSwarm issues from the question board, not from the stage a question is in |
+
+The discovery study (HypSwarm `studies/discovery/`) showed what this costs: 110 of 118 refusals were vocabulary
+friction because the models were writing discipline work into scientific slots, and the honesty rules by themselves
+did not beat a prompt. What a prompt cannot do is remember that the code changed since the tests ran, that the
+source was retracted, that the regime moved, that the teammate's number is stale — the workflow's *invalidation*
+and *gates*. That is where the record should win, and it is exactly what profiles don't yet encode.
+
+## 2. The design: one kernel, five workflows
+
+A **Workflow** is data on the Profile, versioned with it (`software@2`), hash-chained with the investigation that
+pins it:
+
+```python
+@dataclass(frozen=True)
+class Stage:
+    name: str                      # "specified", "implemented", "verified", "reviewed", "released"
+    holds: tuple[str, ...]         # node types that live in this stage ("experiment", "artifact")
+    gate: tuple[str, ...]          # predicates that must hold to leave it (existing + new ones)
+    who: str                       # the role that works it (worker | reviewer | lead | instrument)
+
+@dataclass(frozen=True)
+class Workflow:
+    stages: tuple[Stage, ...]      # in order; a question is "in" the first stage whose gate is not met
+    invalidates: tuple[str, ...]   # relations that put dependants at risk when the far end changes or falls
+    freshness: dict[str, str]      # per node type: what "current" means ("artifact": "same sha as the run used")
+    artifacts: dict[str, dict]     # typed artifacts: kind → required fields ("diff": {base_sha, head_sha, files})
+    evidence_rank: tuple[str, ...] # the profile's own ranking for `evidence`
+    report: str                    # the report template's name
+```
+
+The kernel keeps: twelve node types, hash chain, append-only, derived standing, refusals, the instrument. The
+profile supplies: which relations are risky here, what fresh means, what each stage needs, what the report says.
+HypSwarm reads the stage and issues the next gate's order to the seat whose role owns that stage.
+
+### The five workflows (the §P0 deliverable is one page each; this is the shape)
+
+| profile | stages | gates (new predicates in bold) | invalidation | typed artifacts |
+|---|---|---|---|---|
+| scientific | asked → conjectured → tested → evidenced → claimed → reviewed → decided | hypothesis stated, experiment preregistered, run registered, result, claim, review | the present `RISKY` | data (sha), protocol |
+| software | specified → implemented → verified → reviewed → released | requirement question; **diff registered** (base + head sha); `tests_pass` on **that head**; review; decision | a new head sha supersedes the diff → every `tests_pass` result on the old head is **stale**, its claims AT RISK | diff, build, test-run |
+| trading | asked → thesised → preregistered → backtested → risk-reviewed → positioned → monitored | hypothesis with the move it predicts; experiment with window + costs **before** the run; `backtested_oos`; review by risk; decision with size/stop/review_date; **`still_valid`** (data newer than the backtest's window, regime check) | time: a result **expires** at `review_date`; a regime-change notice puts positions AT RISK | backtest, position (paper) |
+| knowledge | asked → sourced → claimed → checked → compiled | source with passage + retrieved; `sourced` claim; fact-checker review; report lint | **`cites` becomes risky**: a withdrawn or superseded source puts its claims AT RISK; a source older than `max_age` is stale | source, excerpt |
+| optimization | modelled → solved → bounded → verified → recommended | hypothesis = modelling choice; experiment = solve config; `feasible_bounded`; verifier review; decision names the incumbent | a changed instance artifact (new sha) supersedes every solve on it | instance, solution |
+
+Two cross-cutting rules the workflow makes possible and the kernel can't express today:
+
+- **Freshness.** A result is *current* only if the artifacts its run `uses` are the live versions. Software and
+  optimization need this most; it is the "code changed since the tests ran" case nothing in a prompt survives.
+- **Expiry.** A trading result carries `valid_until`; past it the standing says STALE and the claim needs a rerun.
+
+## 3. Phases, gates, spend
+
+| phase | work | where | gate |
+|---|---|---|---|
+| **P0 — specs** | one page per profile: stages, gates, invalidation, artifacts, report; reviewed before code | `HypGraph/docs/workflows/<profile>.md` | the user reads all five and agrees the stages are the discipline's, not ours |
+| **P1 — kernel** | `Workflow` / `Stage` on `Profile`; profile-defined `invalidates` merged into at-risk derivation; `freshness` in `derive`; typed artifacts (required fields by `kind`); `Graph.stage(question)`; `evidence_rank` per profile; report templates; new predicates (`diff_registered`, `still_valid`, `fresh`); schema bump with migration (old records = `@1`) | HypGraph, tests per profile + a replay of the discovery records to see what would change | 100 % of existing tests pass; every old record derives the same standing under `@1` |
+| **P2 — orders from stages** | the scheduler asks the record which stage each question is in and issues that gate's order to the role that owns it; order text names stage and gate; the lead's report comes from the profile's template; `completion` reads the last stage | HypSwarm, scripted-model tests for every path (as now) | the stub discovery run settles every family through its stages |
+| **P3 — the test that can show it** | extend the discovery harness with the change-per-discipline cases: a commit after the tests (software), a retracted source (knowledge), a regime notice and an expired backtest (trading), a changed instance (optimization), a corrected file (scientific); P vs R; predictions first | HypSwarm `studies/discovery/`, ≈ $2 | this is where a prompt cannot hold state and the record can; if R does not win **here**, the workflow design is wrong |
+| **P4 — docs** | profiles presented as HypGraph's, with the workflow on hypgraph.com as it is on hypswarm.com; the engineers pages; `hypgraph profiles` prints stages | both sites | — |
+
+P1 is the considerable part: two to three days of kernel work with tests, and the first schema version bump that
+needs a migration story. P0 is a day and decides whether P1 is right. P3 is the only spend.
+
+**Status (2026-10-26).** P0 written (`docs/workflows/`), P1 built as hypgraph 0.5.0 (`workflow.py`,
+`tests/test_workflows.py`; CHANGELOG). The schema change turned out additive (fields and relation endpoints), so
+no migration: `@1` records derive exactly as before, the `@2` profiles opt in. Left for later phases, each named in
+its spec: per-workflow evidence rank (documented, not derived), the knowledge re-fetch check, CI as the software
+instrument, mechanical feasibility recomputation (P3). P2 (HypSwarm issues orders from stages) is next.
+
+## 4. What stays as it is, on purpose
+
+- Twelve node types. A commit is an artifact with required fields, not a new type; a position is a decision with
+  required fields. The spec, the Atlas, the MCP tools and the playground don't fork per discipline.
+- One hash chain and one `verify`. A workflow is data the chain covers, not code the chain can't see.
+- Dependency-free kernel. Workflows are tables and predicates, like profiles are now.
+- The honesty rules. They held in the discovery study; the workflow adds the state they can't carry.
+
+## 5. Risks
+
+- **Over-specifying a discipline we don't practise.** P0 is where a trader or an engineer corrects the stages; the
+  specs should quote the method they're taken from (preregistration, CI gates, source criticism, verification).
+- **Schema version.** Old records must keep deriving identically; `profile@1` is the frozen behaviour.
+- **Stage inference, not stage setting.** A question's stage must be *derived* from what the record holds (the
+  first unmet gate), never written by an agent — same rule as standing.

hypgraph-0.5.0/docs/workflows/README.md

@@ -0,0 +1,30 @@
+# Workflow specs — P0 of the profiles-as-workflows plan
+
+One page per profile, for review before any kernel code (see `../profile-workflows-plan.md`). Each spec names the
+method it is taken from, then states what the record would enforce: the stages a question passes through, the gate
+out of each stage (predicates the record checks), who works the stage, what later invalidates a claim, what
+"fresh" means, the typed artifacts with their required fields, the report, and completion.
+
+Conventions used in every spec:
+
+- **A stage is derived, never set.** A question is in the first stage whose gate is not met. Agents write nodes;
+  the record reads the stage off them.
+- **Gates are predicates** the record evaluates from the record alone (existing ones in `coord.PREDICATES` and
+  `profiles.PRED_DESC`; new ones are marked **new**).
+- **Invalidation** names the relations that, when the far end falls, changes version or expires, put dependants
+  AT RISK. Today only the scientific set (`requires`, `derived_from`, `based_on`, `works_on`, `rests_on`) does.
+- **Fresh** says when a result still speaks for the thing it measured.
+- **Typed artifacts** are `artifact` / `source` / `decision` nodes with required fields per `kind`, not new types.
+
+| spec | method it is taken from | the one gate a prompt can't keep |
+|---|---|---|
+| [scientific](scientific.md) | hypothetico-deductive method, preregistration | a corrected data file after the analysis |
+| [software](software.md) | continuous integration and code review | a commit after the tests ran |
+| [trading](trading.md) | preregistered backtesting, risk management | a backtest past its review date, a regime notice |
+| [knowledge](knowledge.md) | source criticism, fact-checking practice | a retracted or superseded source |
+| [optimization](optimization.md) | operations-research practice: model, solve, bound, verify | a changed instance after the solve |
+
+Each spec ends with its review questions and the decision taken on each (2026-10-26). **Built as hypgraph 0.5.0**
+(`src/hypgraph/workflow.py`, the `@2` profiles in `profiles.py`, `tests/test_workflows.py`): the stages and gates,
+`Graph.stage()`, the invalidation relations, freshness, the typed shapes and the refusals. What each spec defers to
+a later phase is named in its decisions.

hypgraph-0.5.0/docs/workflows/knowledge.md

@@ -0,0 +1,82 @@
+# Workflow: `knowledge`
+
+## The method it is taken from
+
+Source criticism and professional fact-checking: a statement is only as good as the source that says it, the
+passage that says it must be quoted, the source's reliability and date are part of the claim, and a check is done
+by someone who did not write the claim. The historian's external and internal criticism of sources; the
+International Fact-Checking Network's code (cite primary sources, show the evidence, correct openly); and the
+systematic-review discipline of recording what was searched and what was excluded. The record holds what was
+read, not what was recalled, and a correction propagates to everything built on the source.
+
+## Stages
+
+| # | stage | holds | gate out of it | who |
+|---|---|---|---|---|
+| 1 | asked | question | stated | lead |
+| 2 | searched | experiment `kind=search`: where it looked, with what terms, what it excluded | `search_recorded` **new**: an experiment on the question states the sources consulted (optional stage: required when the task asks for a systematic answer) | researcher |
+| 3 | sourced | source nodes: `citation`, `url` or `doi`, **`passage`**, `retrieved`, `kind` (primary / secondary / tertiary), `reliability` note | `source_quoted` **new**: a source with a non-empty `passage` and `retrieved` date `cites`-able from a claim | researcher |
+| 4 | claimed | claim `cites` the source; measurements bound to numbers in the passage (0.4.1) | `sourced` (today); validator `CLAIM_WITHOUT_SOURCE` | researcher |
+| 5 | checked | review by the fact-checker: opened the source, the passage says it | `reviewed`, with method naming the source opened | fact_checker |
+| 6 | compiled | the report, linted so no sentence treats an unchecked claim as settled | `report_clean` (today) | lead |
+
+A question whose honest answer is "no source" is settled by a claim of `kind=inconclusive` that `cites` the search
+experiment ("searched X, Y, Z; nothing answers it") — the LIB-NOTES "stuck but honest" case becomes a settled one.
+
+## Invalidation
+
+- **`cites` becomes an at-risk relation.** A source that is withdrawn (retracted, taken down, corrected) puts
+  every claim that cites it AT RISK, and every decision on those claims. Today `cites` is not in `RISKY`.
+- **Supersession of sources**: a newer edition or a correction `supersedes` the old source node; claims on the old
+  one are STALE until re-cited.
+- `derived_from`, `based_on`, `rests_on` as usual.
+
+## Freshness
+
+A source has `retrieved`; the profile sets `max_age` (none by default; a task may set "sources newer than 2024").
+A claim whose only sources are older than `max_age` is STALE. A URL source is fresh while its content hash (stored
+at retrieval, when the host fetched it) matches a re-fetch; the instrument can re-fetch and compare, as it re-runs
+code for results.
+
+## Typed sources
+
+| kind | required fields | note |
+|---|---|---|
+| `primary` | `citation`, `url` or `doi`, `passage`, `retrieved` | the thing itself: a paper, a dataset, a document |
+| `secondary` | the same + `cites` (what it summarises) when known | an encyclopaedia, a review |
+| `tertiary` | the same | an index, a listing; a claim resting only on tertiary sources is flagged |
+| `excerpt` artifact | `sha256`, `source` (id), `path` | the fetched text, hashed, for the re-fetch check |
+
+## Evidence rank
+
+`two_independent_primary > primary > secondary > tertiary > unsourced`. "Independent" = different publishers,
+not two pages of one site.
+
+## Report
+
+"Sourced brief": each question with its answer, the claim, the source (citation, passage), the checker's verdict;
+unanswered questions with what was searched; sources by kind; what is stale or withdrawn.
+
+## Completion
+
+`questions_settled` + `all_sourced` (today) + **`all_checked`**: every claim in the brief has a fact-checker's
+review.
+
+## Refusals this workflow adds
+
+- `PASSAGE_MISSING`: a source without the passage that says the thing.
+- `NUMBER_NOT_IN_PASSAGE`: a claim number that the cited passage does not contain (0.4.1 allows passage numbers;
+  this is the converse refusal).
+- `TERTIARY_ONLY` (warning): a finding resting only on tertiary sources.
+
+## Review questions and decisions (2026-10-26)
+
+1. *Is `searched` required?* **Optional** (reported, never blocks); a task that wants a systematic answer puts
+   `search_recorded` in its `done_when`.
+2. *The re-fetch check?* **P3**, with `NUMBER_NOT_IN_PASSAGE`; both need the host's fetch at review time.
+3. *Can the fact-checker re-kind a source?* **Yes**: `corrects` now joins sources; the correcting source carries
+   the kind, and the old one is superseded.
+
+Also decided: "compiled" is not a question stage — the report is investigation-level and stays under completion
+(`report_clean` on the investigation order). The knowledge stages are asked → searched (optional) → sourced →
+claimed → checked.

hypgraph-0.5.0/docs/workflows/optimization.md

@@ -0,0 +1,80 @@
+# Workflow: `optimization`
+
+## The method it is taken from
+
+Operations-research practice: a problem is modelled (objective, decision variables, constraints) before it is
+solved; a solution is only a solution if it is feasible; "optimal" is a statement about a **bound**, not about
+effort; and a solver's answer is verified against the constraints by someone other than the modeller. The
+mixed-integer programming convention that an incumbent is reported with its optimality gap (the gap between the
+best solution and the best bound); the sensitivity-analysis norm that a recommendation says how it changes when
+the data does; and the modelling-lifecycle view (Williams, *Model Building in Mathematical Programming*) that the
+model is a hypothesis about the problem and can be wrong independently of the solver.
+
+## Stages
+
+| # | stage | holds | gate out of it | who |
+|---|---|---|---|---|
+| 1 | posed | question: what to minimise or maximise, under which constraints; the instance as an artifact | `instance_registered` **new**: an artifact `kind=instance` with its sha | lead |
+| 2 | modelled | hypothesis = the modelling choice (variables, objective, constraints as stated); `predictions` = what the solution should look like | `hypothesis_stated` **new** | modeller |
+| 3 | configured | experiment = the solve configuration: solver, time limit, tolerances, `tests` the hypothesis | `preregistered` **new** (the configuration precedes the solve) | solver |
+| 4 | solved | run `executes` the experiment, `uses` the instance; result with `objective`, `feasible`, `bound`, `gap`, `runtime_s`, `solution` artifact | `feasible_bounded` (today) | solver, instrument |
+| 5 | verified | review by the verifier: the solution satisfies the constraints of the **instance artifact** (recomputed, not trusted) | `reviewed` with method naming the check | verifier |
+| 6 | claimed | claim "best found, gap g" or "optimal" with the bound; `OPTIMAL_WITHOUT_BOUND` (today) | `claim_made` | solver |
+| 7 | recommended | decision `based_on` the claim: the incumbent to use, with the sensitivity note | `decided` **new** | lead |
+
+Infeasibility is a settled outcome: a result with `feasible: false` and a claim of `kind=exclusion` ("no feasible
+assignment exists: total capacity 7 < 8 customers") settles the question. Today that path trips
+`ABSOLUTE_WITHOUT_COUNT`; the workflow makes "no feasible X" bind to the result's `feasible` value.
+
+## Invalidation
+
+- **A changed instance** (new sha) `supersedes` the old instance artifact; every run that `uses` it is STALE, its
+  results, claims and the recommendation AT RISK. Same mechanism as software's new head.
+- A revised model (new hypothesis version) marks solves of the old model as "of the old model".
+- `uses`, `derived_from`, `based_on`, `rests_on`.
+
+## Freshness
+
+Fresh = the run's instance artifact is the live one and the model hypothesis is at its reviewed version.
+
+## Typed artifacts
+
+| kind | required fields | note |
+|---|---|---|
+| `instance` | `sha256`, `path`, `size` | the data the model is solved on |
+| `solution` | `sha256`, `path`, `objective`, `feasible` | the assignment / schedule / plan |
+| `model` | `sha256`, `path` (the formulation file), `solver` | optional; when the model is a file |
+
+## Evidence rank
+
+`proven_optimal (gap 0 or bound = objective) > bounded (gap stated) > feasible_only > infeasible_claimed >
+unverified`. A `bound` that comes from enumeration counts as a proof for the instance size it names.
+
+## Report
+
+"Solution report": the problem; the model (variables, objective, constraints); the configuration; the incumbent
+with objective, feasibility, bound and gap; the verifier's check; the recommendation and its sensitivity; what is
+stale (solves on superseded instances or models).
+
+## Completion
+
+`questions_settled` + `incumbent_feasible` (today) + **`verified`**: the incumbent has a verifier's review that
+recomputed feasibility.
+
+## Refusals this workflow adds
+
+- `SOLVED_WITHOUT_INSTANCE`: a run with no `uses` → instance artifact.
+- `VERIFIED_BY_SOLVER`: a review of a solution by its own author.
+- `OPTIMAL_ON_STALE_INSTANCE`: "optimal" bound to a solve whose instance is superseded.
+
+## Review questions and decisions (2026-10-26)
+
+1. *The model: hypothesis or experiment?* **Hypothesis** (`modelled`, gate `hypothesis_stated`): it can be wrong
+   independently of the solve and is revisable with its own version.
+2. *Mechanical feasibility recomputation?* **P3** (`check_solution` reproducer). Built now: `result_reviewed` —
+   the verifier's check on the result, by someone who is not its author — and `incumbent_verified` needs it on the
+   current instance.
+3. *Sensitivity?* **An optional `sensitivity` field on the decision.**
+
+Also decided: `SOLVED_WITHOUT_INSTANCE` refuses a solve result with no producing run as well as one whose run uses
+no instance — otherwise the gate is dodged by not linking the run.

hypgraph-0.5.0/docs/workflows/scientific.md

@@ -0,0 +1,75 @@
+# Workflow: `scientific`
+
+## The method it is taken from
+
+The hypothetico-deductive method as practised in empirical science, with the modern discipline of
+**preregistration**: state the hypothesis and the analysis before seeing the outcome, so the test cannot be bent
+to the result. Popper's criterion that a scientific statement must be falsifiable; the Center for Open Science's
+preregistration practice (hypothesis, design, analysis plan fixed before data); and the replication norm that a
+finding stands on independent lines of evidence, not repeated copies of one. HypGraph's kernel was built from this
+workflow, so this spec mostly names what the kernel already does and marks the two things it doesn't.
+
+## Stages
+
+| # | stage | holds | gate out of it | who |
+|---|---|---|---|---|
+| 1 | asked | question | the question is stated (`question` node with `text`) | lead |
+| 2 | conjectured | hypothesis with `predictions` | `hypothesis_stated` **new**: a hypothesis `answers` the question with at least one checkable prediction | lead / worker |
+| 3 | preregistered | experiment with `aim`, `protocol`, `success_criteria`, `tests` → hypothesis with `expected` | `preregistered` **new**: an experiment `tests` the hypothesis with an expected outcome stated **before** any run `executes` it (created_at order) | worker |
+| 4 | run | run (`agent` or `lab`), artifacts it `uses` | `run_registered` | worker, instrument |
+| 5 | evidenced | result `produced` by the run, values | `result_exists`; the instrument's replicate when code was registered | worker, instrument |
+| 6 | claimed | claim with measurements, `answers` the question | `claim_made` | worker |
+| 7 | reviewed | review by a policy reviewer, not the author | `reviewed` | reviewer |
+| 8 | decided | decision `based_on` the claim | `decided` **new** (optional stage; required only when the task asks for a decision) | lead |
+
+A question is **settled** at stage 7 (today's rule). Stage 3's gate is what preregistration adds: an experiment
+created *after* its run's result is not preregistered, and its result's evidence rank is capped at `exploratory`.
+
+## Invalidation (at-risk relations)
+
+Today's set, unchanged: `requires`, `derived_from`, `based_on`, `works_on`, `rests_on`. Plus **`uses`**: a run
+that `uses` an artifact which is later withdrawn (a corrected data file) puts its results, their claims and the
+decisions on them AT RISK — the F7 case. Today this works only through `derived_from` chains that happen to pass
+through the artifact; it should be the relation itself.
+
+## Freshness
+
+A result is fresh while every artifact its run `uses` is the live version (same sha). A result on a withdrawn or
+superseded artifact is STALE; a claim resting only on stale results needs a rerun before a review counts.
+
+## Typed artifacts
+
+| kind | required fields | note |
+|---|---|---|
+| `data` | `sha256`, `path`, `size` | what the run read; registered by the task or the host |
+| `protocol` | `sha256`, `path` | the analysis code or plan, when it is a file |
+| `figure` | `sha256`, `path`, `format` | produced by a run |
+
+## Evidence rank (unchanged)
+
+`external > new_data > separate_implementation > same_code > unverified`, from `replicates` links and their
+`differs` field; an unprovenanced line counts once.
+
+## Report
+
+"Facts from the record" as today: claims with standing and verdicts, results and whether a claim carries them,
+hypotheses, experiments (preregistered or not), open items, spend; interpretation underneath; linted.
+
+## Completion
+
+`questions_settled` (today). Optional: `decisions_recorded` when the task asked for a decision.
+
+## Refusals this workflow adds
+
+- `EXPERIMENT_AFTER_RUN`: an experiment linked `tests` after a run already `executes` it — allowed, but the record
+  marks the result exploratory and says so.
+- `STALE_EVIDENCE`: a review on a claim whose only results are stale is recorded as `comment`, not `checked`.
+
+## Review questions and decisions (2026-10-26)
+
+1. *Preregistration: a gate or a label?* **A gate** (`preregistered`: the experiment, with its expected outcome,
+   precedes any run that executes it; one written after is named as such). The evidence-rank cap is not built:
+   `report()` already lists experiments as preregistered or not, and the gate's reason says why.
+2. *Is `decided` a scientific stage?* **Optional**: reported, never blocks; a question is complete at `reviewed`.
+3. *`uses` as at-risk changes old records?* **Only under `scientific@2`** (`derive.EXTRA_RISKY`); `@1` records derive
+   exactly as before. Freshness (`stale`) is universal, since no record could have had a superseded artifact.

hypgraph-0.5.0/docs/workflows/software.md

@@ -0,0 +1,78 @@
+# Workflow: `software`
+
+## The method it is taken from
+
+Continuous integration and code review as practised in professional engineering: a change is a reviewable unit
+against a known base; the tests that count are the ones a machine ran on **that** change; nothing merges without
+them; and a later change re-opens the question. Fowler's continuous integration ("every commit is built and
+tested"), the pull-request review norm (author ≠ approver), and the DORA practice of trunk-based delivery where a
+release is a decision on evidence the pipeline produced. The requirement plays the role of the question; the
+instrument plays the role of CI.
+
+## Stages
+
+| # | stage | holds | gate out of it | who |
+|---|---|---|---|---|
+| 1 | specified | question = the requirement or the bug, with acceptance stated | the question has an acceptance criterion in its text or `success_criteria` **new** on a linked experiment (the test plan) | lead |
+| 2 | implemented | artifact `kind=diff` registered: `base_sha`, `head_sha`, `files`, `sha256` of the patch | `diff_registered` **new**: a diff artifact `part_of` the question, newer than the last one | implementer |
+| 3 | verified | run `kind=lab` that `uses` the diff artifact; result `tests` with `passed k of n`, `exit_code` | `tests_pass` **on that head**: the instrument's run `uses` the diff whose `head_sha` is current | tester, instrument |
+| 4 | claimed | claim "requirement met" with measurements bound to the lab result | `claim_made`; validator `PASS_WITHOUT_INSTRUMENT_RUN` (today) | tester |
+| 5 | reviewed | review by a reviewer who is not the diff's author | `reviewed` | reviewer |
+| 6 | released | decision `based_on` the claim: merge / ship / hold, with the head_sha it releases | `decided` **new** | lead |
+
+## Invalidation
+
+- A **new diff artifact** on the same question (a newer `head_sha`) `supersedes` the old one. Every lab run that
+  `uses` the old diff is STALE; its results, the claims on them, and the release decision go AT RISK. This is the
+  gate a prompt cannot keep: the model that ran the tests at 14:02 does not know about the commit at 14:10.
+- `uses`, `derived_from`, `based_on`, `rests_on` as at-risk relations (as scientific), plus **`supersedes` on
+  artifacts** (today supersedes is for claims and decisions only).
+
+## Freshness
+
+A test result is fresh only if the diff its run `uses` has the current `head_sha` for the question. A `tests_pass`
+predicate evaluated on a stale run is NOT MET with the reason "tests ran on <old sha>; current head is <new sha>".
+
+## Typed artifacts
+
+| kind | required fields | note |
+|---|---|---|
+| `diff` | `base_sha`, `head_sha`, `files` (list), `sha256` (of the patch), `path` | the reviewable unit |
+| `test_run` | `command`, `exit_code`, `passed`, `failed`, `sha256` (of the log) | produced by the instrument's run |
+| `build` | `head_sha`, `sha256` (of the artifact), `path` | optional |
+
+A diff registered by an agent is `kind=agent` provenance; only the instrument's `uses` of it makes it evidence.
+
+## Evidence rank
+
+`lab_on_current_head > lab_on_old_head (stale) > agent_reported > unverified`. Replication across environments
+(`new_env`: another OS or Python) ranks above `same_code` as in scientific.
+
+## Report
+
+"Change report": the requirement; the diff (base → head, files); the instrument's test run on that head (passed k
+of n, exit code, command); the claim and its review; the release decision; **what is stale** (any earlier runs on
+superseded heads, listed as superseded); open requirements.
+
+## Completion
+
+`requirements_verified` (today) tightened: every requirement's claim rests on a lab run whose diff is current. Plus
+`released` when the task asks for a release decision.
+
+## Refusals this workflow adds
+
+- `TESTS_ON_STALE_HEAD`: a claim of passing bound to a lab result whose diff is superseded.
+- `DIFF_WITHOUT_BASE`: a diff artifact without `base_sha` / `head_sha`.
+- `REVIEW_BY_AUTHOR`: a review of a claim whose diff the reviewer authored (today only the claim's author is
+  blocked; the diff's author should be too).
+
+## Review questions and decisions (2026-10-26)
+
+1. *Requirement = question or experiment?* **Question**, with the test plan as an experiment linked to it. Stage 1's
+   gate is the question itself (`stated`); an acceptance criterion in `success_criteria` is encouraged, not gated.
+2. *Diff bytes or hashes?* **Hashes and the file list** (`artifact.kind=diff`, `meta: base_sha, head_sha, files`,
+   `sha256` of the patch); the host keeps the bytes.
+3. *CI as the instrument?* **P3.** Built now: the `uses` relation to the current diff is what `tests_pass_current`
+   reads, so a CI reproducer only has to file a lab run that `uses` the diff.
+
+Also decided: `REVIEW_BY_AUTHOR` covers the diff's author (built); `supersedes` joins artifacts (built).

hypgraph-0.5.0/docs/workflows/trading.md

@@ -0,0 +1,81 @@
+# Workflow: `trading`
+
+## The method it is taken from
+
+Quantitative strategy research as the sceptical part of the field describes it: a thesis is a hypothesis; its
+test is a backtest whose window, costs and rules are fixed **before** it runs (the trading analogue of
+preregistration); only an **out-of-sample, after-cost** result speaks to an edge; and a result has a shelf life.
+Bailey, Borwein, López de Prado and Zhu on backtest overfitting ("the probability of backtest overfitting" — the
+more configurations tried, the less an in-sample result means); the deflated Sharpe ratio; walk-forward
+validation; and the risk-management norm that a position is a sized decision with a stop and a review date, taken
+by someone other than the analyst. No live-order path exists anywhere in this workflow.
+
+## Stages
+
+| # | stage | holds | gate out of it | who |
+|---|---|---|---|---|
+| 1 | asked | question: the market question | stated | lead |
+| 2 | thesised | hypothesis with `predictions` = the move, the horizon, the universe | `hypothesis_stated` **new** | quant |
+| 3 | preregistered | experiment: `protocol` names the in-sample and out-of-sample windows, the costs (fees, slippage), the rules, the number of configurations to be tried; `expected` on the `tests` link | `preregistered` **new**: the experiment exists **before** the run that `executes` it, with windows and costs in the protocol | quant |
+| 4 | backtested | run `executes` the experiment, `uses` the data artifact; result with `oos_*` and cost values, `trials` (configurations tried) | `backtested_oos` (today) + **`trials_declared`** new: the result states how many configurations were tried | quant, instrument |
+| 5 | claimed | claim about the edge or its absence, bound to the oos result | `claim_made`; validators `EDGE_WITHOUT_OOS_COSTS`, `BACKTEST_WITHOUT_COSTS` (today), **`EDGE_WITHOUT_TRIALS`** new | quant |
+| 6 | risk-reviewed | review by the risk seat (never the quant) | `reviewed` | risk |
+| 7 | positioned | decision `based_on` the claim: `size`, `stop`, `review_date`, `paper: true` | `position_recorded` (today's completion criterion becomes a gate) | lead |
+| 8 | monitored | later results on the same hypothesis with newer data; notices | `still_valid` **new**: a result newer than the position's `review_date` or a regime check on the hypothesis | quant, risk |
+
+## Invalidation
+
+- **Expiry.** A backtest result carries `valid_until` (default: the decision's `review_date`). Past it the result is
+  STALE and the position AT RISK until a newer result on the same hypothesis exists.
+- **Regime notice.** A host notice ("regime changed: rates / volatility / venue") withdraws the data artifact's
+  claim to represent the present; every position whose claim rests on results `uses`-ing it goes AT RISK.
+- `uses`, `derived_from`, `based_on`, `rests_on` as at-risk relations.
+
+## Freshness
+
+Fresh = `now ≤ valid_until` and the data artifact the run `uses` is live. A claim of an edge on a stale result is
+reported as "edge as of <window>, not re-tested since".
+
+## Typed artifacts and decisions
+
+| kind | required fields | note |
+|---|---|---|
+| artifact `prices` | `sha256`, `path`, `from`, `to`, `frequency` | the data window |
+| artifact `backtest` | `sha256` (of the code), `path`, `trials` | the code and how many configurations it tried |
+| decision `position` | `size`, `stop`, `review_date`, `paper` (must be true), `based_on` → claim | the only kind of position the record accepts |
+
+## Evidence rank
+
+`oos_after_costs_new_data > oos_after_costs > in_sample > unverified`. A result whose `trials` is large relative to
+its window is flagged (the overfitting warning), not refused.
+
+## Report
+
+"Desk note": the thesis; the preregistered protocol (windows, costs, trials); the out-of-sample result after costs
+with the trade count; the risk review; the position (size, stop, review date, paper); what is stale or past review;
+open theses.
+
+## Completion
+
+`questions_settled` + `position_recorded` (today) + **`nothing_past_review`**: no position whose `review_date` has
+passed without a newer result.
+
+## Refusals this workflow adds
+
+- `EDGE_WITHOUT_TRIALS`: "edge" on a result that does not state how many configurations were tried.
+- `POSITION_WITHOUT_STOP`: a position decision missing `size`, `stop` or `review_date`.
+- `LIVE_ORDER`: any decision or artifact kind that names a venue order; there is no path, and the refusal says so.
+- `BACKTEST_AFTER_PROTOCOL_EDIT`: an experiment revised after its run (a changed window) — allowed, but the result
+  is re-ranked `in_sample`.
+
+## Review questions and decisions (2026-10-26)
+
+1. *Will agents report `trials` honestly?* **Required now, checked later**: `backtested` and `EDGE_WITHOUT_TRIALS`
+   need the value; the instrument's count of the parameter grid is P3.
+2. *`review_date` default?* **Required, no default** (`POSITION_WITHOUT_STOP` names what is missing).
+3. *Who raises a regime notice?* **The host or the risk seat**: it is a withdrawal (or supersession) of the data
+   artifact, which only they write; `uses` then carries it to every position.
+
+Also decided: `still_valid` counts a result as newer only if written after both the review date and the position
+(the evidence a position was taken on doesn't renew it). `BACKTEST_AFTER_PROTOCOL_EDIT` is not a separate refusal:
+`preregistered` already names an experiment written after its run.

{hypgraph-0.4.2 → hypgraph-0.5.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.4.2"
+__version__ = "0.5.0"
 
 from .bundle import verify_bundle  # noqa: E402
 from .graph import Author, Graph, GraphError, file_sha256  # noqa: E402