hypgraph 0.5.1__tar.gz → 0.5.3__tar.gz

{hypgraph-0.5.1 → hypgraph-0.5.3}/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.5.3 — 2026-10-26: results that name no file can go stale
+
+- **A result that names no file it read can go stale.** Under a workflow (`@2` profiles), a result whose run has no
+  `uses` link was fresh forever, however the files changed. It now goes STALE once an input file of its
+  investigation is replaced or withdrawn after the result was written ("it names no file it read, and A1 changed
+  after it was written"), and claims resting only on it with it. A file registered on another question only
+  (`part_of`) doesn't count against it; run outputs and page excerpts never do; a result written after the change
+  is fresh; a result that names its files keeps the usual rule (only those files count). Ordered by the event log,
+  not timestamps. Records without a workflow are unchanged. Measured on 851 results in HypSwarm's stored study
+  records: none changes standing.
+
+## 0.5.2 — 2026-10-26: freshness for sources, stale evidence in the report
+
+For P3 (the change suite and the instruments in HypSwarm), the record had to know when a *page* moved, not only a
+file:
+- **A source is fresh while its page still says it.** A host that re-fetches a source's page registers an
+  `excerpt` artifact (`derived_from` the source; `meta.contains_passage`, `meta.fetched`). The source is STALE when
+  every excerpt of it was superseded, or the live one says the page no longer contains its passage — an edit
+  elsewhere on the page keeps it fresh. A source never re-fetched is not stale: nothing says it moved.
+- **A claim is stale when every result and every cited source behind it is.** The knowledge gates
+  (`source_quoted`, `sourced`) take only fresh sources, so a changed page reopens the question at *sourced*.
+- **The report marks it.** Claims and results on stale evidence read `checked · STALE` in the facts tables, a new
+  open item lists them, the workflow section lists stale sources too, and the report check treats calling a stale
+  claim settled as `REPORT_OVERSTATES_STANDING`.
+- **Gates count only what still speaks for the question.** `result_exists`, `backtested` and `solved` take only
+  fresh results (their message says which went stale and why); `result_reviewed` doesn't count a check of a stale
+  result; a decision is stale when everything it was based on is, and `positioned` / `decided` take only fresh ones
+  — a position taken on a backtest the vendor later corrected has to be decided again.
+- **The report check reads the answers block.** A fenced ```answers block (the part of a report a harness scores and a
+  reader copies) was skipped like any code block, so a report could carry an answer only stale evidence gave and pass.
+  Now each answer has to be one a current claim on its question makes — live, not stale — at the precision written and
+  with its sign: `REPORT_ANSWER_STALE` when only old claims or stale results give it (or a current claim binds the
+  same field to another value), `REPORT_ANSWER_UNBACKED` when no claim does or the question has no claim,
+  `REPORT_ANSWERS_UNREADABLE` for invalid JSON. Results count through the claims that bind them, and a count k of n
+  backs its rate; a number a claim names only as a superseded figure doesn't back an answer; URLs, paths and hashes
+  are provenance. Keys are question codes in any case, or a flat object checked against the investigation. Found by
+  HypSwarm's change suite.
+- **The report check skips the record's own facts.** A line inside a "Facts from the research graph" block is not
+  linted when it is exactly a line the record generates now (a hypothesis that says "significantly" is a conjecture
+  the record lists, not the author's assertion). Anything else written under that heading is checked as usual.
+  Found when a report was refused for the hypothesis line the record itself had written.
+
 ## 0.5.1 — 2026-10-26
 
 What wiring HypSwarm's scheduler to the stages (P2) found the workflows had no honest ending or no right answer for:

{hypgraph-0.5.1 → hypgraph-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hypgraph
-Version: 0.5.1
+Version: 0.5.3
 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/
@@ -135,21 +135,31 @@ 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.
+acceptance and done — and, from 0.5, carries the discipline's own **workflow**: the stages a question passes
+through, the gate out of each, what invalidates evidence, the typed shapes. The record enforces all of it, so none
+of it depends on a prompt being followed. Pin one on the investigation (`"profile": "software@2"`); without one, the
+record behaves exactly as before.
 
-| profile | an order is done when… | the record refuses | the investigation is done when |
+| profile | the stages a question passes through | the record refuses | 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.
+| `scientific@2` | asked → conjectured → preregistered (**before** any run) → run → evidenced → claimed → reviewed | numbers no result accounts for, "never" without the count, "significant" without the test, a check on stale evidence | every question settled |
+| `software@2` | specified → implemented (a diff by hash) → verified (**the instrument ran the tests on that head**) → claimed → reviewed | *"it passes"* without an instrument run, or on a superseded head; the diff's author as its reviewer | every requirement's claim rests on a passing run on the current head |
+| `trading@2` | asked → thesised → preregistered → backtested (**out of sample, after costs, trials declared**) → claimed → risk-reviewed → positioned → monitored | a backtest without its costs; *"edge"* without both, or without the configurations tried; a position without size, stop, review date; any live order | questions settled, a position taken or declined, nothing past its review date |
+| `knowledge@2` | asked → (searched) → sourced (**the passage**, retrieved, kind) → claimed → checked | a claim with no source; a source without its passage | every claim cites a source and is checked |
+| `optimization@2` | posed (the instance by hash) → modelled → configured → solved → verified → claimed → checked | an objective without feasibility; *"optimal"* without a bound, or on a changed instance; a solve that uses no instance | a feasible bounded incumbent, verified on the current instance |
+
+**The stage is derived, never set**: `g.stage(question)` reads it off the record (the first stage whose gate is not
+met, every gate MET / NOT MET with what would meet it); `GET /api/graph/stages`; MCP tool `stage`. A workflow
+widens what puts dependants AT RISK — `uses` (a corrected data file, a superseded diff or instance), `cites` (a
+withdrawn source) — and evidence goes **stale** when the artifact it used is superseded or its `valid_until` has
+passed. A result whose run names no file it read goes stale when an input file of its question changes after it:
+nothing shows it read the new version (name the files with `uses` and only those count). An honest "it can't be answered" (a checked `inconclusive` claim), a declined thesis (`no_position`) and a
+verified failure each complete a question the gates alone never would.
+
+Profiles are versioned and frozen: a record written under `trading@1` means the same thing in a year, and the `@1`
+profiles stay exactly as they were. `completion(inv)` reports each criterion; `hypgraph serve` exposes
+`/api/graph/completion` and `/api/graph/profiles`. The method each workflow is taken from is quoted, one page each,
+in [docs/workflows/](docs/workflows/). Adding a discipline is one `Profile` with a `Workflow`.
 
 ## Connect your agent
 

{hypgraph-0.5.1 → hypgraph-0.5.3}/README.md

@@ -103,21 +103,31 @@ 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.
+acceptance and done — and, from 0.5, carries the discipline's own **workflow**: the stages a question passes
+through, the gate out of each, what invalidates evidence, the typed shapes. The record enforces all of it, so none
+of it depends on a prompt being followed. Pin one on the investigation (`"profile": "software@2"`); without one, the
+record behaves exactly as before.
 
-| profile | an order is done when… | the record refuses | the investigation is done when |
+| profile | the stages a question passes through | the record refuses | 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.
+| `scientific@2` | asked → conjectured → preregistered (**before** any run) → run → evidenced → claimed → reviewed | numbers no result accounts for, "never" without the count, "significant" without the test, a check on stale evidence | every question settled |
+| `software@2` | specified → implemented (a diff by hash) → verified (**the instrument ran the tests on that head**) → claimed → reviewed | *"it passes"* without an instrument run, or on a superseded head; the diff's author as its reviewer | every requirement's claim rests on a passing run on the current head |
+| `trading@2` | asked → thesised → preregistered → backtested (**out of sample, after costs, trials declared**) → claimed → risk-reviewed → positioned → monitored | a backtest without its costs; *"edge"* without both, or without the configurations tried; a position without size, stop, review date; any live order | questions settled, a position taken or declined, nothing past its review date |
+| `knowledge@2` | asked → (searched) → sourced (**the passage**, retrieved, kind) → claimed → checked | a claim with no source; a source without its passage | every claim cites a source and is checked |
+| `optimization@2` | posed (the instance by hash) → modelled → configured → solved → verified → claimed → checked | an objective without feasibility; *"optimal"* without a bound, or on a changed instance; a solve that uses no instance | a feasible bounded incumbent, verified on the current instance |
+
+**The stage is derived, never set**: `g.stage(question)` reads it off the record (the first stage whose gate is not
+met, every gate MET / NOT MET with what would meet it); `GET /api/graph/stages`; MCP tool `stage`. A workflow
+widens what puts dependants AT RISK — `uses` (a corrected data file, a superseded diff or instance), `cites` (a
+withdrawn source) — and evidence goes **stale** when the artifact it used is superseded or its `valid_until` has
+passed. A result whose run names no file it read goes stale when an input file of its question changes after it:
+nothing shows it read the new version (name the files with `uses` and only those count). An honest "it can't be answered" (a checked `inconclusive` claim), a declined thesis (`no_position`) and a
+verified failure each complete a question the gates alone never would.
+
+Profiles are versioned and frozen: a record written under `trading@1` means the same thing in a year, and the `@1`
+profiles stay exactly as they were. `completion(inv)` reports each criterion; `hypgraph serve` exposes
+`/api/graph/completion` and `/api/graph/profiles`. The method each workflow is taken from is quoted, one page each,
+in [docs/workflows/](docs/workflows/). Adding a discipline is one `Profile` with a `Workflow`.
 
 ## Connect your agent
 

{hypgraph-0.5.1 → hypgraph-0.5.3}/docs/profile-workflows-plan.md

@@ -95,7 +95,7 @@ instrument, mechanical feasibility recomputation (P3). **P2 built in HypSwarm 0.
 orders, review on the node the previous gate produced, the record's word on done; the examples' scripted models walk
 the stages; the discovery stub run through its stages). P2 fed back into hypgraph 0.5.1: honest endings the stages
 lacked (a declined thesis, an inconclusive answer, a verified failure), artifacts that learn their kind on
-re-registration, optimization's `checked` stage. P3 is next.
+re-registration, optimization's `checked` stage. **P3 built (2026-10-26):** the instruments in HypSwarm 0.1.0a5 (world watcher, re-verification, source re-fetch, refresh orders) and hypgraph 0.5.2 (source freshness, fresh-only gates, stale in the report); the change suite in HypSwarm `studies/discovery/PLAN-CHANGE.md`, self-test and stub run at $0, predictions locked; the model run waits for the spend approval.
 
 ## 4. What stays as it is, on purpose
 

{hypgraph-0.5.1 → hypgraph-0.5.3}/docs/spec.md

@@ -209,7 +209,9 @@ A report aggregates per author (refused, fixed, open, codes) and per rule.
 ## 9. Checking a write-up against the record
 
 A checker reads markdown sentence by sentence and checks it against the record. Code blocks, inline code, URLs, link
-targets and HTML comments are skipped. Quoted passages and negated words ("cannot be proven") are not treated as
+targets and HTML comments are skipped, except a fenced block whose info string is `answers`: that is the report's
+machine-read answer (a JSON object, keyed by question code or flat), and every number or true / false in it is checked
+against the claims. Quoted passages and negated words ("cannot be proven") are not treated as
 the writer's assertion. Codes are matched within the investigation being reported on.
 
 | level | code | when |
@@ -220,6 +222,9 @@ the writer's assertion. Codes are matched within the investigation being reporte
 | error | `REPORT_ABSOLUTE_UNBACKED` | never / always / impossible / guaranteed / eliminates / proven / 100% asserted, not in an instruction, with no cited claim carrying a count with k ∈ {0, n} |
 | error | `REPORT_ABSENCE_UNBACKED` | "no effect" / "rules out" / "doesn't matter" without citing a claim filed as `exclusion` or `inconclusive` |
 | error | `REPORT_SIGNIFICANCE_UNBACKED` | "significantly" without a p-value or interval in the sentence and without citing a node that carries a test (a negated "not significant" is a warning) |
+| error | `REPORT_ANSWER_STALE` | a value in the `answers` block that only stale, superseded or withdrawn claims (or stale results) on that question give, or that a current claim binds to a different value under the same field while an old one binds it to this; or a question whose every claim is old |
+| error | `REPORT_ANSWER_UNBACKED` | a value in the `answers` block that no current claim on the question states or binds, at the precision the answer gives it and with its sign (a count k of n, bound or written as "k of n", backs its rate); or a question answered with no claim at all. A number a claim names only as a figure that no longer holds ("the earlier count of 789 is superseded") doesn't back it. URLs, paths and hashes in the block are provenance and aren't checked. |
+| error | `REPORT_ANSWERS_UNREADABLE` | the `answers` block isn't valid JSON |
 | warning | `REPORT_UNSOURCED_NUMBER` | a number not contained in or implied by the investigation's results, live claims' measurements, statements and scopes, the investigation's scope and constants, or experiment and run settings. Integers ≤ 12, years, dates, times and 7-digit+ ids are skipped. Statistical quantities need one decimal. |
 | warning | `REPORT_OMITS_DISPUTE` | cites a contested or at-risk node without saying so |
 | warning | `REPORT_CITES_SUPERSEDED` | cites a superseded node without saying so |

{hypgraph-0.5.1 → hypgraph-0.5.3}/docs/workflows/knowledge.md

@@ -73,7 +73,11 @@ review.
 
 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.
+2. *The re-fetch check?* **Built in P3** (hypgraph 0.5.2 + HypSwarm 0.1.0a5): a host's `refetch(url)` files each
+   source's page as an `excerpt` artifact with `contains_passage`; a page that no longer says the passage makes the
+   source and the claims citing it stale, and the question returns to *sourced*. `NUMBER_NOT_IN_PASSAGE` is not a
+   separate refusal: a claim number that is in no bound result and not in the cited passage is already
+   `UNBOUND_NUMBER`.
 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.
 

{hypgraph-0.5.1 → hypgraph-0.5.3}/docs/workflows/optimization.md

@@ -72,7 +72,10 @@ recomputed feasibility.
 
 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` —
+2. *Mechanical feasibility recomputation?* **Built in P3 as re-execution**: the instrument re-runs the solver's
+   registered code on the instance as it is now (a changed instance is a new artifact that supersedes the old), so
+   objective, feasibility and bound are recomputed mechanically; a domain-specific `check_solution` reading a
+   solution artifact stays a host hook for later. Built in P1: `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.**

{hypgraph-0.5.1 → hypgraph-0.5.3}/docs/workflows/software.md

@@ -77,6 +77,12 @@ superseded heads, listed as superseded); open requirements.
 
 Also decided: `REVIEW_BY_AUTHOR` covers the diff's author (built); `supersedes` joins artifacts (built).
 
+**CI as the instrument (P3, HypSwarm 0.1.0a5).** `run(..., watch=True)` keeps the working tree of the task's
+files as one `kind=diff` artifact that every commit supersedes; a run under an order uses the question's current
+head; when a head moves, the instrument re-runs every stale result's command on the new tree — the same values bring
+the claim back with no model call, a moved count leaves it stale and the question is redone. That is the CI rule
+("tests on this commit"), kept by the record rather than by a pipeline.
+
 **Verified failure (0.5.1).** When the instrument's run on the current head records a negative result ("1 of 2
 checks pass"), `tests_pass_current` can never be met; a checked claim resting on that result settles the
 requirement as a verified failure (`stage()` says so), and `requirements_verified_current` stays unmet. The record

{hypgraph-0.5.1 → hypgraph-0.5.3}/docs/workflows/trading.md

@@ -70,8 +70,10 @@ passed without a newer result.
 
 ## 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.
+1. *Will agents report `trials` honestly?* **Required, and checked like any value**: `backtested` and
+   `EDGE_WITHOUT_TRIALS` need it, and the instrument's re-run confirms or contradicts the printed `trials` as it does
+   every registered value. Counting a parameter grid statically from arbitrary code was not built (P3): it can't be
+   done reliably, and a wrong count would be worse than the confirmed one.
 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.

{hypgraph-0.5.1 → hypgraph-0.5.3}/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.5.1"
+__version__ = "0.5.3"
 
 from .bundle import verify_bundle  # noqa: E402
 from .graph import Author, Graph, GraphError, file_sha256  # noqa: E402

{hypgraph-0.5.1 → hypgraph-0.5.3}/src/hypgraph/derive.py

@@ -146,6 +146,14 @@ def risky(s: Snap, x: str) -> tuple:
     return RISKY + extra if extra else RISKY
 
 
+def workflow_profile(s: Snap, x: str) -> bool:
+    """Whether x's investigation runs a profile with a workflow (the @2 profiles): freshness rules that need the files
+    to be registered apply only there."""
+    inv = s.nodes.get(s.nodes[x]["inv"]) if x in s.nodes else None
+    pid = str((inv or {}).get("body", {}).get("profile") or "").lower()
+    return bool(pid) and pid in EXTRA_RISKY
+
+
 def upstream(s: Snap, x: str) -> list[tuple[str, str]]:
     """What x rests on, one step: premises (requires), derivations, a decision's basis, and the run that produced it.
     Support is counted separately (unsupported): one fallen support among several doesn't break a claim."""
@@ -163,11 +171,90 @@ def downstream(s: Snap, x: str) -> list[tuple[str, str]]:
     return downs
 
 
+def excerpts(s: Snap, sid: str) -> list[str]:
+    """The pages a host fetched for a source: artifacts ``kind=excerpt`` derived_from it (oldest first)."""
+    return [e["src"] for e in s.inn.get(sid, []) if e["rel"] == "derived_from"
+            and s.nodes[e["src"]]["type"] == "artifact" and (s.nodes[e["src"]]["body"].get("kind") or "") == "excerpt"]
+
+
+def _order(s: Snap) -> tuple[dict, dict, dict]:
+    """When each node was created, each edge linked and each node withdrawn, as event sequence numbers (timestamps
+    are only to the second). Cached on the snapshot until the next event."""
+    cached = getattr(s, "_order_cache", None)
+    if cached and cached[0] == s.seq:
+        return cached[1]
+    made: dict[str, int] = {}
+    linked: dict[int, int] = {}
+    gone: dict[str, int] = {}
+    for e in s.events:
+        if e["kind"] == "create":
+            made.setdefault(e["ref"], e["seq"])
+        elif e["kind"] == "link" and isinstance(e.get("payload"), dict) and e["payload"].get("edge") is not None:
+            linked[int(e["payload"]["edge"])] = e["seq"]
+        elif e["kind"] == "withdraw":
+            gone.setdefault(e["ref"], e["seq"])
+    out = (made, linked, gone)
+    s._order_cache = (s.seq, out)                      # type: ignore[attr-defined]
+    return out
+
+
+def _moved_since(s: Snap, rid: str) -> list[str]:
+    """Input files of the result's investigation that were replaced or withdrawn after the result was written. A run
+    output (an artifact some run produced) and a page excerpt (a re-fetch supersedes it every time) don't count, and a
+    file registered on other questions only (``part_of``) doesn't count against a result on a different one."""
+    from .workflow import question_of                  # workflow imports derive; read lazily
+    made, linked, gone = _order(s)
+    t = made.get(rid)
+    if t is None:
+        return []
+    inv = s.nodes[rid]["inv"]
+    q: set | None = None
+    out = []
+    for aid, a in s.nodes.items():
+        if a["type"] != "artifact" or a["inv"] != inv or (a["body"].get("kind") or "") == "excerpt":
+            continue
+        if any(e["rel"] == "produced" for e in s.inn.get(aid, [])):
+            continue
+        on = {e["dst"] for e in s.out.get(aid, []) if e["rel"] == "part_of" and s.nodes[e["dst"]]["type"] == "question"}
+        if on:
+            if q is None:
+                # a result reaches its question through the claims built on it, as often as through its run
+                qs = {question_of(s, rid)} | {question_of(s, e["src"]) for e in s.inn.get(rid, [])
+                                               if e["rel"] == "derived_from"}
+                qs |= {question_of(s, e["dst"]) for e in s.out.get(rid, []) if e["rel"] == "supports"}
+                q = {x for x in qs if x}
+            if q and not (q & on):
+                continue
+        when = [linked.get(e["id"], 0) for e in s.inn.get(aid, []) if e["rel"] == "supersedes"]
+        if aid in gone:
+            when.append(gone[aid])
+        if any(w > t for w in when):
+            out.append(a["code"] or aid)
+    return out
+
+
 def stale(s: Snap, nid: str) -> list[str]:
     """Why a result (or a claim through its results) no longer speaks for what it measured; [] when fresh. A result
     is stale when the run that produced it used an artifact that is now superseded or withdrawn, or when its
-    ``valid_until`` has passed. A claim is stale when it has results and every one of them is stale."""
+    ``valid_until`` has passed. Under a workflow, a result whose run names no file it read (no ``uses``) is stale once
+    any input file of its investigation is replaced or withdrawn after it was written: nothing shows it read the
+    new one. A source is stale when the host re-fetched its page and the page as it is now no
+    longer contains its passage (the live excerpt says ``contains_passage: false``), or every excerpt of it was
+    superseded. A claim is stale when it has results or cited sources and every one of them is stale."""
     n = s.nodes[nid]
+    if n["type"] == "source":
+        ex = excerpts(s, nid)
+        if not ex:
+            return []                                  # never re-fetched: nothing says the page moved
+        live = [a for a in ex if lifecycle(s, a) == "active"]
+        if not live:
+            return [f"its page changed since it was read ({', '.join(s.nodes[a]['code'] or a for a in ex[-2:])} "
+                    "superseded)"]
+        meta = [s.nodes[a]["body"].get("meta") or {} for a in live]
+        if all(m.get("contains_passage") is False for m in meta):
+            when = max((str(m.get("fetched") or "") for m in meta), default="")
+            return [f"the page no longer contains its passage (re-fetched{' ' + when if when else ''})"]
+        return []
     if n["type"] == "result":
         out = []
         run = producing_run(s, nid)
@@ -179,15 +266,29 @@ def stale(s: Snap, nid: str) -> list[str]:
                 a = s.nodes[e["dst"]]
                 kind = a["body"].get("kind") or "artifact"
                 out.append(f"{kind} {a['code'] or e['dst']} is {lc}")
+        named = run and any(e["rel"] == "uses" for e in s.out.get(run, []))
+        if not named and workflow_profile(s, nid):
+            moved = _moved_since(s, nid)
+            if moved:
+                out.append(f"it names no file it read, and {', '.join(moved[:3])} changed after it was written")
         vu = str(n["body"].get("valid_until") or "").strip()
         if vu and s.now and s.now[:len(vu)] > vu:
             out.append(f"valid_until {vu} has passed")
         return out
+    if n["type"] == "decision":
+        # a decision is stale when everything it was based on is (a position taken on a backtest the vendor corrected)
+        basis = [e["dst"] for e in s.out.get(nid, []) if e["rel"] == "based_on" and not fallen(s, e["dst"])]
+        reasons = [stale(s, b) for b in basis]
+        if basis and all(reasons):
+            return list(dict.fromkeys(x for r in reasons for x in r))
+        return []
     if n["type"] == "claim":
         rs = [e["src"] for e in s.inn.get(nid, []) if e["rel"] == "supports" and s.nodes[e["src"]]["type"] == "result"
               and not fallen(s, e["src"])]
         rs += [e["dst"] for e in s.out.get(nid, []) if e["rel"] == "derived_from" and s.nodes[e["dst"]]["type"] == "result"
                and not fallen(s, e["dst"])]
+        rs += [e["dst"] for e in s.out.get(nid, []) if e["rel"] == "cites" and s.nodes[e["dst"]]["type"] == "source"
+               and lifecycle(s, e["dst"]) == "active" and not fallen(s, e["dst"])]
         rs = list(dict.fromkeys(rs))
         if not rs:
             return []
@@ -439,6 +540,15 @@ def affected_by(s: Snap, touched: set) -> set:
     invs = {x for x in stack if s.nodes[x]["type"] == "investigation"}
     if invs:
         stack += [i for i, n in s.nodes.items() if n["inv"] in invs]
+    # a changed file reaches the results that name no file through no edge (see stale): under a workflow, every such
+    # result in the file's investigation may have gone stale
+    moved = {s.nodes[x]["inv"] for x in stack if s.nodes[x]["type"] == "artifact"}
+    if moved:
+        for i, n in s.nodes.items():
+            if n["type"] == "result" and n["inv"] in moved and workflow_profile(s, i):
+                run = producing_run(s, i)
+                if not (run and any(e["rel"] == "uses" for e in s.out.get(run, []))):
+                    stack.append(i)
     while stack:
         y = stack.pop()
         if y in out:
@@ -480,7 +590,7 @@ def state(s: Snap, nid: str) -> dict:
         moved = basis_changed(s, nid)
         if moved:
             st["basis_changed"] = moved
-    if t in ("result", "claim"):
+    if t in ("result", "claim", "source", "decision"):
         old = stale(s, nid)
         if old:
             st["stale"] = old

{hypgraph-0.5.1 → hypgraph-0.5.3}/src/hypgraph/plan.py

@@ -260,9 +260,10 @@ def report(g: "Graph", inv: str) -> dict:
         st = D.state(s, c)
         claims.append({**_brief_min(s, c), "lifecycle": st["lifecycle"], "review": (st.get("review") or {}).get("state"),
                        "verdicts": verdicts(c), "v": s.nodes[c]["v"], "evidence": st.get("evidence"),
-                       "lines": st.get("independent_lines")})
+                       "lines": st.get("independent_lines"), "stale": list(st.get("stale") or [])})
     results = [{**_brief_min(s, r), "outcome": D.state(s, r).get("outcome"), "by": s.nodes[r]["created_by"],
-                "in_a_claim": r in cited_by_claim, "lifecycle": D.state(s, r)["lifecycle"]} for r in by_type["result"]]
+                "in_a_claim": r in cited_by_claim, "lifecycle": D.state(s, r)["lifecycle"],
+                "stale": list(D.state(s, r).get("stale") or [])} for r in by_type["result"]]
     hyps = [{**_brief_min(s, h), "lifecycle": D.state(s, h)["lifecycle"],
              "support": D.state(s, h).get("independent_lines"), "challenges": D.state(s, h).get("challenges")}
             for h in by_type["hypothesis"]]
@@ -277,6 +278,8 @@ def report(g: "Graph", inv: str) -> dict:
     open_items = {
         "claims_unreviewed": [c["code"] for c in live if c["review"] in (None, "unchecked", "needs_revalidation")],
         "claims_contested": [c["code"] for c in live if c["review"] == "contested"],
+        # a check made on evidence that has since gone stale (a file superseded, a page changed) is not a check now
+        "claims_stale": [c["code"] for c in live if c["stale"]],
         "results_in_no_claim": [r["code"] for r in results if not r["in_a_claim"] and r["lifecycle"] != "withdrawn"
                                 and r["by"] != g.policy.instrument],
         "experiments_not_preregistered": [x["code"] for x in exps if not x["preregistered"]],
@@ -295,7 +298,7 @@ def report(g: "Graph", inv: str) -> dict:
     prof = profiles.profile_of(s, inv)
     if prof and prof.workflow:
         stale = [{"code": s.nodes[i]["code"], "type": s.nodes[i]["type"], "why": D.state(s, i)["stale"]}
-                 for i in by_type["result"] + by_type["claim"] if D.state(s, i).get("stale")
+                 for i in by_type["result"] + by_type["claim"] + by_type["source"] if D.state(s, i).get("stale")
                  and D.state(s, i)["lifecycle"] != "withdrawn"]
         out["workflow"] = {"profile": prof.id, "report": prof.workflow.report, "method": prof.workflow.method,
                            "questions": workflow.stages(s, inv, s.now), "stale": stale}
@@ -310,11 +313,13 @@ def report_markdown(r: dict) -> str:
          "Interpretation goes below this section._", "", "### Claims", "",
          "| claim | standing | review | verdicts | statement |", "|---|---|---|---|---|"]
     for c in r["claims"]:
-        L.append(f"| {c['code']} v{c['v']} | {c['lifecycle']} | {c['review'] or '-'} | "
+        rv = (c['review'] or '-') + (" · STALE" if c.get("stale") else "")
+        L.append(f"| {c['code']} v{c['v']} | {c['lifecycle']} | {rv} | "
                  f"{'; '.join(c['verdicts']) or '-'} | {cut(c['title'])} |")
     L += ["", "### Results", "", "| result | outcome | by | carried by a claim | summary |", "|---|---|---|---|---|"]
     for x in r["results"]:
-        L.append(f"| {x['code']} | {x['outcome'] or '-'} | {x['by']} | {'yes' if x['in_a_claim'] else 'NO'} | "
+        oc = (x['outcome'] or '-') + (" · STALE" if x.get("stale") else "")
+        L.append(f"| {x['code']} | {oc} | {x['by']} | {'yes' if x['in_a_claim'] else 'NO'} | "
                  f"{cut(x['title'])} |")
     L += ["", "### Hypotheses", ""]
     L += [f"- {h['code']} ({h['lifecycle']}; support lines {h['support']}, challenges {h['challenges']}): "
@@ -329,12 +334,14 @@ def report_markdown(r: dict) -> str:
         for q in w["questions"]:
             nxt = "complete" if q["complete"] else cut(q["next"], 140)
             L.append(f"| {q['code']} | {q['stage']} ({q['index']}/{q['of']}) | {nxt} |")
-        L += ["", "Stale evidence (the run used an artifact since superseded or withdrawn, or valid_until passed): "
+        L += ["", "Stale evidence (a file it used was superseded or withdrawn, its page changed, or valid_until passed): "
               + ("; ".join(f"{x['code']} — {x['why'][0]}" for x in w["stale"]) if w["stale"] else "none")]
     o = r["open"]
     L += ["", "### Open items", "",
           f"- claims not yet reviewed: {', '.join(o['claims_unreviewed']) or 'none'}",
           f"- claims contested: {', '.join(o['claims_contested']) or 'none'}",
+          f"- claims on stale evidence (what they rest on has changed since; a check of them no longer counts): "
+          f"{', '.join(o.get('claims_stale') or []) or 'none'}",
           f"- results no claim carries (their conclusions are unreviewed): {', '.join(o['results_in_no_claim']) or 'none'}",
           f"- experiments not preregistered: {', '.join(o['experiments_not_preregistered']) or 'none'}"]
     sp = r["spend"]