probability-flow 1.4.0__tar.gz → 1.4.2__tar.gz

{probability_flow-1.4.0 → probability_flow-1.4.2}/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 1.4.2 (2026-10-12)
+
+### Added
+
+- **`edges[].description`**, first-class, mirroring `variables[].description`. It
+  is content about the relation rather than about either end: why this parent
+  bears on this child, how strongly, in words. It crosses into the graph
+  `reveal.induce` builds, while an edge's `metadata` does not, and that split is
+  the reason it is a field rather than a key inside `metadata`: the reveal game
+  strips `metadata` as its ground-truth guard, so decoration kept there is
+  removed exactly when it is wanted.
+- `edges[].metadata`, the private container, completing the bargain the document
+  and variable levels already struck.
+
+### Fixed
+
+- **An unknown key on an edge was accepted and silently dropped.** The document
+  and each variable were checked against a key set; edges were checked for an
+  unknown `kind` and never for unknown keys, and the writer rebuilt each edge
+  from a three-key literal. So an extra field survived a read, vanished on the
+  next write, and raised nothing. A generator shipping worded edge strengths lost
+  every one of them with no way to tell. Edges are now checked like the other two
+  levels, and an undecorated edge still emits exactly three keys, so existing
+  documents are unchanged.
+
+- **The PyPI page's three sidebar links were dead.** `Homepage`, `Repository` and
+  `Issues` all pointed at the source repository, which is private, so every one
+  returned a 404 to anyone who found the package and clicked. That shipped with
+  0.5.0 and was live until it was noticed. They are removed rather than
+  redirected, because no link beats a dead link and there is no public issue
+  tracker to offer while the repository is private. The long description and the
+  author's email are the contact surface. A homepage goes back when there is a
+  documentation site to point it at.
+- **The README had no install instruction**, which is the first thing the page it
+  renders on is for. It also opened on three sentences about this project's own
+  branch layout, which says nothing to somebody who has just installed the
+  package and cannot see the repository. It now opens with what the library does,
+  how to install it, and a note that versions below 1.0 are a different library.
+- A refusal that names the missing edge when a gate source has no edge of its own.
+  Declaring a gate puts the source in the CPD's input list and does not draw its
+  edge, and the error used to state the two sets without saying which call closed
+  the gap.
+
+### Note
+
+Regenerating the shipped documents is part of a version bump, even a patch one.
+The emitter stamps the current version into every document it writes, so the two
+worked examples are rewritten whenever the version moves. Reading a shipped
+document and writing it back is a textual no-op, and that property is worth the
+churn, but it is churn.
+
 ## 1.4.0 (2026-10-12)
 
 The first release of the 1.x line. **PyPI currently serves 0.5.0**, which is the

{probability_flow-1.4.0 → probability_flow-1.4.2}/PKG-INFO

@@ -1,10 +1,7 @@
 Metadata-Version: 2.5
 Name: probability-flow
-Version: 1.4.0
+Version: 1.4.2
 Summary: Discrete causal graphs and exact inference.
-Project-URL: Homepage, https://github.com/scalable-oversight-benchmarks/probability-flow
-Project-URL: Repository, https://github.com/scalable-oversight-benchmarks/probability-flow
-Project-URL: Issues, https://github.com/scalable-oversight-benchmarks/probability-flow/issues
 Author-email: Alex Roman <dr.alexroman@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -27,14 +24,24 @@ Description-Content-Type: text/markdown
 
 # probability-flow
 
-Discrete **causal graphs** and exact inference.
+Discrete **causal graphs** and exact inference, in pure Python with no
+dependencies.
 
-This is the `v1` rewrite. It shares a repository with the 0.x line but no code:
-the ASPIC argumentation layer, the argument generator, the belief-propagation
-solvers and the metrics package are all gone from this branch. The 0.x tree is
-still on `main` if you want to refer back to it.
+```bash
+pip install probability-flow
+```
+
+You write an argument down as a graph of propositions. Each proposition says how
+it depends on its parents. The library answers what any of them is worth, given
+everything or given only part of it.
+
+Nothing here is approximate. Three engines, all exact, and you do not normally
+choose between them.
+
+**Versions below 1.0 on the index are a different library** and share no code with
+this one. If you installed `probability-flow` before 1.4.0, see `CHANGELOG.md`.
 
-## The milestone
+## Start here
 
 Define a causal graph, observe some variables, and ask for a posterior.
 

{probability_flow-1.4.0 → probability_flow-1.4.2}/README.md

@@ -1,13 +1,23 @@
 # probability-flow
 
-Discrete **causal graphs** and exact inference.
+Discrete **causal graphs** and exact inference, in pure Python with no
+dependencies.
 
-This is the `v1` rewrite. It shares a repository with the 0.x line but no code:
-the ASPIC argumentation layer, the argument generator, the belief-propagation
-solvers and the metrics package are all gone from this branch. The 0.x tree is
-still on `main` if you want to refer back to it.
+```bash
+pip install probability-flow
+```
+
+You write an argument down as a graph of propositions. Each proposition says how
+it depends on its parents. The library answers what any of them is worth, given
+everything or given only part of it.
+
+Nothing here is approximate. Three engines, all exact, and you do not normally
+choose between them.
+
+**Versions below 1.0 on the index are a different library** and share no code with
+this one. If you installed `probability-flow` before 1.4.0, see `CHANGELOG.md`.
 
-## The milestone
+## Start here
 
 Define a causal graph, observe some variables, and ask for a posterior.
 

{probability_flow-1.4.0 → probability_flow-1.4.2}/probability_flow/__init__.py

@@ -38,7 +38,7 @@ from .serialize import FORMAT, VERSION, from_json, to_json
 from .variable import BINARY, Definition, Variable
 from .viz import render, to_text
 
-__version__ = "1.4.0"
+__version__ = "1.4.2"
 
 __all__ = [
     "__version__",

{probability_flow-1.4.0 → probability_flow-1.4.2}/probability_flow/edges.py

@@ -48,16 +48,31 @@ from __future__ import annotations
 
 
 class Edge:
-    """A directed relation from `source` to `target`."""
+    """A directed relation from `source` to `target`.
+
+    `description` is decorator-written content about the RELATION rather than
+    about either end: why this parent bears on this child, how strongly, in
+    words. It mirrors `Variable.description` and is first-class for a reason that
+    is easy to get backwards. Decoration has to survive into the graph a reader
+    is shown, and the reveal game STRIPS `metadata` as its ground-truth guard,
+    because that is where an implicit prior and a generator's sampled world live.
+    So text put in `metadata` would be removed exactly when it is wanted, and
+    text put here is carried across.
+
+    `metadata` is the private container, ignored by this library and round-tripped
+    verbatim, the same bargain it strikes at the document and variable levels.
+    """
 
-    __slots__ = ("source", "target")
+    __slots__ = ("source", "target", "description", "metadata")
 
     #: Shown in errors and renderings; subclasses override.
     kind = "edge"
 
-    def __init__(self, source, target):
+    def __init__(self, source, target, description=None):
         self.source = source
         self.target = target
+        self.description = description
+        self.metadata = {}
 
     @property
     def endpoints(self):

{probability_flow-1.4.0 → probability_flow-1.4.2}/probability_flow/generate.py

@@ -516,12 +516,24 @@ def _definitional_cpd(var, rng, spec):
     over = list(var.parents)
     leak = rng.uniform(*spec.definitional_leak_range)
 
+    # Sorted by name BEFORE drawing, because `definition_cpds` is a public
+    # parameter that accepts a set -- and a set of CLASSES is not stably ordered:
+    # class hashes derive from id(), so iteration order changes between processes.
+    # Measured on {And, Or, AtLeast, Exactly, AtMost}: four runs of
+    # `generate(seed=11)` produced FOUR DIFFERENT DOCUMENTS. That would silently
+    # invalidate the provenance argument that lets the sampled world stay out of
+    # the document, since same-seed-plus-pinned-generator would stop reproducing
+    # it.
+    #
+    # Sorting always, not only for sets, so every input form with the same
+    # families draws identically -- order should not matter to a uniform choice.
+    # It leaves the default alone, since "And" already sorts before "Or".
     choices = spec.definition_cpds
+    families = sorted(choices, key=lambda f: f.__name__)
     if isinstance(choices, dict):
-        families = list(choices)
         family = rng.choices(families, weights=[choices[f] for f in families])[0]
     else:
-        family = rng.choice(list(choices))      # a bare sequence is uniform
+        family = rng.choice(families)           # a bare sequence is uniform
 
     if family in _COUNTED:
         # AtLeast / Exactly / AtMost take a threshold; the others do not.

{probability_flow-1.4.0 → probability_flow-1.4.2}/probability_flow/logical.py

@@ -501,13 +501,37 @@ def _bind(cpd, child, parents):
     actual = {id(p) for p in parents}
     if declared != actual:
         missing = [short(p.name) for p in parents if id(p) not in declared]
-        extra = [short(p.name) for p in cpd.parents if id(p) not in actual]
+        extra = [p for p in cpd.parents if id(p) not in actual]
+        # THE ONE-LINE FIX, NAMED. A refusal that states the two sets leaves the
+        # reader to work out which call closes the gap, and a blind author
+        # reaching for a gate hits this first: declaring `gates=[...]` puts the
+        # source in the CPD's input list and does NOT draw its edge, because a
+        # CPD is parameters and an edge is structure. So the message says the
+        # call rather than only the discrepancy.
+        gate_sources = {id(g.source) for g in getattr(cpd, "gates", ())}
+        fix = ""
+        if extra:
+            # NAMED, NOT SPELLED AS CODE. A node's name is a proposition with
+            # spaces in it, so `A supports H.causes(H)` looks pasteable and is
+            # not. Say which edge is missing and let the reader write the call
+            # with whatever variables they are holding.
+            lines = [f"    {short(p.name)!r} has to cause {short(child.name)!r}"
+                     for p in extra]
+            why = ("A gate source is an input to the CPD and still needs its own "
+                   "edge: declaring a gate sets the weight that edge takes when "
+                   "the gate fires, and drawing the edge stays explicit, because "
+                   "a CPD is parameters and an edge is structure."
+                   if any(id(p) in gate_sources for p in extra) else
+                   "An input the CPD names has to be an actual cause of the node.")
+            fix = ("\n" + why + " Draw the missing edge first, with "
+                   "`causes()` or `add_edge()`:\n" + "\n".join(lines))
         raise ValueError(
             f"the {type(cpd).__name__} for {short(child.name)!r} is over "
             f"[{', '.join(short(p.name) for p in cpd.parents)}] but its inputs "
             f"are [{', '.join(short(p.name) for p in parents)}]"
             + (f"; missing {missing}" if missing else "")
-            + (f"; not an input: {extra}" if extra else "")
+            + (f"; not an input: {[short(p.name) for p in extra]}" if extra else "")
             + ". Every input edge must appear, and only those."
+            + fix
         )
     return cpd.reorder(parents).for_child(child)

{probability_flow-1.4.0 → probability_flow-1.4.2}/probability_flow/reveal.py

@@ -138,7 +138,9 @@ def induce(graph, revealed):
     METADATA IS NOT COPIED, and that is a guard rather than an omission.
     `metadata` is where `q` lives and also where a generator records what it
     knows, so copying it would leak ground truth into the very artifact the judge
-    reasons over.
+    reasons over. An EDGE'S `description` IS copied, and the two facts are one
+    decision: decoration a reader is meant to see has to be first-class, because
+    anything kept in `metadata` is removed exactly when it is wanted.
 
     DEPTH ONE. An unrevealed parent contributes its `q` and nothing else -- no
     CPD, no parents of its own, no virtual evidence. Walking further up is the
@@ -193,7 +195,14 @@ def induce(graph, revealed):
     # claim a node that is not there.
     for e in graph.edges():
         if id(e.source) in revealed_ids and id(e.target) in revealed_ids:
-            out.add_edge(mirror[id(e.source)], mirror[id(e.target)], type(e))
+            drawn = out.add_edge(mirror[id(e.source)], mirror[id(e.target)], type(e))
+            # THE DESCRIPTION CROSSES AND THE METADATA DOES NOT, and that split is
+            # the whole reason an edge's description is first-class rather than a
+            # key inside `metadata`. The text is what a reader is MEANT to see;
+            # `metadata` is where an implicit prior and a generator's sampled
+            # world live, so it is stripped. Decoration kept in `metadata` would
+            # be removed exactly when it was wanted.
+            drawn.description = e.description
 
     # The CPDs, after the edges, because a CPD is validated against its node's
     # parents and they have to exist first.
@@ -217,7 +226,8 @@ def induce(graph, revealed):
         copy = Evidence(mirror[id(v)], ev.label, ev.name, states=ev.states,
                         id=ev.id, description=ev.description)
         out._insert(copy)
-        out.add_edge(mirror[id(v)], copy, type(graph.edge(v, ev)))
+        rider = out.add_edge(mirror[id(v)], copy, type(graph.edge(v, ev)))
+        rider.description = graph.edge(v, ev).description
         out._cpds[id(copy)] = graph._cpd(ev).partially_revealed(
             [mirror[id(v)]], unrevealed_q={}, child=copy)
         mirror[id(ev)] = copy

{probability_flow-1.4.0 → probability_flow-1.4.2}/probability_flow/serialize.py

@@ -28,7 +28,7 @@ import json
 from .variable import short
 
 FORMAT = "probability-flow/causal-graph"
-VERSION = "1.4.0"
+VERSION = "1.4.2"
 
 #: Every key a document may carry, at each level. An unknown key is REJECTED.
 #:
@@ -39,9 +39,17 @@ VERSION = "1.4.0"
 #: producer's output surfaces on the first read instead of silently dropping
 #: whatever it was meant to say.
 #:
-#: `metadata` is the single exception, at both levels: an explicit container
-#: whose contents this library never inspects. Everything else strict, one place
-#: to extend.
+#: `metadata` is the single exception, at ALL THREE levels: the document, a
+#: variable and an edge. An explicit container whose contents this library never
+#: inspects. Everything else strict, one place to extend.
+#:
+#: THERE WERE ONLY TWO LEVELS HERE UNTIL AN EDGE ATE A COLLABORATOR'S WORK. Edges
+#: were checked for an unknown KIND and never for unknown KEYS, and the writer
+#: rebuilt each one from a three-key literal, so an extra key was accepted on read
+#: and dropped on write with nothing raised. A generator shipping worded edge
+#: strengths lost every one of them silently. The comment above this one used to
+#: say "at both levels" and meant the document and a variable, which named the
+#: missing third level without noticing it.
 TOP_LEVEL_KEYS = frozenset({
     "format", "version", "name", "hypothesis", "produced_by", "metadata",
     "engine_config", "variables", "edges", "cpds",
@@ -50,6 +58,9 @@ VARIABLE_KEYS = frozenset({
     "id", "name", "states", "description", "observed", "definitional",
     "evidence_for", "label", "metadata",
 })
+EDGE_KEYS = frozenset({
+    "source", "target", "kind", "description", "metadata",
+})
 
 
 #: Engine settings this version knows how to validate. Unknown keys inside
@@ -133,6 +144,17 @@ def _validate_engine_config(config) -> None:
             )
 
 
+def _decorate(edge, spec) -> None:
+    """Carry an edge's decoration off its document spec.
+
+    One function for both routes, because there are two: an ordinary edge is
+    created here, and an edge into a virtual-evidence node was already created by
+    `add_evidence`. Those were decorated in two places until one of them was not.
+    """
+    edge.description = spec.get("description")
+    edge.metadata = _copy(spec.get("metadata", {}))
+
+
 def _reject_unknown(spec, known, where) -> None:
     unknown = sorted(set(spec) - known)
     if unknown:
@@ -349,7 +371,11 @@ def to_json(graph, *, indent: int = 2) -> str:
         "variables": variables,
         "edges": [
             {"source": node_ref(e.source), "target": node_ref(e.target),
-             "kind": e.kind}
+             "kind": e.kind,
+             # Omitted when empty, so an undecorated edge still emits the same
+             # three keys it always did and existing documents are unchanged.
+             **({"description": e.description} if e.description else {}),
+             **({"metadata": _copy(e.metadata)} if e.metadata else {})}
             for e in _canonical_edges(graph)
         ],
         "cpds": [
@@ -448,6 +474,10 @@ def from_json(text: str):
     # variables. Definition-ness is derived from the edges, so the edge list
     # has to be consulted before any node is created.
     edge_specs = doc.get("edges", [])
+    for i, spec in enumerate(edge_specs):
+        _reject_unknown(spec, EDGE_KEYS,
+                        f"edge {spec.get('source')!r} -> {spec.get('target')!r}"
+                        if isinstance(spec, dict) else f"edge at index {i}")
     definitional = {
         e["target"] for e in edge_specs if e.get("kind") == "constitutive"
     }
@@ -546,8 +576,14 @@ def from_json(text: str):
                     f"two edges both say {e['source']!r} -> {e['target']!r}"
                 )
             seen_into_evidence.add(tgt.id)
+            # THE EDGE ALREADY EXISTS: `add_evidence` drew it in the pass above,
+            # so this one is not created here and used to `continue` before any
+            # decoration was read. On the file this was first tested against,
+            # that lost 19 of 43 edge descriptions, one per evidence channel,
+            # and lost them silently because the other 24 came through.
+            _decorate(g.edge(src, tgt), e)
             continue
-        g.add_edge(src, tgt, kinds[kind])
+        _decorate(g.add_edge(src, tgt, kinds[kind]), e)
 
     # Restore the document's own variable order. Evidence nodes go through
     # add_evidence in a second pass, so they arrive last no matter where the

{probability_flow-1.4.0 → probability_flow-1.4.2}/probability_flow/viz.py

@@ -164,6 +164,16 @@ def _condition(cpd, assignment) -> str:
 INK        = "#1b1f24"
 CAUSAL     = "#46525f"
 CONSTIT    = "#44505c"   # see `constitutive`: the DOUBLE LINE carries it now
+#: Green is the one hue the drawing does NOT otherwise spend. The ramp runs
+#: red-grey-blue and the gate is purple, so green says "a different kind of
+#: edge" without colliding with anything that means a quantity. It was ruled
+#: out for WEIGHTS because green reads as "good" rather than "true"; a
+#: constitutive edge carries no valence to misread, so that objection does not
+#: reach here.
+CONSTIT_GREEN = "#1b7f4f"
+#: Round dots, deliberately not the gate's long dash: both say "this line is
+#: special", and they have to say different specials.
+CONSTIT_DOTS = (0, (0.1, 1.9))
 GATE       = "#6b3fa0"   # purple: the weight ramp took green->red
 TRUE_C     = "#3b4cc0"   # coolwarm_r at +1: blue is "true", with less
 FALSE_C    = "#b40426"   # valence attached to it than green had
@@ -303,7 +313,13 @@ class Style:
                                    # -- 0.68 on the generator notebook's graph --
                                    # and 37% of that figure was empty.
     fontsize: float = 9.0
-    constitutive: str = "double"   # "double" (=) | "triple" | "arrow" | "diamond" | "brace"
+    #: The SHAPE of a constitutive edge: how many strands and whether they are
+    #: dotted. "double" reads as "=", which is identity rather than influence.
+    constitutive: str = "double"   # double | triple | dotted | double-dotted
+                                   # | arrow | diamond | brace
+    #: Its HUE, as a separate channel so the two can be combined: "neutral"
+    #: (slate, the shape carries everything) or "green", or any colour name.
+    constitutive_colour: str = "neutral"
     gate_glyph: str = "switch"     # "switch" (pole and two throws) | "valve" | "tee" | "tap"
     switch_angle: float = 15.0     # degrees between the two throws
     switch_arm: float = 0.35       # pole to contact, in INCHES -- a fixed size
@@ -879,6 +895,20 @@ def _clip(p, q, half):
     return (p[0] + dx * t, p[1] + dy * t)
 
 
+#: shape -> (strand offsets, dotted). One table so the drawing and the legend
+#: cannot disagree about what a mode looks like, which they did once.
+_STRANDS = {"double": ((-1, 1), False),
+            "triple": ((-1, 0, 1), False),
+            "dotted": ((0,), True),
+            "double-dotted": ((-1, 1), True)}
+
+
+def _constit_colour(style):
+    """The hue for a constitutive edge, kept separate from its shape."""
+    return {"neutral": CONSTIT, "green": CONSTIT_GREEN}.get(
+        style.constitutive_colour, style.constitutive_colour)
+
+
 def _offset(path, d):
     """Shift a polyline sideways by `d` inches, along its own normal.
 
@@ -1480,7 +1510,8 @@ _ARGUMENTS = {
     "ramp_floor": "ramp_floor",         # 1.0 for the colormap untouched
     "colours": "bar_colors",
     "outcomes": "badge_outcome",
-    "constitutive": "constitutive",     # "double" | "triple" | "arrow" | ...
+    "constitutive": "constitutive",     # shape: see Style.constitutive
+    "constitutive_colour": "constitutive_colour",   # "neutral" | "green" | any
 }
 _VALUES = {("idle_badge", "weights"): "number"}
 
@@ -1691,20 +1722,23 @@ def render(graph, observations=None, *, styles=None, style=None, ax=None,
             segs.append((path[i], path[i + 1]))
         a, b = path[-2], path[-1]
         if kind == "constitutive":
-            col = GHOST if ghosted else CONSTIT
+            col = GHOST if ghosted else _constit_colour(style)
             if style.constitutive == "arrow":
                 _draw_path(ax, path, col, 1.25, al)
-            elif style.constitutive in ("double", "triple"):
-                # TWO FINE LINES, reading as "=" -- identity rather than
+            elif style.constitutive in _STRANDS:
+                # FINE PARALLEL LINES, reading as "=" -- identity rather than
                 # influence, which is what constitution is. Blue used to carry
-                # this and the weight ramp has taken blue, so the SHAPE carries
-                # it now and no hue is spent.
-                offs = ((-1, 1) if style.constitutive == "double" else (-1, 0, 1))
+                # this and the weight ramp has taken blue, so the shape carries
+                # it now; hue is a second channel on top rather than a
+                # replacement, because the two are independent questions.
+                offs, dots = _STRANDS[style.constitutive]
                 for s in offs:
                     strand = _offset(path, 0.030 * s)
                     ax.plot([p[0] for p in strand], [p[1] for p in strand],
-                            color=col, linewidth=0.85, alpha=al, zorder=1.5,
-                            solid_capstyle="round")
+                            color=col, linewidth=0.85 if len(offs) > 1 else 1.2,
+                            alpha=al, zorder=1.5, solid_capstyle="round",
+                            linestyle=CONSTIT_DOTS if dots else "solid",
+                            dash_capstyle="round")
                 ax.add_patch(FancyArrowPatch(path[-2], b, arrowstyle="-|>",
                                              mutation_scale=10, color=col,
                                              linewidth=0.9, alpha=al,
@@ -2106,17 +2140,20 @@ def _legend(ax, x, y, style, rows):
     def _constit(cx, cy):
         if style.constitutive == "arrow":
             ax.add_patch(FancyArrowPatch((cx, cy), (cx + 0.42, cy), arrowstyle="-|>",
-                                         mutation_scale=10, color=CONSTIT,
+                                         mutation_scale=10, color=_constit_colour(style),
                                          linewidth=1.25, shrinkA=0, shrinkB=0))
             return
-        if style.constitutive in ("double", "triple"):
-            offs = (-1, 1) if style.constitutive == "double" else (-1, 0, 1)
+        ccol = _constit_colour(style)
+        if style.constitutive in _STRANDS:
+            offs, dots = _STRANDS[style.constitutive]
             for s in offs:
                 ax.plot([cx, cx + 0.34], [cy + 0.030 * s, cy + 0.030 * s],
-                        color=CONSTIT, linewidth=0.85)
+                        color=ccol, linewidth=0.85 if len(offs) > 1 else 1.2,
+                        linestyle=CONSTIT_DOTS if dots else "solid",
+                        dash_capstyle="round")
             ax.add_patch(FancyArrowPatch((cx + 0.34, cy), (cx + 0.44, cy),
                                          arrowstyle="-|>", mutation_scale=10,
-                                         color=CONSTIT, linewidth=0.9,
+                                         color=ccol, linewidth=0.9,
                                          shrinkA=0, shrinkB=0))
             return
         ax.plot([cx, cx + 0.42], [cy, cy], color=CONSTIT, linewidth=1.15)

{probability_flow-1.4.0 → probability_flow-1.4.2}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "probability-flow"
-version = "1.4.0"
+version = "1.4.2"
 description = "Discrete causal graphs and exact inference."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -41,10 +41,19 @@ dependencies = []            # the core is pure Python
 [project.optional-dependencies]
 viz = ["matplotlib"]                     # optional: render(); to_text() needs nothing
 
-[project.urls]
-Homepage = "https://github.com/scalable-oversight-benchmarks/probability-flow"
-Repository = "https://github.com/scalable-oversight-benchmarks/probability-flow"
-Issues = "https://github.com/scalable-oversight-benchmarks/probability-flow/issues"
+# NO PROJECT URLS, DELIBERATELY, AND THIS IS NOT AN OVERSIGHT.
+#
+# PyPI renders these in the page sidebar. All three used to point at the source
+# repository, which is PRIVATE, so every one of them returned a genuine 404 to
+# anybody who found the package and clicked. That shipped with 0.5.0 and was live
+# until it was noticed. No link is better than a dead link, and there is no public
+# issue tracker to offer while the repository is private, so the long description
+# and `author_email` are the whole contact surface.
+#
+# Restore a Homepage here once the documentation site is published, and only
+# then. A link to a page that does not exist yet is the same defect again.
+# [project.urls]
+# Homepage = "https://probabilityflow.com/..."
 
 [tool.hatch.build.targets.wheel]
 packages = ["probability_flow"]
@@ -61,6 +70,16 @@ include = ["/probability_flow", "/README.md", "/CHANGELOG.md", "/LICENSE",
 [tool.pytest.ini_options]
 pythonpath = ["."]
 testpaths = ["tests"]
+# `release` is DESELECTED BY DEFAULT, and that is the point rather than a
+# convenience. A check that the tag matches HEAD is true only at the moment of
+# release: between tagging and uploading, every ordinary commit moves HEAD past
+# the tag, so running it in the normal suite would force a version bump for each
+# commit, and a version bump regenerates every shipped document. It would have
+# made the repository unworkable for exactly the window it was written to protect.
+addopts = "-m 'not release'"
+markers = [
+    "release: run at release time only. `uv run pytest -m release` is the gate.",
+]
 
 [tool.ruff]
 line-length = 100