hypgraph 0.7.7__tar.gz → 0.7.8__tar.gz

{hypgraph-0.7.7 → hypgraph-0.7.8}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.7.8 — 2026-10-29: pinned references between records
+
+- **A record can cite a node of another record and prove what it read.** A `source` takes four more fields,
+  `record` (the cited record's URL), `node`, `version` and `hash` (sha256 of that version's canonical body, the
+  same hash the cited record's chain holds), all four or none (`SHAPE_REFERENCE` otherwise). `Graph.pin(node,
+  record_url)` / `GET /api/graph/pin/{id}?record=` build them for one of this record's nodes, with the node's own
+  words in `citation` and `says`, so the citing record reads without the cited one. `Graph.references(inv)` /
+  `GET /api/graph/references` list the sources here that pin other records, with who cites them.
+  `hypgraph.verify_reference(fields, fetch=)` reads the cited record's node route (HTTP, or a host's own reader)
+  and reports whether the pinned version still hashes to the pin, whether it was revised since, and whether it
+  was withdrawn. The citing record never trusts the other's status; it trusts the hash it pinned. A record stays
+  one trust boundary; a host that holds many (a mesh) derives the network from these pins.
+
 ## 0.7.7 — 2026-10-29: `hypgraph serve` inside a container
 
 - **`hypgraph serve` bound to `0.0.0.0` answered 421 to everyone.** Its Host check knew only the bind address,

{hypgraph-0.7.7 → hypgraph-0.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hypgraph
-Version: 0.7.7
+Version: 0.7.8
 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.7.7 → hypgraph-0.7.8}/docs/spec.md

@@ -28,7 +28,7 @@ correction is a new row, never an edited one.
 | `run` | RUN | **kind**\*, job_id, name, state, code, inputs, outputs, args, config, seed, env, started, finished, exit_code, log_sha256, note | One execution: code, inputs and outputs hashed, seed, state. `kind=lab` only from an instrument. |
 | `result` | RS | **summary**\*, kind, outcome, values, expected, limitations, power, evidence_note, legacy | What a run (or an observation, or a citation) found: values, outcome, power. |
 | `artifact` | A | **sha256**\*, path, size, format | Exact bytes, by sha256 — data, code, a model, a figure. |
-| `source` | S | **citation**\*, doi, url, passage, retrieved, says | Outside literature or data: citation, DOI, the passage that says it. |
+| `source` | S | **citation**\*, doi, url, passage, retrieved, says, kind, reliability, record, node, version, hash | Outside literature or data: citation, DOI, the passage that says it. Or another record's node, pinned: `record` (its URL), `node`, `version` and `hash` (sha256 of that version's canonical body) — all four or none. |
 | `review` | RV | **verdict**\*, **method**\*, **notes**\*, official | A verdict on one version of a claim, result, run, experiment or hypothesis. |
 | `decision` | D | **choice**\*, alternatives, **reasons**\*, revisit_if, meeting | A choice made on the evidence; flagged when what it was based on changes. |
 | `task` | T | **kanban_id**\*, title | A unit of work in your tracker, linked to what it works on. |

{hypgraph-0.7.7 → hypgraph-0.7.8}/src/hypgraph/__init__.py

@@ -16,13 +16,14 @@ 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.7.7"
+__version__ = "0.7.8"
 
 from .bundle import verify_bundle  # noqa: E402
 from .graph import Author, Graph, GraphError, file_sha256  # noqa: E402
 from .policy import Policy  # noqa: E402
+from .references import verify_reference  # noqa: E402
 from .schema import FORMAT, describe  # noqa: E402
 from .store import verify_file  # noqa: E402
 
-__all__ = ["Graph", "GraphError", "Policy", "Author", "verify_bundle", "verify_file", "file_sha256", "describe",
+__all__ = ["Graph", "GraphError", "Policy", "Author", "verify_bundle", "verify_file", "file_sha256", "describe", "verify_reference",
            "FORMAT", "__version__"]

{hypgraph-0.7.7 → hypgraph-0.7.8}/src/hypgraph/graph.py

@@ -28,6 +28,7 @@ from typing import Any, Callable, Optional
 
 from . import profiles
 from . import derive as D
+from . import references as R
 from . import refusals, store
 from .checks import claim_issues, value_issues
 from .policy import Policy
@@ -158,6 +159,12 @@ def clean_body(ntype: str, body: dict, *, partial_ok: bool = False) -> dict:
             if len(canon(v)) > n:
                 raise _shape("SHAPE_TOO_LONG", f"{k} is too long", words=[k])
         out[k] = v
+    if ntype == "source":
+        try:
+            out = R.check_fields(out)
+        except ValueError as e:
+            raise _shape("SHAPE_REFERENCE", str(e), "pin another record's node with record, node, version and hash "
+                         "(its /api/graph/pin/<id>?record=<url> gives them)", ["record", "node", "version", "hash"])
     return out
 
 
@@ -1225,6 +1232,14 @@ class Graph:
             out["versions"] = list(s.versions.get(nid, []))
         return out
 
+    def pin(self, nid: str, record: str) -> dict:
+        """Source fields another record can cite this node by: its version and hash, pinned (references.pin)."""
+        return R.pin(self, nid, record)
+
+    def references(self, inv: str = "") -> list[dict]:
+        """The sources here that pin nodes of other records, with who cites them (references.references)."""
+        return R.references(self, inv)
+
     def resolve(self, ref: str, inv: str = "") -> str:
         """A node id from an id or a display code (CL3, H2, X4 …), within an investigation when given."""
         ref = str(ref or "").strip()

hypgraph-0.7.8/src/hypgraph/references.py

@@ -0,0 +1,173 @@
+"""Pinned references: one record citing a node of another record, so that records can form a network without
+sharing a chain.
+
+A record is one trust boundary: one hash chain, one policy, one board. Another record's claim can still be a line
+of support here — as a ``source`` node, which is what a cited outside work already is — provided the reference
+says *which version* it read and *what that version hashed to*. The fields on ``source``:
+
+    record    the served record's base URL (what its /api/graph hangs off), e.g. https://mesh/q/demo-a
+    node      the node id there
+    version   the version that was read
+    hash      sha256 of that version's canonical body — the same hash the record's own chain holds for it
+
+``pin`` builds those fields for one of this record's nodes; ``verify_reference`` fetches the cited record and checks
+them: the hash still matches (nothing was rewritten), whether the node has been revised since (the pinned version
+stands as read, but there is a newer one), and whether it has been withdrawn. A host that holds many records (a
+mesh) uses the same functions against its own copies and derives cross-record standing from them. This record never
+trusts another record's status; it trusts the hash it pinned."""
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Callable, Optional
+
+from . import store
+
+if TYPE_CHECKING:
+    from .graph import Graph
+
+_HEX64 = re.compile(r"^[0-9a-f]{64}$")
+_URL = re.compile(r"^https?://[^\s/?#]+[^\s]*$", re.I)
+Fetch = Callable[[str], dict]
+
+
+def body_hash(body: dict) -> str:
+    """The hash a record's chain holds for a version: sha256 over the canonical JSON of its body."""
+    return store.sha(store.canon(body))
+
+
+def normalize_record(url: str) -> str:
+    """A record URL without a trailing slash, fragment or query; refuses anything that is not http(s)."""
+    u = str(url or "").strip()
+    if not _URL.match(u):
+        raise ValueError(f"record must be the cited record's http(s) URL, not {u!r}")
+    p = urllib.parse.urlsplit(u)
+    return urllib.parse.urlunsplit((p.scheme.lower(), p.netloc, p.path.rstrip("/"), "", ""))
+
+
+def check_fields(body: dict) -> dict:
+    """Validate the reference part of a source body (after the generic field cleaning). All four fields or none;
+    version a positive integer; hash 64 hex characters; record an http(s) URL. Returns the body with the fields
+    normalised."""
+    keys = ("record", "node", "version", "hash")
+    present = [k for k in keys if body.get(k) not in (None, "", 0)]
+    if not present:
+        return body
+    missing = [k for k in keys if k not in present]
+    if missing:
+        raise ValueError("a reference to another record names all of record, node, version and hash; missing: "
+                         + ", ".join(missing))
+    out = dict(body)
+    out["record"] = normalize_record(body["record"])
+    out["node"] = str(body["node"]).strip()
+    v = body["version"]
+    try:
+        fv = float(v)
+    except (TypeError, ValueError):
+        raise ValueError(f"version must be a positive whole number, not {v!r}")
+    if not fv.is_integer() or fv < 1:
+        raise ValueError(f"version must be a positive whole number, not {v!r}")
+    out["version"] = int(fv)
+    h = str(body["hash"]).strip().lower()
+    if not _HEX64.match(h):
+        raise ValueError("hash must be the 64-hex sha256 of the cited version's canonical body")
+    out["hash"] = h
+    return out
+
+
+def is_reference(body: dict) -> bool:
+    return bool(body.get("record")) and bool(body.get("hash"))
+
+
+def pin(g: "Graph", nid: str, record: str, *, now: str = "") -> dict:
+    """Source fields that pin ``nid`` of ``g`` as it stands now, for another record to cite. ``record`` is the URL
+    this record is served at. The citation and ``says`` carry the node's own words, so the citing record reads
+    without the cited one."""
+    s = g.snapshot()
+    nid = g.resolve(nid)
+    n = s.nodes[nid]
+    rec = normalize_record(record)
+    brief = g.brief(s, nid)
+    title = brief["title"] or n["type"]
+    when = now or datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    return {"citation": f"{brief['code']} ({n['type']}) in {rec}, version {n['v']}: {title}"[:1000],
+            "url": f"{rec}/#node={nid}", "kind": "primary", "retrieved": when,
+            "says": str(title)[:1500],
+            "record": rec, "node": nid, "version": int(n["v"]), "hash": body_hash(n["body"])}
+
+
+def references(g: "Graph", inv: str = "") -> list[dict]:
+    """Every source in ``g`` that pins a node of another record, with who cites it here. What a host walks to build
+    the network between records."""
+    s = g.snapshot()
+    out = []
+    for nid, n in s.nodes.items():
+        if n["type"] != "source" or not is_reference(n["body"]) or (inv and n["inv"] != inv):
+            continue
+        b = n["body"]
+        out.append({"id": nid, "code": n["code"], "inv": n["inv"], "record": b["record"], "node": b["node"],
+                    "version": b["version"], "hash": b["hash"], "lifecycle": g.state(nid)["lifecycle"],
+                    "cited_by": sorted({e["src"] for e in s.inn.get(nid, []) if e["rel"] == "cites"})})
+    out.sort(key=lambda r: (r["record"], r["node"], r["id"]))
+    return out
+
+
+def _http_fetch(timeout: float) -> Fetch:
+    def fetch(url: str) -> dict:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.load(r)
+    return fetch
+
+
+def verify_reference(fields: dict, *, fetch: Optional[Fetch] = None, timeout: float = 10.0) -> dict:
+    """Check a pinned reference against the record it points at.
+
+    ``fetch(url) -> dict`` answers ``GET <record>/api/graph/node/<node>?history=1``; the default is HTTP. A host
+    that holds the cited record passes its own reader. Returns::
+
+        {ok, problem, record, node, version, current_version, revised, withdrawn, lifecycle}
+
+    ``ok`` means the pinned version exists there and its body hashes to the pinned hash: what this record read is
+    what that record holds. ``revised`` (a newer version exists) and ``withdrawn`` are reported beside it — the
+    pin still stands as read, but the citing record's host decides what that means for its standing."""
+    try:
+        f = check_fields({k: fields.get(k) for k in ("record", "node", "version", "hash")})
+    except ValueError as e:
+        return {"ok": False, "problem": str(e)}
+    if not is_reference(f):
+        return {"ok": False, "problem": "not a reference: no record and hash pinned"}
+    url = f"{f['record']}/api/graph/node/{urllib.parse.quote(f['node'], safe='')}?history=1"
+    out = {"ok": False, "record": f["record"], "node": f["node"], "version": f["version"], "url": url}
+    try:
+        doc = (fetch or _http_fetch(timeout))(url)
+    except urllib.error.HTTPError as e:
+        return {**out, "problem": f"the record answered {e.code} for {f['node']}"}
+    except Exception as e:  # unreachable, bad JSON, timeout: the reference is unverified, not wrong
+        return {**out, "problem": f"could not read the record: {type(e).__name__}"}
+    if not isinstance(doc, dict) or "versions" not in doc:
+        return {**out, "problem": "the record's answer carries no versions (is it a HypGraph node route with history=1?)"}
+    versions = {int(v.get("v", 0)): v for v in doc.get("versions") or [] if isinstance(v, dict)}
+    cur = max(versions) if versions else int(doc.get("v") or 0)
+    out |= {"current_version": cur, "revised": cur > f["version"], "withdrawn": bool(doc.get("withdrawn")),
+            "lifecycle": str((doc.get("state") or {}).get("lifecycle") or ("withdrawn" if doc.get("withdrawn") else ""))}
+    ver = versions.get(f["version"])
+    if ver is None:
+        return {**out, "problem": f"version {f['version']} does not exist there (it has {cur})"}
+    body = ver.get("body")
+    if isinstance(body, str):
+        try:
+            body = json.loads(body)
+        except json.JSONDecodeError:
+            return {**out, "problem": "the version's body is not JSON"}
+    got = body_hash(body) if isinstance(body, dict) else ""
+    if got != f["hash"]:
+        return {**out, "problem": f"version {f['version']} hashes to {got[:16]}…, not the pinned {f['hash'][:16]}…"}
+    return {**out, "ok": True}
+
+
+__all__ = ["pin", "references", "verify_reference", "check_fields", "is_reference", "body_hash", "normalize_record"]

{hypgraph-0.7.7 → hypgraph-0.7.8}/src/hypgraph/schema.py

@@ -65,7 +65,9 @@ TYPES: dict[str, dict] = {
     "source": {"prefix": "S", "fields": {
         "citation": _f("text", 1000, True), "doi": _f("str", 200), "url": _f("str", 500), "passage": _f("text", 3000),
         "retrieved": _f("str", 40), "says": _f("text", 1500), "kind": _f("enum:primary|secondary|tertiary"),
-        "reliability": _f("text", 1000)}},
+        "reliability": _f("text", 1000),
+        # a pinned reference to a node of another record (references.py): all four or none
+        "record": _f("str", 500), "node": _f("str", 80), "version": _f("num"), "hash": _f("str", 64)}},
     "review": {"prefix": "RV", "fields": {
         "verdict": _f("enum:" + "|".join(sorted(VERDICTS)), req=True), "method": _f("text", 1500, True),
         "notes": _f("text", 4000, True), "official": _f("bool")}},
@@ -179,7 +181,7 @@ ABOUT = {
     "run": "One execution: code, inputs and outputs hashed, seed, state. `kind=lab` only from an instrument.",
     "result": "What a run (or an observation, or a citation) found: values, outcome, power.",
     "artifact": "Exact bytes, by sha256 — data, code, a model, a figure.",
-    "source": "Outside literature or data: citation, DOI, the passage that says it.",
+    "source": "Outside literature or data: citation, DOI, the passage that says it — or another record's node, pinned by version and hash.",
     "review": "A verdict on one version of a claim, result, run, experiment or hypothesis.",
     "decision": "A choice made on the evidence; flagged when what it was based on changes.",
     "task": "A unit of work linked to what it works on — or a work order: objective, assignee, done-when "

{hypgraph-0.7.7 → hypgraph-0.7.8}/src/hypgraph/server.py

@@ -5,6 +5,8 @@
     GET  /api/graph/investigations          {investigations, stats}
     GET  /api/graph/subgraph?inv=&types=    nodes (with standing) and live edges
     GET  /api/graph/node/{id}?history=1     one node, its links, its versions
+    GET  /api/graph/pin/{id}?record=URL     source fields another record cites this node by (version + hash pinned)
+    GET  /api/graph/references?inv=         the sources here that pin nodes of other records
     GET  /api/graph/why/{id}                what it rests on        /impact/{id}  what rests on it
     GET  /api/graph/neighborhood/{id}?depth=
     GET  /api/graph/search?text=&type=&inv=&limit=
@@ -160,6 +162,15 @@ def dispatch(g: Graph, method: str, path: str, query: dict | None = None, body:
             return 200, g.subgraph(inv, types=types)
         if head == "node" and arg:
             return 200, g.get(arg, history=q.get("history") in ("1", "true"))
+        if head == "pin" and arg:
+            if not q.get("record"):
+                return 400, {"detail": "record=<the URL this record is served at> is required"}
+            try:
+                return 200, g.pin(arg, q["record"])
+            except ValueError as e:
+                return 400, {"detail": str(e)}
+        if head == "references":
+            return 200, {"references": g.references(inv)}
         if head == "why" and arg:
             return 200, g.why(arg)
         if head == "impact" and arg:

hypgraph-0.7.8/tests/test_references.py

@@ -0,0 +1,156 @@
+"""Pinned references between records: record B cites a node of record A as a source that names the version it read
+and that version's hash. The pin is built by A (``pin``), checked against A (``verify_reference``), and listed by B
+(``references``). A is read the way a host reads it: through the API's node route with history."""
+import json
+import threading
+import urllib.request
+
+import pytest
+
+from hypgraph import Graph, GraphError, Policy, verify_reference
+from hypgraph import derive as D
+from hypgraph.references import body_hash, check_fields, normalize_record
+from hypgraph.server import dispatch, make_server
+
+RECORD_A = "https://mesh.example.org/q/demo-a"
+
+
+@pytest.fixture
+def a():
+    """Record A: one checked claim with a bound measurement."""
+    g = Graph(policy=Policy(reviewers={"critic"}, instrument="lab"))
+    me = g.author("ada")
+    inv = me.investigation("Treatment effect", "Does the treatment group score higher?")["id"]
+    run = me.add("run", inv, kind="agent", name="scores", state="succeeded")["id"]
+    r = me.add("result", inv, kind="computed", outcome="positive", summary="The treatment group scored higher in 41 of 50 pairs.",
+               values={"higher": {"k": 41, "n": 50}}, links=[{"rel": "produced", "from": run}])["id"]
+    c = me.add("claim", inv, statement="The treatment group scores higher in 41 of 50 matched pairs.",
+               scope="The 50 matched pairs in the pilot data.",
+               measurements=[{"name": "higher", "result": r, "key": "higher", "k": 41, "n": 50}],
+               links=[{"rel": "supports", "from": r, "why": "the measurement the claim states"}])["id"]
+    return g, inv, c
+
+
+def reader_of(g):
+    """A fetch that reads ``g`` the way a host reads a served record: through the node route with history."""
+    def fetch(url):
+        assert url.startswith(RECORD_A + "/api/graph/"), url
+        path, _, query = url[len(RECORD_A + "/api/graph"):].partition("?")
+        q = {k: [v] for k, v in (kv.split("=", 1) for kv in query.split("&") if kv)}
+        status, obj = dispatch(g, "GET", path, query=q)
+        assert status == 200, (status, obj)
+        return json.loads(json.dumps(obj, default=str))
+    return fetch
+
+
+def test_pin_carries_version_hash_and_the_nodes_own_words(a):
+    g, inv, c = a
+    p = g.pin("CL1", RECORD_A + "/")                          # a display code resolves; the trailing slash goes
+    assert p["record"] == RECORD_A and p["node"] == c and p["version"] == 1
+    assert p["hash"] == body_hash(g.get(c)["body"]) and len(p["hash"]) == 64
+    assert "41 of 50" in p["says"] and p["citation"].startswith("CL1 (claim) in " + RECORD_A)
+    assert p["url"] == f"{RECORD_A}/#node={c}" and p["kind"] == "primary" and p["retrieved"]
+
+
+def test_b_cites_a_and_the_reference_is_a_line_of_support(a):
+    g_a, _, c = a
+    g_b = Graph()
+    bob = g_b.author("bob")
+    inv = bob.investigation("Follow-up", "Does the effect hold at scale?")["id"]
+    s = bob.add("source", inv, **g_a.pin(c, RECORD_A))
+    assert s["body"]["version"] == 1 and isinstance(s["body"]["version"], int)
+    cl = bob.add("claim", inv, statement="A pilot found the treatment group higher in 41 of 50 matched pairs.",
+                 scope="The pilot's 50 matched pairs, as recorded in demo-a.", links=[{"rel": "cites", "to": s["id"]}])
+    st = D.state(g_b.snapshot(), cl["id"])
+    assert st["independent_lines"] == 1 and st["evidence"] == "external"
+    refs = g_b.references()
+    assert len(refs) == 1 and refs[0]["record"] == RECORD_A and refs[0]["node"] == c and refs[0]["cited_by"] == [cl["id"]]
+    assert g_b.references("inv-nothing") == []
+
+
+def test_verify_against_the_cited_record(a):
+    g_a, _, c = a
+    fields = g_a.pin(c, RECORD_A)
+    v = verify_reference(fields, fetch=reader_of(g_a))
+    assert v["ok"] and v["current_version"] == 1 and not v["revised"] and not v["withdrawn"] and v["lifecycle"] == "active"
+
+    g_a.author("ada").revise(c, "the scope was too narrow", scope="The 50 matched pairs in the pilot data, both sites.")
+    v = verify_reference(fields, fetch=reader_of(g_a))
+    assert v["ok"] and v["revised"] and v["current_version"] == 2            # what was read still stands as read
+
+    g_a.author("ada").withdraw(c, "the pairs were matched after the scores were seen")
+    v = verify_reference(fields, fetch=reader_of(g_a))
+    assert v["ok"] and v["withdrawn"] and v["lifecycle"] == "withdrawn"
+
+
+def test_a_rewritten_body_or_a_wrong_pin_fails(a):
+    g_a, _, c = a
+    fields = g_a.pin(c, RECORD_A)
+    bad = {**fields, "hash": "0" * 64}
+    v = verify_reference(bad, fetch=reader_of(g_a))
+    assert not v["ok"] and "hashes to" in v["problem"]
+    v = verify_reference({**fields, "version": 7}, fetch=reader_of(g_a))
+    assert not v["ok"] and "version 7 does not exist" in v["problem"]
+    v = verify_reference({**fields, "node": "n-nowhere"}, fetch=reader_of(g_a))
+    assert not v["ok"] and "problem" in v
+
+    def down(url):
+        raise OSError("connection refused")
+    v = verify_reference(fields, fetch=down)
+    assert not v["ok"] and v["problem"].startswith("could not read the record")
+
+
+def test_the_schema_refuses_half_a_reference(a):
+    g_a, _, c = a
+    g_b = Graph()
+    bob = g_b.author("bob")
+    inv = bob.investigation("Follow-up", "Does the effect hold at scale?")["id"]
+    p = g_a.pin(c, RECORD_A)
+    with pytest.raises(GraphError) as e:
+        bob.add("source", inv, **{k: v for k, v in p.items() if k != "hash"})
+    assert "missing: hash" in str(e.value)
+    with pytest.raises(GraphError) as e:
+        bob.add("source", inv, **{**p, "hash": "nope"})
+    assert "64-hex" in str(e.value)
+    with pytest.raises(GraphError) as e:
+        bob.add("source", inv, **{**p, "version": 1.5})
+    assert "whole number" in str(e.value)
+    with pytest.raises(GraphError):
+        bob.add("source", inv, **{**p, "record": "ftp://mesh/q/a"})
+    plain = bob.add("source", inv, citation="A plain outside source, cited by its DOI.", doi="10.1000/xyz")
+    assert "record" not in plain["body"] and g_b.references() == []
+
+
+def test_check_fields_and_normalize_record():
+    assert normalize_record("HTTPS://Mesh.example.org/q/a/?x=1#node=n") == "https://Mesh.example.org/q/a"
+    assert check_fields({"citation": "x"}) == {"citation": "x"}
+    out = check_fields({"record": "https://m/q/a", "node": " n1 ", "version": 2.0, "hash": "A" * 64})
+    assert out["version"] == 2 and out["node"] == "n1" and out["hash"] == "a" * 64
+
+
+def test_the_routes_pin_and_list(a, tmp_path):
+    g_a, inv, c = a
+    srv = make_server(g_a, "127.0.0.1", 0)
+    threading.Thread(target=srv.serve_forever, daemon=True).start()
+    base = f"http://127.0.0.1:{srv.server_address[1]}"
+    try:
+        with urllib.request.urlopen(f"{base}/api/graph/pin/{c}?record={RECORD_A}") as r:
+            p = json.load(r)
+        assert p["hash"] == body_hash(g_a.get(c)["body"]) and p["version"] == 1
+        try:
+            urllib.request.urlopen(f"{base}/api/graph/pin/{c}")
+            assert False, "record= is required"
+        except urllib.error.HTTPError as e:
+            assert e.code == 400
+        g_b = Graph(str(tmp_path / "b.hypgraph"))
+        bob = g_b.author("bob")
+        inv_b = bob.investigation("Follow-up", "Does the effect hold at scale?")["id"]
+        bob.add("source", inv_b, **p)
+        status, obj = dispatch(g_b, "GET", "/references", query={"inv": [inv_b]})
+        assert status == 200 and [x["node"] for x in obj["references"]] == [c]
+        # verified over real HTTP, the way a mesh or another host does it
+        v = verify_reference({**p, "record": base})
+        assert v["ok"] and not v["revised"]
+    finally:
+        srv.shutdown()
+        g_b.close()