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

{probability_flow-1.4.2 → probability_flow-1.4.3}/.gitignore

@@ -16,16 +16,19 @@ _previews/
 # kept ON DISK and out of the repo -- removal from disk is Alex's call.
 exam.py
 exam2.ipynb
-figures/
+# ROOT-ANCHORED ON PURPOSE. An unanchored `figures/` matches a directory of that
+# name at ANY depth, and it silently swallowed `docs/figures/`, which is
+# COMMITTED output the site embeds. The generator for those lives in
+# `illustrations/`.
+/figures/
 
 # Written by notebook/tutorial.ipynb when it runs, as the save-and-load
 # section requires an actual file on disk. An artifact of executing the
 # notebook, not an input to it.
 notebook/sidewalk.json
 
-# Staged into docs/ at site-build time by hooks/stage_notebooks.py. The one copy
-# that is not generated lives in notebook/, beside the builder that makes it.
-docs/tutorial.ipynb
+# Staged into docs/ at site-build time by hooks/stage_examples.py. The one copy
+# that is not generated lives in examples/, beside the script that writes it.
 docs/examples/
 
 # mkdocs output

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

@@ -1,5 +1,117 @@
 # Changelog
 
+## 1.4.3
+
+### Added
+
+- **Structural editing.** `graph.remove_edge(cause, effect)` and
+  `graph.remove_variable(variable)`, plus `cpd.set_weight(parent, bits)` for
+  changing what an edge carries. Until now the library could only grow a graph,
+  so every consumer who needed to drop a node edited the serialised form and
+  read it back.
+
+  Removal **asks the CPD to drop the parent** rather than rewriting its
+  serialised form, because only the family knows its own shape. A caller
+  patching the document has to know that `weights` is a dict and `gates` is a
+  list and that a logical CPD keeps its inputs under `constituents` with no
+  `parents` key at all. One measured consequence of getting that wrong: an
+  orphaned gate re-creates the edge it names on the way back in, so the file
+  said two parents, the graph had three, every posterior was unchanged, and
+  nothing reported a problem.
+
+  Ids are never renumbered or reused. A gate goes when either end of it does,
+  with a warning. A family that cannot lose a parent without inventing
+  something has its CPD cleared, which makes `check()` and every query fail
+  until a new one is written.
+
+- `IndependentEvidence.weights` is now read-only. Assigning into it changed
+  nothing and reported nothing, because `_log_w` is what every query reads.
+  Use `set_weight`.
+
+### Added
+
+- **The documentation site is published**, at
+  <http://probabilityflow.com/docs/>, one directory per release with a version
+  selector and a banner on any version that is not the newest. It replaces a
+  hand-written page that described a version of the library which no longer
+  existed. Until Netlify issues a certificate for the domain, that link is
+  http and not https.
+- **Figures.** The pages that describe a graph now draw one. `illustrations/build.py`
+  writes them from the library into `docs/figures/`, so a figure cannot depict a
+  graph the library would not produce, and three tests keep the embeds and the
+  files in step.
+- **An API reference**, at `docs/api/` and on the documentation site. Grouped by
+  what you are doing rather than by which module a name lives in, with a section
+  for the things you receive rather than construct, because ten exported names
+  are returned to you and never called by anybody.
+
+### Changed
+
+- **The API reference is five pages** rather than one, indented under one
+  section: graphs and CPDs, asking questions, saving and loading, drawing,
+  generating, and the reveal game.
+- **The reveal game has its own page**, and the formalism page no longer
+  mentions it. It is an application built on the library rather than part of
+  the formalism, and the benchmark's own vocabulary has been taken off the site
+  entirely.
+- **The formalism page says edges come in three kinds.** Gating used to be
+  described as "not a third kind" on the grounds that the schema writes it
+  `causal`. That is a fact about the schema. A gate is an edge with its own
+  rules, and the page now says so and draws one.
+- **The tutorial is on Colab** rather than rendered as a static page, so a
+  reader can run it. `mkdocs-jupyter` is no longer a documentation dependency.
+
+### Fixed
+
+- **A fully revealed CPD came back as a table, losing its structure.** Nothing is
+  hidden at a full reveal, so the restriction is the identity and flattening is
+  pure loss: it preserves every probability exactly while destroying the operator,
+  the constituent count and the per-input activations. On a real decorated graph
+  that turned three `logical` CPDs into tables with every posterior still correct.
+  A definitional node has no per-edge strength, so the operator and the count are
+  the whole content of a sentence about a constitutive edge, and a consumer that
+  lost them had to reach back into the source document for structure. `logical`
+  and the noisy families now stay in family when nothing is hidden.
+
+  A **partial** reveal still returns a table, and that is not an oversight: `and`
+  over three constituents with two shown and the third at `q = 0.5` is `0.5` on
+  the row where both hold, where an `and` over the two would be `1.0`. Tagging
+  that `logical` would misdescribe the numbers.
+
+## Unreleased
+
+### Fixed
+
+- **An evidence node's `name` is free text.** The reader used to refuse any name
+  that was not exactly `"{parent}:{label}"`, so a document naming its
+  virtual-evidence nodes after the observation was rejected outright. The parent
+  is carried structurally in `evidence_for`, which is what consumers use, and
+  nothing parses the suffix back out of the name, so the rule enforced a format
+  on the one field a reader reads in order to encode something the document
+  already states. `add_evidence` still generates the suffixed form: what the
+  library produces and what the reader accepts are separate questions. The
+  integrity checks are untouched, so `evidence_for` must still name a real
+  variable, an evidence node must still have a CPD, and it is still at most one
+  per variable and never a constitutive target.
+
+### Changed
+
+- **`reveal.induce` now preserves `metadata`, on nodes and on edges.** It used to
+  strip it. The guarantee that nothing in `metadata` reached a reader has been
+  given up deliberately, because decoration lives there: several wordings of one
+  edge at different levels of precision, with one promoted into `description`. A
+  strip forced a consumer to choose a wording before inducing, and carrying it across
+  lets them induce once and render the same subgraph more than one way.
+
+  **The boundary moves rather than disappearing.** A reader never saw the document
+  in the first place, only text produced from it, so what protects them is what a
+  verbaliser emits. That is a weaker promise in a more honest place.
+
+  Nothing inside `metadata` is validated, which is what makes it useful and what
+  makes it the wrong place for anything a reader must not see. No number changes:
+  an implicit prior is read off the source graph, so carrying it into the result
+  cannot move an answer, and this is asserted rather than assumed.
+
 ## 1.4.2 (2026-10-12)
 
 ### Added
@@ -17,7 +129,7 @@
 ### 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
+  and each variable were checked against a key set, while 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: probability-flow
-Version: 1.4.2
+Version: 1.4.3
 Summary: Discrete causal graphs and exact inference.
 Author-email: Alex Roman <dr.alexroman@gmail.com>
 License-Expression: MIT
@@ -459,10 +459,14 @@ keys of `weights` plus any gate source, and a gate source joins the CPD's input
 list automatically at **weight `0.0` bits**, which is what "contributes no evidence
 of its own, gating only" means.
 
-**You still have to draw the edge yourself.** `gate_source.causes(child)` is
-required, and omitting it is a `ValueError` naming the two sets. The automatic part
-is the CPD's input list, not the graph's edges, and the sentence above used to
-read as though it were both.
+**You do not have to draw the edge.** Declaring the gate is enough: naming the
+source in a `Gate` is a statement that it bears on this node, so the edge it
+implies is drawn for you. Drawing it by hand first also works and is not
+duplicated.
+
+The edge is there for the arithmetic rather than for the picture. A gate source
+carrying no weight of its own gets no arrow in a rendering at all. It gets a
+switch wired into the edge it modulates.
 
 **These are not `logical` with a leak.** A `logical` is deterministic over a
 predicate on a count, and these are probabilistic over per-input activations.

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

@@ -435,10 +435,14 @@ keys of `weights` plus any gate source, and a gate source joins the CPD's input
 list automatically at **weight `0.0` bits**, which is what "contributes no evidence
 of its own, gating only" means.
 
-**You still have to draw the edge yourself.** `gate_source.causes(child)` is
-required, and omitting it is a `ValueError` naming the two sets. The automatic part
-is the CPD's input list, not the graph's edges, and the sentence above used to
-read as though it were both.
+**You do not have to draw the edge.** Declaring the gate is enough: naming the
+source in a `Gate` is a statement that it bears on this node, so the edge it
+implies is drawn for you. Drawing it by hand first also works and is not
+duplicated.
+
+The edge is there for the arithmetic rather than for the picture. A gate source
+carrying no weight of its own gets no arrow in a rendering at all. It gets a
+switch wired into the edge it modulates.
 
 **These are not `logical` with a leak.** A `logical` is deterministic over a
 predicate on a count, and these are probabilistic over per-input activations.

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

@@ -26,7 +26,7 @@ graph: being "the hypothesis" is a fact about the question, not about the causal
 structure.
 """
 
-from . import eliminate, engines, junction, logical, noisy, reveal
+from . import eliminate, engines, generation, junction, logical, noisy, reveal
 from .cpd import CPD, CPT, Table
 from .edges import Causal, Constitutive, Edge
 from .evidence import Evidence
@@ -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.2"
+__version__ = "1.4.3"
 
 __all__ = [
     "__version__",
@@ -54,6 +54,7 @@ __all__ = [
     "Table",
     "logical",
     "noisy",
+    "generation",
     "eliminate",
     "junction",
     "engines",

{probability_flow-1.4.2 → probability_flow-1.4.3}/probability_flow/cpd.py

@@ -127,6 +127,51 @@ class CPD(ABC):
             "what it says; it has to be written again"
         )
 
+    #: THE MIRROR OF `extensible`, and the same test read backwards: whether a
+    #: parent can be DROPPED from this CPD without inventing anything. An
+    #: additive form just loses a term. A table cannot: its rows are indexed by
+    #: the full assignment, so dropping a parent means choosing which slice of
+    #: the table survives, and nothing in the table says which.
+    #:
+    #: Where there is no answer the author clearly meant, the CPD is cleared
+    #: with a warning rather than silently reinterpreted, exactly as on the way
+    #: in. The downstream guard is the same one: a variable with no CPD fails
+    #: `check()` and every query, loudly.
+    reducible = False
+
+    def reduction_note(self, dropped) -> "str | None":
+        """What to warn about after dropping `dropped`, or None."""
+        return None
+
+    def reduction_reason(self) -> str:
+        """Why this CPD cannot lose a parent, for the warning."""
+        return (f"it is indexed by all of "
+                f"({', '.join(short(p.name) for p in self.parents) or 'nothing'}) "
+                "and nothing in it says which slice should survive")
+
+    def reduced_to(self, parents) -> "CPD":
+        """This CPD over `parents`, which drops one from its current set."""
+        raise ValueError(
+            f"{type(self).__name__} cannot drop a parent without changing what "
+            "it says; it has to be written again"
+        )
+
+    def _in_family_over(self, parents, order):
+        """This CPD over `parents`, in its own family, or None if it cannot be.
+
+        `order[i]` is the index in `self.parents` of the parent now at position
+        `i`, derived by STABLE ID rather than by identity, because the caller's
+        parents may be a different graph's objects with the same names. That is
+        why `reorder` cannot be used here: it matches by identity and raises
+        across graphs.
+
+        None means there is no in-family form and the caller should fall back to
+        a table. The base returns None; a family that can respin itself says so
+        by overriding. `Table` does not need to, because a table restricted to
+        all of its parents is a table either way.
+        """
+        return None
+
     def reorder(self, parents) -> "CPD":
         """Return this CPD with its conditioning set written in `parents` order.
 
@@ -219,6 +264,21 @@ class CPD(ABC):
                     "count would silently restrict to the wrong states. See #22."
                 )
 
+        # NOTHING HIDDEN MEANS NOTHING TO AVERAGE, so the restriction is the
+        # IDENTITY and flattening here is pure loss. It preserves every
+        # probability exactly while destroying the structure, which is the
+        # failure the format document already names about the emitter: "nothing
+        # checking numbers would notice". The same principle binds this method,
+        # and nobody connected the two until a consumer needed the operator.
+        #
+        # A full reveal is not an edge case, it is the state a reveal game ENDS
+        # in, and a consumer that needs a node's operator to put it into English
+        # needs it most there. Verified identical to the original to 1e-15.
+        if not hidden:
+            kept = self._in_family_over(list(shown), at)
+            if kept is not None:
+                return kept.for_child(target)
+
         rows = {}
         for assignment in _assignments(list(shown)):
             total = [0.0] * len(target.states)
@@ -226,14 +286,14 @@ class CPD(ABC):
                 weight = 1.0
                 for i, index in zip(hidden, combo):
                     parent = self.parents[i]
-                    q = unrevealed_q[_stable_key(parent)]
-                    if len(parent.states) == 2:
-                        weight *= q if index == 1 else (1.0 - q)
-                    else:
-                        # The model prescribes q for a BINARY parent only; a
-                        # multi-state one is taken as uniform, which is a stand-in
-                        # and is recorded as an open gap in reveal/latex/main.tex.
-                        weight *= 1.0 / len(parent.states)
+                    # ONE PATH FOR EVERY ARITY. A multi-state parent used to be
+                    # taken as uniform here, which was a stand-in rather than a
+                    # derivation. Its implicit prior is now a distribution over
+                    # its states, exactly as a prior over a three-state variable
+                    # is three numbers, and the binary case is the two-entry
+                    # instance of the same thing.
+                    weight *= as_implicit_distribution(
+                        unrevealed_q[_stable_key(parent)], parent)[index]
                 if weight == 0.0:
                     continue
                 full = [0] * len(self.parents)
@@ -262,6 +322,70 @@ class CPD(ABC):
                      _keys_are_indices=True)
 
 
+def as_implicit_distribution(value, parent):
+    """An implicit prior as a DISTRIBUTION over `parent`'s states.
+
+    `value` may be either form, because both are useful and one is ambiguous:
+
+      a number          P(the parent is not in its FIRST state), which is what a
+                        binary `q` has always meant, so `0.3` gives `(0.7, 0.3)`.
+                        REFUSED for a multi-state parent, because there is no
+                        honest way to spread one number over three states.
+      a sequence        one entry per state, in `parent.states` order, summing to
+                        one. This is the general form and the only one a
+                        multi-state parent can use.
+
+    The vector is what a non-binary parent needs, exactly as a prior over a
+    three-state variable needs three numbers. Before it existed, a multi-state
+    unrevealed parent was taken as UNIFORM, which is a stand-in rather than a
+    derivation and was recorded as an open gap.
+
+    Validated here rather than where it is stored, because `metadata` is a
+    container this library does not inspect and this is the first thing that
+    looks at the value.
+    """
+    n = len(parent.states)
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        if n != 2:
+            raise ValueError(
+                f"{parent.name!r} has {n} states, so its implicit prior needs "
+                f"{n} numbers, one per state in {parent.states!r}, and a single "
+                f"number was given ({value!r}). One number means P(not the first "
+                "state), which says nothing about how the rest divides."
+            )
+        q = float(value)
+        if not 0.0 <= q <= 1.0:
+            raise ValueError(
+                f"{parent.name!r} has an implicit prior of {value!r}, which is "
+                "not a probability."
+            )
+        return (1.0 - q, q)
+
+    try:
+        dist = tuple(float(x) for x in value)
+    except (TypeError, ValueError):
+        raise ValueError(
+            f"{parent.name!r} has an implicit prior of {value!r}, which is "
+            "neither a number nor a sequence of them."
+        ) from None
+    if len(dist) != n:
+        raise ValueError(
+            f"{parent.name!r} has {n} states {parent.states!r} and its implicit "
+            f"prior gives {len(dist)} numbers. It needs one per state, in that "
+            "order, exactly as a prior does."
+        )
+    if any(x < 0.0 for x in dist):
+        raise ValueError(
+            f"{parent.name!r} has a negative entry in its implicit prior: {dist}"
+        )
+    if abs(sum(dist) - 1.0) > 1e-9:
+        raise ValueError(
+            f"{parent.name!r} has an implicit prior summing to {sum(dist)!r} "
+            "rather than 1. It is a distribution over the parent's states."
+        )
+    return dist
+
+
 def _stable_key(variable):
     """How a parent is matched ACROSS graphs: its stable id, falling back to
     object identity for a variable that is not in a graph yet."""

probability_flow-1.4.2/probability_flow/generate.py → probability_flow-1.4.3/probability_flow/generation.py

@@ -30,6 +30,7 @@ from .edges import Causal, Constitutive
 from .evidence import Evidence
 from .graph import CausalGraph
 from .independent import Gate, IndependentEvidence
+from .variable import Definition, Variable
 
 __all__ = ["StructureSpec", "GraphSpec", "generate", "generate_batch",
            "check_reveal_legal", "GenerationError"]
@@ -104,8 +105,9 @@ class GraphSpec:
 
     #: Probability that an UNDETERMINED node with at least two parents is
     #: definitional. Only the undetermined are rolled: see `_assign_types`.
-    #: (Alex has not settled this name.)
-    definitional_prob: float = 0.0
+    #: (Alex has not settled this name; he asked on 2026-10-13 that it not be
+    #: renamed before the Friday demo, so the churn does not land near it.)
+    definitional_prob: float = 0.25
     #: Definitional nodes get their own CPD parameters, not the ordinary ones.
     definitional_leak_range: tuple[float, float] = (0.0, 0.02)
 
@@ -662,7 +664,7 @@ def _generator_fingerprint():
     """
     from . import __version__
 
-    fingerprint = {"generator": "probability_flow.generate",
+    fingerprint = {"generator": "probability_flow.generation",
                    "generator_version": __version__}
     try:
         import subprocess
@@ -702,9 +704,14 @@ def generate(spec: GraphSpec | None = None, seed: int = 0) -> CausalGraph:
     # assembly: now, and only now, can a Variable be created with its type
     graph = CausalGraph(f"generated/{seed}")
     var: dict = {}
-    for name, tag in plan.items():
-        var[name] = (graph.add_definition(name) if name in definitional
-                     else graph.add_variable(name))
+    # ids are n-based by convention (Alex, 2026-10-13). The library would assign
+    # `v0, v1, ...` on insert, so the id has to be supplied BEFORE the variable
+    # joins the graph -- afterwards it is read-only, deliberately, since the
+    # document format references it.
+    for index, (name, tag) in enumerate(plan.items()):
+        node = (Definition(name, id=f"n{index}") if name in definitional
+                else Variable(name, id=f"n{index}"))
+        var[name] = graph.add(node)
     hypothesis = var[spec.hypothesis_name]
     for source, target in edges:
         kind = Constitutive if target in definitional else Causal
@@ -749,7 +756,11 @@ def generate(spec: GraphSpec | None = None, seed: int = 0) -> CausalGraph:
         if node is hypothesis or isinstance(node, Evidence):
             continue
         p_if, p_if_not = _evidence_pair(rng, spec)
-        observation = node.add_evidence("observation", p_if=p_if, p_if_not=p_if_not)
+        # `<claim id>-ve`, so one id convention runs through the whole document
+        # (Alex, 2026-10-13). The NAME is left as `add_evidence` builds it; only
+        # the id is in scope here.
+        observation = node.add_evidence("observation", p_if=p_if, p_if_not=p_if_not,
+                                        id=f"{node.id}-ve")
         # Virtual evidence DOES get a cluster tag, unlike implicit_prior: it is
         # revealed with the variable it is about, so it belongs to the same
         # cluster, and a consumer walking every variable should not meet a hole.
@@ -846,7 +857,7 @@ def check_reveal_legal(graph: CausalGraph) -> None:
     if leaked:
         raise GenerationError(
             f"the ground-truth world reached the document on {leaked}. It used to "
-            "live in node metadata and survive only because the reveal game strips "
+            "live in node metadata, and the reveal game no longer strips "
             "metadata -- one undocumented line in another repo. It is now simply "
             "not written, so this is a generator bug rather than a leak"
         )
@@ -885,14 +896,11 @@ def leaks_ground_truth(doc: dict) -> list[str]:
     more, so this returns empty for anything this module produces. It stays
     because the day somebody puts it back is the day this fires.
 
-    Two things in its old wording are no longer true and are worth correcting
-    rather than deleting. It said the world "lives in per-node metadata", which
-    stopped being so when the write was removed. And it said the strip that kept
-    it from the judge was "one undocumented line in another repo", which was
-    accurate while the revealed-subgraph builder lived in `eval`. That builder is
-    retired: `reveal.induce` strips metadata here, says why in its docstring, and
-    `test_induce_STRIPS_METADATA_because_it_is_where_ground_truth_lives` holds it
-    in place.
+    THE STRIP IT USED TO RELY ON IS GONE. `reveal.induce` carried metadata from
+    1.4.3 onward, so "it survives only because the reveal game strips metadata" is
+    no longer true and this check is the whole protection rather than the second
+    layer. That is the reason it stays: the write was removed, and this is what
+    fires if it returns.
     """
     return [v.get("name", v.get("id")) for v in doc.get("variables", [])
             if "ground_truth" in (v.get("metadata") or {})]

{probability_flow-1.4.2 → probability_flow-1.4.3}/probability_flow/graph.py

@@ -220,6 +220,139 @@ class CausalGraph:
             stacklevel=4,
         )
 
+    def remove_edge(self, cause: Variable, effect: Variable) -> None:
+        """Remove the edge `cause -> effect`, and the effect CPD's term for it.
+
+        THE CPD IS ASKED TO DROP THE PARENT, not rewritten from outside. Only
+        the family knows its own shape: an additive CPD loses a term and any
+        gate that touched either end, a conjunction loses a constituent, a noisy
+        family loses a factor, and a table cannot lose anything without somebody
+        choosing which slice survives, so it is cleared with a warning.
+
+        That division is the whole point. A caller editing the SERIALISED form
+        has to know that `weights` is a dict and `gates` is a list and that a
+        logical CPD keeps its inputs under `constituents` with no `parents` key
+        at all. Getting one of those wrong writes a document that still loads,
+        because the orphaned gate re-creates the edge it names, and the removal
+        then silently did not happen.
+        """
+        self._require(cause)
+        self._require(effect)
+        from .evidence import Evidence
+        if isinstance(effect, Evidence):
+            raise ValueError(
+                f"{short(effect.name)!r} is a virtual-evidence node and "
+                f"{short(cause.name)!r} is what it is evidence ABOUT, so this "
+                "edge is what makes it evidence at all. Remove the evidence "
+                f"node itself with remove_variable({short(effect.name)!r}), or "
+                f"remove {short(cause.name)!r} and it goes too."
+            )
+        if self._edges.get((id(cause), id(effect))) is None:
+            raise ValueError(
+                f"there is no edge {short(cause.name)!r} -> {short(effect.name)!r} "
+                "to remove. Edges are directed, so check the direction: "
+                f"{short(effect.name)!r} -> {short(cause.name)!r} "
+                + ("DOES exist." if self._edges.get((id(effect), id(cause)))
+                   else "does not either.")
+            )
+        self._drop_edge(cause, effect)
+
+    def _drop_edge(self, cause: Variable, effect: Variable) -> None:
+        """Remove an edge without the Evidence guard.
+
+        Module-internal, and split out for the same reason `_insert` is split
+        from `add`: `remove_variable` has to take an evidence node's own edge
+        with it, and the public guard exists to stop a CALLER doing that on its
+        own and leaving evidence about nothing behind.
+        """
+        del self._edges[(id(cause), id(effect))]
+        self._parent_list[id(effect)] = [
+            p for p in self._parent_list[id(effect)] if p is not cause]
+        self._child_list[id(cause)] = [
+            c for c in self._child_list[id(cause)] if c is not effect]
+        self._reconcile_cpd_dropped(effect, cause)
+
+    def remove_variable(self, variable: Variable) -> None:
+        """Remove a variable, its virtual evidence, and every edge touching either.
+
+        IDS ARE NEVER REUSED OR RENUMBERED. The ids in a document are the keys
+        every external reference uses, so a removal that renumbered would be
+        schema-breaking rather than merely surprising. Removing `n3` leaves
+        `n4` as `n4`, and a later `add_variable` takes the next id that has
+        never been used rather than the hole.
+
+        Virtual evidence goes with the variable it is about. It models the
+        uncertainty of OBSERVING that variable, so keeping it afterwards would
+        leave a node that is evidence about nothing.
+        """
+        self._require(variable)
+        if variable is self._hypothesis:
+            raise ValueError(
+                f"{short(variable.name)!r} is this graph's hypothesis, so "
+                "removing it would leave the graph with nothing to be about. "
+                "Set `graph.hypothesis` to another variable first if that is "
+                "what you mean."
+            )
+        from .evidence import Evidence
+        doomed = [variable]
+        if not isinstance(variable, Evidence) and variable.has_evidence:
+            doomed.append(variable.evidence)
+        for victim in doomed:
+            # Copy both lists first: removing an edge mutates them.
+            for parent in list(self._parent_list[id(victim)]):
+                self._drop_edge(parent, victim)
+            for child in list(self._child_list[id(victim)]):
+                self._drop_edge(victim, child)
+        for victim in doomed:
+            self._variables.remove(victim)
+            del self._by_name[victim.name]
+            del self._by_id[victim.id]
+            self._cpds.pop(id(victim), None)
+            self._parent_list.pop(id(victim), None)
+            self._child_list.pop(id(victim), None)
+            self._position.pop(id(victim), None)
+            victim._graph = None
+        # POSITIONS ARE AN INTERNAL ORDERING, NOT THE SCHEMA IDS. Parent lists
+        # are sorted by position so that the same graph always serialises one
+        # way, so the index has to stay dense after a removal. `variable.id` is
+        # untouched by this.
+        for i, remaining in enumerate(self._variables):
+            self._position[id(remaining)] = i
+
+    def _reconcile_cpd_dropped(self, effect: Variable, dropped: Variable) -> None:
+        """The effect just lost a parent. Reduce its CPD, or clear it.
+
+        The mirror of `_reconcile_cpd`, and deliberately the same shape: reduce
+        where the reduction is the only thing the author could have meant, clear
+        where it is not. Clearing is safe for the same reason it is on the way
+        in, which is that a variable with no CPD fails `check()` and every query
+        rather than answering with something nobody wrote.
+        """
+        cpd = self._cpds.get(id(effect))
+        if cpd is None:
+            return
+        parents = tuple(self._parent_list[id(effect)])
+        if cpd.reducible:
+            self._cpds[id(effect)] = cpd.reduced_to(parents)
+            note = cpd.reduction_note(dropped)
+            if note:
+                warnings.warn(
+                    f"{short(effect.name)!r} lost the parent "
+                    f"{short(dropped.name)!r}, and its {type(cpd).__name__} "
+                    f"{note}",
+                    stacklevel=4,
+                )
+            return
+        del self._cpds[id(effect)]
+        warnings.warn(
+            f"{short(effect.name)!r} lost the parent {short(dropped.name)!r}, "
+            f"and its {type(cpd).__name__} was CLEARED: "
+            f"{cpd.reduction_reason()}. Set a new CPD for {short(effect.name)!r} "
+            f"over ({', '.join(short(p.name) for p in parents) or 'nothing'}); "
+            "until you do, every query on this graph will fail.",
+            stacklevel=4,
+        )
+
     @staticmethod
     def _check_kind(edge: Edge, effect: Variable) -> None:
         """The constitutive invariant, enforced as each edge arrives.
@@ -303,6 +436,26 @@ class CausalGraph:
         - a ready-made `CPD` (a compact parameterised form, say).
         """
         self._require(variable)
+
+        # A GATE NAMES ITS SOURCE, so the edge it implies is drawn here rather
+        # than left to the author.
+        #
+        # THIS IS NOT A PARAMETERS CALL INVENTING STRUCTURE, which is the
+        # objection it looks like. `Gate(u, modulates=a)` states that u bears on
+        # this node; the edge is that statement's mechanical consequence, not a
+        # relationship nobody mentioned. Structure before parameters still holds
+        # for everything a CPD does NOT name.
+        #
+        # Declaring a gate and stopping used to raise, and the refusal told the
+        # author to draw an edge the renderer then HIDES: a gate that carries no
+        # weight of its own gets no arrow to the child, it gets a switch wired
+        # into the edge it modulates. So the author was being asked to write a
+        # line whose only visible effect was to stop an error.
+        for gate in getattr(cpd_or_rows, "gates", ()) or ():
+            if not any(p is gate.source
+                       for p in self._parent_list[id(variable)]):
+                self.add_edge(gate.source, variable)
+
         parents = tuple(self._parent_list[id(variable)])
         if isinstance(cpd_or_rows, CPT):
             cpd = cpd_or_rows.build(variable, parents)