hypgraph 0.5.2__tar.gz → 0.5.3__tar.gz

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

@@ -1,5 +1,16 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hypgraph
-Version: 0.5.2
+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/
@@ -152,7 +152,8 @@ record behaves exactly as before.
 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. An honest "it can't be answered" (a checked `inconclusive` claim), a declined thesis (`no_position`) and a
+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`

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

@@ -120,7 +120,8 @@ record behaves exactly as before.
 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. An honest "it can't be answered" (a checked `inconclusive` claim), a declined thesis (`no_position`) and a
+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`

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

{hypgraph-0.5.2 → 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."""
@@ -169,10 +177,68 @@ def excerpts(s: Snap, sid: str) -> list[str]:
             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 source is stale when the host re-fetched its page and the page as it is now no
+    ``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]
@@ -200,6 +266,11 @@ 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")
@@ -469,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:

hypgraph-0.5.3/tests/test_unnamed_inputs.py

@@ -0,0 +1,94 @@
+"""Under a workflow, a result whose run names no file it read (no ``uses``) can't show it read the new version of a
+file that changed after it — so it goes stale then, like a result that named the old file. Results written after the
+change, results that name their files, files of another question, run outputs, page excerpts and investigations with
+no workflow are untouched."""
+from hypgraph import Graph, Policy
+
+H = "harness"
+SHA_A, SHA_B, SHA_C = "a1" * 32, "b2" * 32, "c3" * 32
+
+
+def _g(profile="scientific@2"):
+    g = Graph(policy=Policy(reviewers={"critic"}, extra_reserved={H}))
+    fields = {"title": "Does A beat B on the items?", "objective": "Count each model's correct items on the file."}
+    if profile:
+        fields["profile"] = profile
+    inv = g.create(author=H, type="investigation", fields=fields)["id"]
+    q1 = g.create(author=H, type="question", inv=inv, code="Q1", fields={"text": "Is A right more often than B?"})["id"]
+    return g, inv, q1
+
+
+def _file(g, inv, sha, on=None, supersedes=None, kind=""):
+    fields = {"sha256": sha, "path": "items.csv"}
+    if kind:
+        fields["kind"] = kind
+    links = [{"rel": "part_of", "to": on}] if on else []
+    if supersedes:
+        links.append({"rel": "supersedes", "to": supersedes})
+    return g.create(author="vendor", type="artifact", inv=inv, fields=fields, links=links)["id"]
+
+
+def _result(g, inv, q, uses=None):
+    run = g.create(author="analyst", type="run", inv=inv, fields={"kind": "agent", "name": "count", "state": "succeeded"},
+                   links=[{"rel": "uses", "to": u, "data": {"role": "data"}} for u in uses or []])["id"]
+    rs = g.create(author="analyst", type="result", inv=inv, fields={"summary": "Counted the correct items per model.",
+                  "values": {"a_correct": {"value": 827}}, "outcome": "positive"},
+                  links=[{"rel": "produced", "from": run}])["id"]
+    c = g.create(author="analyst", type="claim", inv=inv, fields={"statement": "Model A is right more often than B.",
+                 "scope": "The items file as the vendor sent it."},
+                 links=[{"rel": "answers", "to": q}, {"rel": "derived_from", "to": rs}])["id"]
+    return rs, c
+
+
+def test_a_result_naming_no_file_goes_stale_when_a_file_changes_after_it():
+    g, inv, q = _g()
+    a1 = _file(g, inv, SHA_A)
+    rs, c = _result(g, inv, q)
+    assert not g.state(rs).get("stale")
+    a2 = _file(g, inv, SHA_B, supersedes=a1)
+    why = g.state(rs)["stale"]
+    assert why and "names no file it read" in why[0] and g.get(a1)["code"] in why[0]
+    assert g.state(c).get("stale")                                   # the claim rests on it, so it is stale too
+    # a result written after the change could have read the new file: fresh
+    rs2, c2 = _result(g, inv, q)
+    assert not g.state(rs2).get("stale") and not g.state(c2).get("stale")
+    # withdrawing a file counts the same as replacing it
+    g2, inv2, p = _g()
+    b1 = _file(g2, inv2, SHA_A)
+    rs3, _ = _result(g2, inv2, p)
+    g2.withdraw(author="vendor", node=b1, why="the vendor pulled the file")
+    assert g2.state(rs3).get("stale")
+    assert a2
+
+
+def test_a_result_that_names_its_files_follows_the_usual_rule():
+    g, inv, q = _g()
+    a1 = _file(g, inv, SHA_A)
+    other = g.create(author="vendor", type="artifact", inv=inv, fields={"sha256": SHA_C, "path": "labels.csv"})["id"]
+    rs, _ = _result(g, inv, q, uses=[a1])
+    _file(g, inv, SHA_B, supersedes=other)                       # a file it didn't use changed: still fresh
+    assert not g.state(rs).get("stale")
+    _file(g, inv, "d4" * 32, supersedes=a1)                      # the file it used changed: stale, the usual way
+    assert "is superseded" in g.state(rs)["stale"][0]
+
+
+def test_files_of_another_question_run_outputs_and_excerpts_do_not_count():
+    g, inv, q1 = _g()
+    q2 = g.create(author=H, type="question", inv=inv, code="Q2", fields={"text": "How many items is B right on?"})["id"]
+    f2 = _file(g, inv, SHA_A, on=q2)
+    out = g.create(author="analyst", type="artifact", inv=inv, fields={"sha256": SHA_C, "path": "plot.png"})["id"]
+    run = g.create(author="analyst", type="run", inv=inv, fields={"kind": "agent", "name": "plot", "state": "succeeded"},
+                   links=[{"rel": "produced", "to": out}])["id"]
+    rs, _ = _result(g, inv, q1)
+    _file(g, inv, SHA_B, on=q2, supersedes=f2)                   # Q2's file: not Q1's result's business
+    g.create(author="analyst", type="artifact", inv=inv, fields={"sha256": "e5" * 32, "path": "plot.png"},
+             links=[{"rel": "supersedes", "to": out}])          # a run's output replaced: not an input
+    assert run and not g.state(rs).get("stale")
+
+
+def test_no_workflow_no_rule():
+    g, inv, q = _g(profile="")
+    a1 = _file(g, inv, SHA_A)
+    rs, _ = _result(g, inv, q)
+    _file(g, inv, SHA_B, supersedes=a1)
+    assert not g.state(rs).get("stale")