hypgraph 0.7.2__tar.gz → 0.7.4__tar.gz

{hypgraph-0.7.2 → hypgraph-0.7.4}/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
-
+ 
+## 0.7.4 — 2026-10-28: a bound result is a line of support, and a relation word is read as the relation it names
+
+- **A bound result is a line of support.** A claim's standing counted only `supports` edges into it, so a claim
+  that derives from a result and binds its numbers to it by `measurements` read "no live support", evidence
+  "unverified" — 73 of 113 active claims in the challenge records, each with its result right there. The results a
+  claim derives from and the results its measurements bind now count as lines of support (each once; shared runs
+  or data still merge into one line), so the evidence profile is the result's — lab-recorded when the instrument
+  filed it — and `unsupported` means what it says.
+- **A relation word the grammar doesn't have is read as the relation it names.** "generated", "created", "wrote"
+  → `produced`; "ran", "executed" → `executes`; "test" → `tests`; "answer" → `answers`; "used", "reads" → `uses`;
+  "contradicts", "refutes" → `challenges`; and so on (`schema.REL_SYNONYMS`, one reading each), noted on the
+  link like a translation. A hypothesis "derived from" a claim or result is `motivated_by` it; an experiment
+  "derived from" a hypothesis `tests` it. The link refusals left in the runs after 0.7.3: an unknown relation
+  `generated`, `derived_from hypothesis → claim`.
+
+## 0.7.3 — 2026-10-28: the refusal log sees everything — results, shape, links — and reads a link as the relation that joins
+
+- **A link is read as the relation that joins.** A relation that can't join its two types, where one relation says
+  the same thing between them, is applied as that relation with a note, like a link turned round: an experiment
+  that "supports" a hypothesis *tests* it; a run that "uses" an experiment *executes* it; a result, experiment or
+  decision that "answers" a question is *part of* it; a claim or result that "uses" or "rests on" an artifact is
+  *derived from* it; a decision that "supports" a claim is *based on* it (`schema.TRANSLATE`). An experiment may
+  `uses` the artifact it is designed on. A link refused on its pair is matched as fixed by the link that then
+  lands between the same nodes. Read off 23 `LINK_NOT_ALLOWED` refusals in nine runs: every hint named the
+  relation, 3 were taken; 19 of the 23 pairs now go through.
+- **Shape refusals are logged, coded, and say where the thing goes.** A sixteen-challenge sweep's run logs held
+  217 refusals for a field, an option or a link the schema doesn't have, against the 79 overclaims its refusal
+  logs held — the larger friction stream, and invisible to the log, the report and the replay. Now `clean_body`
+  and the link check raise a `GraphError` whose `problems` carry a code (`SHAPE_UNKNOWN_FIELD`,
+  `SHAPE_NOT_AN_OPTION`, `SHAPE_MISSING_FIELD`, `SHAPE_TOO_LONG`, `SHAPE_TOO_SHORT`, `SHAPE_WRONG_TYPE`,
+  `LINK_NOT_ALLOWED`, `LINK_UNKNOWN_RELATION`, `LINK_NO_NODE`) and a fix; `create`, `revise` and `link` log the
+  refusal with the body (`detail.type` `shape` / `link`) before raising it; `refusal_report` counts them apart under
+  `shape`; `replay_refusals` skips them. The three messages the sweep hit most now say where the thing goes: `code`
+  on a result belongs to the run (`code=[…]`, `produced` → the result); an experiment's `expected` goes on its
+  `tests` link (`data: {expected: …}`); and `outcome must be one of …` explains each option. An option written as
+  a leading word and a sentence ("negative — no outcome remains significant after correction", "H1 confirmed: the
+  setting loses its edge") is read as the word, the sentence kept as the evidence note; a leading "fail" stays
+  refused as ambiguous (negative if the code ran and showed the opposite, failed if it didn't run). Plural and
+  result-kind words on a claim's `kind` (`findings`, `computed`) map to `finding`. Read off the 17 outcome bodies
+  the new log captured in the first runs on the branch: 9 were whole sentences with no option word (refused, now
+  with the fix), 8 began with one.
+- **The refusal log treats results like claims.** A refused result is logged in full (its summary as the statement,
+  `RESULT_RESTATES` included), the author's next accepted result that says the same thing — by its words, or by
+  carrying at least half of the refused result's value keys again — fixes it (`fixes_refusals`, and the report's
+  *fixed* column, which showed 0 for every result code), and `replay_refusals` runs results through the value and
+  profile result checks as their author, claims through the profile checks too (an `EDGE_WITHOUT_TRIALS` refusal
+  used to replay as `passes`), and counts `RESULT_RESTATES` and typed-node refusals as skipped instead of replaying
+  a decision's choice as a claim. Found replaying 846 refusals from the challenge studies.
 ## 0.7.2 — 2026-10-28: the honest sentences the rules were refusing, and a nominal effect can't hide its correction
 
 - **Honest sentences the rules were refusing.** Read off every refusal logged in 96 records of the challenge studies

{hypgraph-0.7.2 → hypgraph-0.7.4}/PKG-INFO

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

@@ -41,7 +41,7 @@ correction is a new row, never an edited one.
 | `tests` | experiment | claim, hypothesis | an experiment tests a hypothesis or claim (data.expected: what it should show if true) |
 | `executes` | run | experiment | a run carries out an experiment |
 | `produced` | run | artifact, result | a run produced a result or artifact |
-| `uses` | run | artifact | a run used an artifact (data.role: data / code / model / config) |
+| `uses` | run, experiment | artifact | a run used an artifact (data.role: data / code / model / config); an experiment is designed on one |
 | `derived_from` | artifact, claim, result | artifact, result, run, source | computed or taken from |
 | `supports` | claim, result, source | claim, hypothesis | evidence for (why required) |
 | `challenges` | claim, result, source | claim, hypothesis | evidence against (why required) |
@@ -199,13 +199,26 @@ A refused claim never enters the record, so its trace lives in a separate append
 its own SHA-256 chain over `canon({at, kind, author, inv, node, op, statement, codes, detail, ref, prev})`. The
 record's own chain and `verify()` are unaffected.
 
-- `kind: refused`: the author, the investigation, the statement (≤ 1,500 characters), the sorted codes, and the
-  problems (code, message, fix) it was refused with. `op` is `create` or `revise`; `node` is set for a revision.
-- `kind: fixed`: a later claim or revision by the same author in the same investigation, accepted within 24 hours,
-  that says the same thing. "The same" means the same node for a revision; otherwise a Jaccard overlap ≥ 0.3 of the
-  statements' content words. `ref` is the refusal it fixes.
-
-A report aggregates per author (refused, fixed, open, codes) and per rule.
+- `kind: refused`: the author, the investigation, the statement (≤ 1,500 characters; a result's summary), the
+  sorted codes, and the problems (code, message, fix) it was refused with; `detail` holds the whole body, the
+  support it had and the node type (`claim`, `result`, or a typed node). `op` is `create` or `revise`; `node` is
+  set for a revision.
+- A refusal on *shape* — a field the type doesn't have (`SHAPE_UNKNOWN_FIELD`), a value outside an enum
+  (`SHAPE_NOT_AN_OPTION`), a missing, too long or too short field, a wrong type, or a link the relation grammar
+  refuses (`LINK_NOT_ALLOWED`, `LINK_UNKNOWN_RELATION`, `LINK_NO_NODE`) — is logged the same way with
+  `detail.type` `shape` or `link`. Its message carries the fix: where the field goes (`code` on a result belongs to
+  the run; an experiment's `expected` goes on its `tests` link) or what each option means. The report counts these
+  apart from overclaims and the replay skips them.
+- `kind: fixed`: a later claim, result or revision by the same author in the same investigation, accepted within
+  24 hours, that says the same thing. "The same" means the same node for a revision; otherwise a Jaccard overlap
+  ≥ 0.3 of the statements' content words, or, for a result, at least half of the refused result's value keys carried
+  again. `ref` is the refusal it fixes.
+
+A report aggregates per author (refused, fixed, open, codes) and per rule. A replay runs every logged refusal through
+the checker as it is now — claims through the claim and profile checks, results through the value and profile result
+checks as their author — and says for each whether it would be refused the same way, differently, or accepted;
+`RESULT_RESTATES` and typed-node refusals depend on the record's state at the time and are counted as skipped. A
+change to a rule is judged on that replay over the real corpus before it ships.
 
 ## 9. Checking a write-up against the record
 

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

{hypgraph-0.7.2 → hypgraph-0.7.4}/src/hypgraph/derive.py

@@ -349,7 +349,25 @@ def dependents(s: Snap, nid: str, limit: int = 500) -> list[tuple[str, str, int]
 
 
 def supporters(s: Snap, nid: str) -> list[dict]:
-    return [e for e in s.inn.get(nid, []) if e["rel"] == "supports"]
+    """What stands behind a node: every `supports` edge into it, and — for a claim — the results it is derived from
+    and the results its measurements bind (each once). A claim that binds its numbers to a result rests on that
+    result whether or not anyone also wrote `supports`; until 0.7.4 only the edge counted, and most honest claims
+    read "no live support" with their evidence "unverified"."""
+    out = [e for e in s.inn.get(nid, []) if e["rel"] == "supports"]
+    n = s.nodes.get(nid)
+    if n and n["type"] == "claim":
+        seen = {e["src"] for e in out}
+        for e in s.out.get(nid, []):
+            if e["rel"] == "derived_from" and e["dst"] in s.nodes and s.nodes[e["dst"]]["type"] == "result" \
+                    and e["dst"] not in seen:
+                seen.add(e["dst"])
+                out.append({"src": e["dst"], "rel": "derived_from", "dst": nid, "data": {}, "by": n["created_by"]})
+        for m in n["body"].get("measurements") or []:
+            rid = m.get("result") if isinstance(m, dict) else None
+            if rid and rid in s.nodes and s.nodes[rid]["type"] == "result" and rid not in seen:
+                seen.add(rid)
+                out.append({"src": rid, "rel": "measurement", "dst": nid, "data": {}, "by": n["created_by"]})
+    return out
 
 
 def at_risk(s: Snap, nid: str) -> list[str]:

{hypgraph-0.7.2 → hypgraph-0.7.4}/src/hypgraph/graph.py

@@ -31,7 +31,7 @@ from . import derive as D
 from . import refusals, store
 from .checks import claim_issues, value_issues
 from .policy import Policy
-from .schema import REPLICATION, RELS, SAME_TYPE, SYNONYMS, TYPES, VERDICTS
+from .schema import REL_SYNONYMS, REPLICATION, RELS, SAME_TYPE, SYNONYMS, TRANSLATE, TYPES, VERDICTS
 from .store import canon, now
 
 
@@ -47,49 +47,116 @@ class GraphError(ValueError):
 SpendFn = Callable[..., dict]
 
 
+def _shape(code: str, message: str, fix: str = "", words: list | None = None) -> GraphError:
+    """A shape refusal: the message, and the fix as its own field so a host can show it and the log can count it."""
+    return GraphError(message + (f" — {fix}" if fix else ""),
+                      [{"code": code, "message": message, "fix": fix, "words": list(words or [])}])
+
+
+# where a field an agent reaches for actually goes (read off 217 shape refusals in a sixteen-challenge sweep)
+_UNKNOWN_FIX = {
+    ("result", "code"): "the code belongs to the run: register the run with code=[…] (and uses → the script's "
+                        "artifact), then link it produced → this result",
+    ("result", "name"): "a result has a summary, not a name; the run has the name",
+    ("result", "uses"): "uses is the run's link to the artifacts it read, not a result field",
+    ("experiment", "data"): "expected goes on the link that tests the hypothesis: links=[{rel: 'tests', to: 'H1', "
+                            "data: {expected: 'what this experiment shows if H1 is true'}}]",
+    ("experiment", "data.expected"): "expected goes on the link that tests the hypothesis: links=[{rel: 'tests', "
+                                     "to: 'H1', data: {expected: '…'}}]",
+    ("claim", "fields"): "pass the claim's fields themselves (statement, scope, kind, measurements), not a fields "
+                         "object",
+}
+_OPTION_FIX = {
+    ("result", "outcome"): "positive: what the summary describes was seen; negative: it was not; inconclusive: "
+                           "neither; failed: the code didn't run; skipped: it wasn't run — one word; the sentence "
+                           "goes in the summary or evidence_note",
+    ("result", "kind"): "computed: from code you ran; observed: measured or read off data; cited: taken from a "
+                        "source",
+    ("claim", "kind"): "finding: what the evidence shows; exclusion: what it rules out; inconclusive; convention: "
+                       "a definition; lead: a hunch to test",
+}
+
+
+_AMBIGUOUS_LEAD = {"fail", "failed", "failure", "error", "errored"}      # the thing under test, or the code?
+_LEAD = re.compile(r"^\s*([A-Za-z][A-Za-z0-9_' -]{0,40}?)\s*(?:—|–|:|-{1,2})\s+(\S.*)$", re.S)
+
+
+def _leading_option(raw: str, syn: dict, opts: list) -> tuple[str, str]:
+    """An option written as a leading word and a sentence — "negative — nothing survives correction",
+    "H1 confirmed: the setting loses" — read as (option, the sentence); ('', '') when there is no such word, and
+    ('?', '') when the word is one whose meaning differs between the thing tested and the code ("fail")."""
+    m = _LEAD.match(raw or "")
+    if not m:
+        return "", ""
+    lead, rest = m.group(1).strip().lower(), m.group(2).strip()
+    tokens = [lead.replace(" ", "_").replace("-", "_")] + lead.replace("-", " ").split()
+    for t in tokens:
+        if t in _AMBIGUOUS_LEAD:
+            return "?", ""
+        v = syn.get(t, t)
+        if v in opts:
+            return v, rest
+    return "", ""
+
+
 def clean_body(ntype: str, body: dict, *, partial_ok: bool = False) -> dict:
-    """Validate and normalise a node's fields against its type (schema.TYPES)."""
+    """Validate and normalise a node's fields against its type (schema.TYPES). Every refusal carries a SHAPE_* code
+    and, where the sweep showed agents reaching for a field that lives elsewhere, says where it goes."""
     spec = TYPES[ntype]["fields"]
     if not isinstance(body, dict):
-        raise GraphError("fields must be an object")
+        raise _shape("SHAPE_NOT_AN_OBJECT", "fields must be an object")
     unknown = sorted(set(body) - set(spec))
     if unknown:
-        raise GraphError(f"{ntype} has no field(s) {unknown}; fields: {', '.join(spec)}")
+        fixes = [f for k in unknown if (f := _UNKNOWN_FIX.get((ntype, k)))]
+        raise _shape("SHAPE_UNKNOWN_FIELD", f"{ntype} has no field(s) {unknown}; fields: {', '.join(spec)}",
+                     "; ".join(fixes) if fixes else f"drop {', '.join(unknown)}", unknown)
     out = {}
     for k, (kind, n, req) in spec.items():
         v = body.get(k)
         if v in (None, "", [], {}):
             if req and not partial_ok:
-                raise GraphError(f"{ntype} needs {k}")
+                raise _shape("SHAPE_MISSING_FIELD", f"{ntype} needs {k}", words=[k])
             continue
         if kind in ("str", "text"):
             v = str(v).strip()
             if len(v) > n:
-                raise GraphError(f"{k} is longer than {n} characters")
+                raise _shape("SHAPE_TOO_LONG", f"{k} is longer than {n} characters", f"shorten {k} to {n} characters",
+                             [k])
             if req and len(v) < (3 if kind == "str" else 10):
-                raise GraphError(f"{k}: say it in a full sentence")
+                raise _shape("SHAPE_TOO_SHORT", f"{k}: say it in a full sentence", words=[k])
         elif kind.startswith("enum:"):
-            v = SYNONYMS.get((ntype, k), {}).get(str(v).strip().lower().replace(" ", "_").replace("-", "_"), str(v).strip())
-            if str(v) not in kind[5:].split("|"):
-                raise GraphError(f"{k} must be one of {kind[5:].replace('|', ', ')}")
+            opts, syn, raw = kind[5:].split("|"), SYNONYMS.get((ntype, k), {}), str(v).strip()
+            v = syn.get(raw.lower().replace(" ", "_").replace("-", "_"), raw)
+            if str(v) not in opts:
+                lead, rest = _leading_option(raw, syn, opts)
+                if lead and lead != "?":
+                    v = lead                      # the word is the option; the sentence stays as the note
+                    if rest and k == "outcome" and "evidence_note" in spec and not str(body.get("evidence_note") or "").strip():
+                        out["evidence_note"] = rest[:spec["evidence_note"][1]]
+                else:
+                    fix = _OPTION_FIX.get((ntype, k), "")
+                    if lead == "?":
+                        fix = ("a leading 'fail' is ambiguous: negative if the code ran and showed the opposite of what "
+                               "the summary tests, failed if the code didn't run" + (f"; {fix}" if fix else ""))
+                    raise _shape("SHAPE_NOT_AN_OPTION", f"{k} must be one of {kind[5:].replace('|', ', ')}", fix, [k])
             v = str(v)
         elif kind == "list":
             if isinstance(v, str):
                 v = [v]
             if not isinstance(v, list) or len(v) > n:
-                raise GraphError(f"{k} must be a list of at most {n} items")
+                raise _shape("SHAPE_WRONG_TYPE", f"{k} must be a list of at most {n} items", words=[k])
         elif kind == "dict":
             if not isinstance(v, dict) or len(canon(v)) > n:
-                raise GraphError(f"{k} must be an object (at most {n} characters)")
+                raise _shape("SHAPE_WRONG_TYPE", f"{k} must be an object (at most {n} characters)", words=[k])
         elif kind == "bool":
             v = bool(v)
         elif kind == "num":
             v = float(v)
             if not math.isfinite(v):
-                raise GraphError(f"{k} must be a finite number")
+                raise _shape("SHAPE_WRONG_TYPE", f"{k} must be a finite number", words=[k])
         elif kind == "any":
             if len(canon(v)) > n:
-                raise GraphError(f"{k} is too long")
+                raise _shape("SHAPE_TOO_LONG", f"{k} is too long", words=[k])
         out[k] = v
     return out
 
@@ -392,6 +459,32 @@ class Graph:
             k += 1
         return f"{prefix}{k}"
 
+    @staticmethod
+    def _translate(s: D.Snap, src: str, rel: str, dst: str) -> tuple[str, str]:
+        """A relation that can't join these two types, read as the one that says the same thing between them
+        (schema.TRANSLATE), or a word the grammar doesn't have read as the relation it names (schema.REL_SYNONYMS):
+        the relation to apply and a note, or the given relation and ''."""
+        given = rel
+        if rel not in RELS:
+            word = str(rel or "").strip().lower().replace(" ", "_").replace("-", "_")
+            rel = REL_SYNONYMS.get(word, rel)
+            if rel in RELS and src in s.nodes and dst in s.nodes:
+                st, dt = s.nodes[src]["type"], s.nodes[dst]["type"]
+                srcs, dsts = RELS[rel]
+                if (st in srcs and dt in dsts) or (dt in srcs and st in dsts):
+                    return rel, (f"{s.nodes[src].get('code') or src} -{given}-> {s.nodes[dst].get('code') or dst} "
+                                 f"read as {rel}")
+        if rel in RELS and src in s.nodes and dst in s.nodes:
+            st, dt = s.nodes[src]["type"], s.nodes[dst]["type"]
+            srcs, dsts = RELS[rel]
+            if not (st in srcs and dt in dsts) and not (dt in srcs and st in dsts):
+                new = TRANSLATE.get((rel, st, dt))
+                if new:
+                    return new, (f"{s.nodes[src].get('code') or src} -{given}-> {s.nodes[dst].get('code') or dst} "
+                                 f"read as {new} (a {st} {new.replace('_', ' ')} a {dt}; {rel} joins "
+                                 f"{', '.join(sorted(srcs))} to {', '.join(sorted(dsts))})")
+        return rel, ""
+
     @staticmethod
     def _orient(s: D.Snap, src: str, rel: str, dst: str) -> tuple[str, str, str, bool]:
         """A link given backwards — a claim that 'supports' its result — is turned round when only the reverse is
@@ -406,10 +499,10 @@ class Graph:
     @staticmethod
     def _check_link(s: D.Snap, src: str, rel: str, dst: str) -> None:
         if rel not in RELS:
-            raise GraphError(f"unknown relation {rel!r}; relations: {', '.join(RELS)}")
+            raise _shape("LINK_UNKNOWN_RELATION", f"unknown relation {rel!r}; relations: {', '.join(RELS)}", words=[rel])
         for x in (src, dst):
             if x not in s.nodes:
-                raise GraphError(f"no node {x}")
+                raise _shape("LINK_NO_NODE", f"no node {x}", "name a node the record holds (its code or id)", [x])
         st, dt = s.nodes[src]["type"], s.nodes[dst]["type"]
         srcs, dsts = RELS[rel]
         if st not in srcs or dt not in dsts:
@@ -417,8 +510,8 @@ class Graph:
             back = [r for r, (a, b) in RELS.items() if dt in a and st in b and r not in SAME_TYPE and r not in joins]
             hint = (f" — a {st} joins a {dt} with {', '.join(joins)}" if joins else "") + \
                    (f"; the other way round, a {dt} joins a {st} with {', '.join(back)}" if back else "")
-            raise GraphError(f"{rel} can't join {st} → {dt} (allowed: {', '.join(sorted(srcs))} → "
-                             f"{', '.join(sorted(dsts))}){hint}")
+            raise _shape("LINK_NOT_ALLOWED", f"{rel} can't join {st} → {dt} (allowed: {', '.join(sorted(srcs))} → "
+                         f"{', '.join(sorted(dsts))}){hint}", words=[rel, st, dt])
         if rel in SAME_TYPE and st != dt:
             raise GraphError(f"{rel} joins two nodes of the same type")
         if src == dst:
@@ -539,7 +632,13 @@ class Graph:
             raise GraphError(f"unknown type {type!r}; types: {', '.join(TYPES)}")
         if type == "review":
             raise GraphError("use review() to record a review")
-        body = clean_body(type, fields)
+        try:
+            body = clean_body(type, fields)
+        except GraphError as e:
+            refusals.record_refusal(self, author=author, op="create", inv=inv or "", node="",
+                                    body=fields if isinstance(fields, dict) else {},
+                                    problems=e.problems or [{"code": "SHAPE", "message": str(e)}], type="shape")
+            raise
         links = [l for l in (links or []) if isinstance(l, dict)]
         with self._lock:
             try:
@@ -578,7 +677,15 @@ class Graph:
                 staged = {"id": nid, "type": type, "code": "", "inv": inv, "created_at": at, "created_by": who,
                           "v": 1, "body": body}
                 s.nodes[nid] = staged                     # staged for link checks; dropped if the write fails
-                oriented = [self._orient(s, *self._link_spec(nid, l)) for l in links]
+                specs, translated = [], []
+                for l in links:
+                    a, rel, b = self._link_spec(nid, l)
+                    given, (rel, note) = rel, self._translate(s, a, rel, b)
+                    if note:
+                        translated.append(note)
+                        l["data"] = {**(l.get("data") or {}), "read_as": given}    # what the author wrote
+                    specs.append((a, rel, b))
+                oriented = [self._orient(s, *x) for x in specs]
                 pending = [(a, rel, b) for a, rel, b, _f in oriented]
                 flipped = [f"{s.nodes[a].get('code') or a} -{rel}-> {s.nodes[b].get('code') or b}"
                            for a, rel, b, f in oriented if f]
@@ -628,7 +735,7 @@ class Graph:
                     if rp:
                         found = [p.to_dict() for p in rp]
                         refusals.record_refusal(self, author=author, op="create", inv=inv, node="", body=body,
-                                                problems=found, support=[])
+                                                problems=found, support=[], type="result")
                         raise GraphError("result refused:\n- " + "\n- ".join(p.text() for p in rp), found)
                 if type in ("artifact", "source", "decision") and author not in P.curators:
                     np_ = profiles.node_issues(s, inv, type, body, pending)       # the workflow's typed shapes
@@ -637,7 +744,7 @@ class Graph:
                         refusals.record_refusal(self, author=author, op="create", inv=inv, node="",
                                                 body={"statement": str(body.get("choice") or body.get("citation")
                                                                        or body.get("path") or ""), "kind": type},
-                                                problems=found)
+                                                problems=found, type=type)
                         raise GraphError(f"{type} refused:\n- " + "\n- ".join(p.text() for p in np_), found)
                 if type == "result" and author not in P.reserved:
                     same = self._restated_by(s, body, inv, nid)
@@ -648,9 +755,8 @@ class Graph:
                         c = s.nodes[mine[0]]["code"] or mine[0]
                         found = [{"code": "RESULT_RESTATES", "message": f"this result repeats the numbers of your own "
                                   f"{c}", "fix": f"bind claims to {c} instead", "words": []}]
-                        refusals.record_refusal(self, author=author, op="create", inv=inv, node="",
-                                                body={"statement": body.get("summary", ""), "kind": "result"},
-                                                problems=found)
+                        refusals.record_refusal(self, author=author, op="create", inv=inv, node="", body=body,
+                                                problems=found, type="result")
                         raise GraphError(f"result refused: it repeats the numbers of your own {c} — bind claims to "
                                          f"{c} instead of writing it again; a genuine rerun is a run that replicates "
                                          f"{c}'s run [RESULT_RESTATES]", found)
@@ -667,12 +773,19 @@ class Graph:
                     for (a, rel, b), l in zip(pending, links):
                         self._insert_edge(con, s, a, rel, b, l.get("data") or {}, l.get("why") or "", author, at)
                 self._transaction(write)
+            except GraphError as e:
+                if e.problems and str(e.problems[0].get("code", "")).startswith("LINK_"):
+                    refusals.record_refusal(self, author=author, op="create", inv=inv or "", node="",
+                                            body=fields if isinstance(fields, dict) else {}, problems=e.problems,
+                                            type="link")
+                raise
             finally:
                 # the staged node lives in the cached snapshot: a failed write drops it; after a commit the next
                 # read loads the committed rows over it
                 self._after_write()
         out = self.get(nid)
         notes = [f"link turned round to the direction the relation allows: {x}" for x in flipped]
+        notes += [f"link read as the relation that joins: {x}" for x in translated]
         if auto_notes:
             notes.append("bound by the record: " + ", ".join(auto_notes))
             out["auto_bound"] = auto_notes
@@ -681,9 +794,10 @@ class Graph:
         if out["state"].get("restates"):
             out["restates"] = [self.get(r)["code"] for r in out["state"]["restates"]]
         self._with_orders(out, author, inv)
-        if type == "claim" and author not in P.curators:
-            fixed = refusals.match_fix(self, author=author, inv=inv, node=nid, statement=body.get("statement", ""),
-                                       op="create")
+        if type in refusals.REPLAYABLE and author not in P.curators:
+            fixed = refusals.match_fix(self, author=author, inv=inv, node=nid, op="create",
+                                       statement=str(body.get("statement") or body.get("summary") or ""),
+                                       values=body.get("values") if type == "result" else None)
             if fixed:
                 out["fixes_refusals"] = fixed
         return out
@@ -835,7 +949,13 @@ class Graph:
                 if not self._may_revise(s, author, n):
                     raise GraphError(f"only {n['created_by']} (its author), a reviewer or the {P.operator} revises "
                                      f"{n['code']}; challenge it, or propose a node that supersedes it")
-                body = clean_body(n["type"], {**n["body"], **(fields or {})})
+                try:
+                    body = clean_body(n["type"], {**n["body"], **(fields or {})})
+                except GraphError as e:
+                    refusals.record_refusal(self, author=author, op="revise", inv=n["inv"], node=node,
+                                            body=fields if isinstance(fields, dict) else {},
+                                            problems=e.problems or [{"code": "SHAPE", "message": str(e)}], type="shape")
+                    raise
                 extra: list[str] = []
                 auto_notes: list[str] = []
                 if n["type"] == "claim":
@@ -876,9 +996,10 @@ class Graph:
             out["notes"] = ["bound by the record: " + ", ".join(auto_notes)]
             out["auto_bound"] = auto_notes
         self._with_orders(out, author, out["inv"])
-        if out["type"] == "claim" and author not in P.curators:
-            fixed = refusals.match_fix(self, author=author, inv=out["inv"], node=node,
-                                       statement=out["body"].get("statement", ""), op="revise")
+        if out["type"] in refusals.REPLAYABLE and author not in P.curators:
+            fixed = refusals.match_fix(self, author=author, inv=out["inv"], node=node, op="revise",
+                                       statement=str(out["body"].get("statement") or out["body"].get("summary") or ""),
+                                       values=out["body"].get("values") if out["type"] == "result" else None)
             if fixed:
                 out["fixes_refusals"] = fixed
         return out
@@ -889,14 +1010,31 @@ class Graph:
         with self._lock:
             try:
                 s = self.snapshot()
+                given, (rel, translated) = rel, self._translate(s, src, rel, dst)
+                if translated:
+                    data = {**(data or {}), "read_as": given}                       # what the author wrote
                 src, rel, dst, flipped = self._orient(s, src, rel, dst)
                 if src in s.nodes:
                     self._fixed_guard(s, author, src)
                 eid = self._transaction(lambda con: self._insert_edge(con, s, src, rel, dst, data or {}, why, author,
                                                                       self.clock()))
+            except GraphError as e:
+                if e.problems and str(e.problems[0].get("code", "")).startswith("LINK_"):
+                    refusals.record_refusal(self, author=author, op="link", inv=(s.nodes.get(src) or {}).get("inv", ""),
+                                            node="", body={"statement": f"{src} {rel} {dst}"}, problems=e.problems,
+                                            type="link")
+                raise
             finally:
                 self._after_write()
-        return {"edge": eid, "src": src, "rel": rel, "dst": dst, "flipped": flipped}
+        out = {"edge": eid, "src": src, "rel": rel, "dst": dst, "flipped": flipped}
+        if translated:
+            out["notes"] = [f"link read as the relation that joins: {translated}"]
+        if author not in self.policy.curators:
+            fixed = refusals.match_fix(self, author=author, inv=(s.nodes.get(src) or {}).get("inv", ""), node="",
+                                       statement="", op="link", pair=(src, dst))
+            if fixed:
+                out["fixes_refusals"] = fixed
+        return out
 
     def retract(self, *, author: str, edge: int, why: str) -> dict:
         if len(str(why or "").strip()) < 10: