bigraph-schema 1.4.2__tar.gz → 1.4.3__tar.gz

{bigraph_schema-1.4.2/bigraph_schema.egg-info → bigraph_schema-1.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigraph-schema
-Version: 1.4.2
+Version: 1.4.3
 Summary: A serializable type schema for compositional systems biology
 Author: Eran Agmon, Ryan Spangler
 Requires-Python: >=3.9

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

@@ -1,4 +1,5 @@
 from bigraph_schema.edge import Edge
+from bigraph_schema.contract import ProcessContract, resolve_contract
 from bigraph_schema.protocols import local_lookup_module
 
 from bigraph_schema.schema import BASE_TYPES, resolve_path, deep_merge, make_default

bigraph_schema-1.4.3/bigraph_schema/contract.py

@@ -0,0 +1,172 @@
+"""
+========
+Contract
+========
+
+A ``ProcessContract`` is a structured, mathematically-legible *superset* of the
+existing :attr:`bigraph_schema.edge.Edge.description` convention. ``description``
+is a flat markdown/LaTeX string that already states a process's governing
+equations; a ``ProcessContract`` adds explicit per-port / per-config / per-symbol
+semantics around that same math.
+
+The two are wired so the existing ``description`` is **reused, never rewritten**:
+when a contract omits ``summary`` / ``math`` / ``description`` those fields are
+derived by parsing the flat ``description`` string (see
+:meth:`ProcessContract.from_description` and
+:meth:`ProcessContract.merged_with_description`). Authored ``inputs`` /
+``outputs`` / ``config`` / ``symbols`` are always left untouched.
+
+Everything here is additive: a process that declares no contract resolves to a
+description-derived (or docstring-derived) one, or to ``None`` — it never raises
+and never changes runtime behavior.
+"""
+
+import inspect
+import copy
+import re
+from dataclasses import dataclass, field, asdict
+
+
+# Lines that read as governing equations rather than prose. Matched by any of
+# the canonical relation / operator markers, or by a probability-distribution
+# name (so a line like ``x ~ Multinomial(...)`` is captured as math).
+_DIST_NAMES = (
+    r"Multinomial|Binomial|Poisson|Normal|Gaussian|Bernoulli|Uniform|"
+    r"Exponential|Gamma|Beta|Dirichlet|Categorical|Geometric|Lognormal|"
+    r"LogNormal|Hypergeometric|NegativeBinomial|Weibull|Chi|StudentT"
+)
+_MATH_RE = re.compile(r"[=~≈←≥≤∑∏]|\b(?:" + _DIST_NAMES + r")\b")
+
+
+@dataclass
+class ProcessContract:
+    """A structured superset of ``Edge.description``.
+
+    All mutable fields use ``default_factory`` so instances never share state.
+    """
+
+    summary: str = ""
+    description: str = ""
+    inputs: dict = field(default_factory=dict)
+    outputs: dict = field(default_factory=dict)
+    config: dict = field(default_factory=dict)
+    math: list = field(default_factory=list)
+    symbols: dict = field(default_factory=dict)
+    assumptions: list = field(default_factory=list)
+    references: list = field(default_factory=list)
+
+    def to_dict(self):
+        """Return a JSON-safe plain-``dict`` representation."""
+        return asdict(self)
+
+    @classmethod
+    def from_description(cls, text):
+        """Parse a flat ``description`` string into a contract.
+
+        - the first non-empty line becomes ``summary``
+        - subsequent lines carrying an equation marker (see ``_MATH_RE``) become
+          ``math`` entries
+        - the remaining non-empty lines are joined into ``description``
+
+        Returns ``None`` for empty / ``None`` input.
+        """
+        if text is None:
+            return None
+        text = str(text)
+        if not text.strip():
+            return None
+
+        summary = ""
+        math = []
+        rest = []
+        seen_summary = False
+        for line in text.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                continue
+            if not seen_summary:
+                summary = stripped
+                seen_summary = True
+                continue
+            if _MATH_RE.search(stripped):
+                math.append(stripped)
+            else:
+                rest.append(stripped)
+
+        return cls(
+            summary=summary,
+            description="\n".join(rest),
+            math=math)
+
+    def merged_with_description(self, desc):
+        """Return a copy with only EMPTY ``summary`` / ``math`` / ``description``
+        filled from parsing ``desc``.
+
+        Authored ``inputs`` / ``outputs`` / ``config`` / ``symbols`` /
+        ``assumptions`` / ``references`` are preserved untouched.
+        """
+        merged = copy.deepcopy(self)
+        parsed = ProcessContract.from_description(desc)
+        if parsed is not None:
+            if not merged.summary:
+                merged.summary = parsed.summary
+            if not merged.math:
+                merged.math = list(parsed.math)
+            if not merged.description:
+                merged.description = parsed.description
+        return merged
+
+
+def _as_contract(declared):
+    """Coerce a declared ``contract`` attribute into a ``ProcessContract``.
+
+    Accepts a ``ProcessContract`` (returned as-is) or a plain ``dict`` (used as
+    kwargs). Any other type yields ``None`` so resolution falls through.
+    """
+    if isinstance(declared, ProcessContract):
+        return declared
+    if isinstance(declared, dict):
+        try:
+            return ProcessContract(**declared)
+        except TypeError:
+            return None
+    return None
+
+
+def resolve_contract(instance):
+    """Resolve the ``ProcessContract`` for a process/step ``instance``.
+
+    Resolution order (first that yields a contract wins):
+
+    1. a declared ``contract`` attribute (``ProcessContract`` or ``dict``),
+       merged with the object's ``description`` (authored rows preserved);
+    2. a description-derived contract from the object's ``description``;
+    3. a docstring-derived contract from the class docstring.
+
+    Never raises: odd input (``None``, a bare ``object()``, anything without a
+    class docstring of its own) returns ``None``.
+    """
+    if instance is None:
+        return None
+    try:
+        declared = getattr(instance, "contract", None)
+        desc = getattr(instance, "description", None)
+
+        contract = _as_contract(declared)
+        if contract is not None:
+            return contract.merged_with_description(desc or "")
+
+        if desc:
+            derived = ProcessContract.from_description(desc)
+            if derived is not None:
+                return derived
+
+        # Docstring fallback — but ignore a docstring merely inherited from
+        # ``object`` (so a bare ``object()`` resolves to None, while a class
+        # with its own docstring resolves).
+        doc = inspect.getdoc(type(instance))
+        if doc and doc != inspect.getdoc(object):
+            return ProcessContract.from_description(doc)
+        return None
+    except Exception:
+        return None

{bigraph_schema-1.4.2 → bigraph_schema-1.4.3}/bigraph_schema/core.py

@@ -104,8 +104,8 @@ def schema_keys(schema):
 def append_link_path(schema, link_path):
     if isinstance(schema, Node):
         if not hasattr(schema, '_link_path'):
-            schema.link_path = []
-        schema.link_path.append(link_path)
+            schema._link_path = []
+        schema._link_path.append(link_path)
     else:
         if not '_link_path' in schema:
             schema['_link_path'] = []
@@ -135,10 +135,16 @@ class Core:
             for key, values in importlib.metadata.packages_distributions().items()
             for value in values}
 
-        self.distributions_packages = {
-            value: key
-            for key, values in self.packages_distributions.items()
-            for value in values}
+        # dist -> LIST of its import packages. A single distribution can ship
+        # more than one import package (e.g. a real package plus a back-compat
+        # shim), so this must AGGREGATE, not last-wins-collapse to a single
+        # package — otherwise an empty shim can shadow the real package and its
+        # edges/types/visualizations are never discovered (bigraph-schema
+        # discover walks every package listed here).
+        self.distributions_packages = {}
+        for package, dists in self.packages_distributions.items():
+            for dist in dists:
+                self.distributions_packages.setdefault(dist, []).append(package)
 
         self.registry = {}
         self.link_registry = {}
@@ -188,6 +194,17 @@ class Core:
             self.registry[key] = found
         # Invalidate access cache since type registry changed
         self._access_cache.pop(key, None)
+        # Record the reverse class -> name mapping so serialize.render() can emit
+        # this type's NAME (not a Python class repr) when a port declares it as a
+        # type OBJECT (e.g. a process whose inputs() returns InPlaceDict()).
+        try:
+            from bigraph_schema.methods.serialize import register_type_name
+            from bigraph_schema.schema import Node
+            cls = found if isinstance(found, type) else type(found)
+            if isinstance(cls, type) and issubclass(cls, Node):
+                register_type_name(cls, key)
+        except Exception:
+            pass
 
     def register_types(self, types):
         """Bulk register multiple type keys into the operation registry."""
@@ -200,7 +217,7 @@ class Core:
             self.registry[key] = self.resolve(self.registry[key], data)
 
     def register_link(self, key, link):
-        if key in self.registry:
+        if key in self.link_registry:
             self.update_link(key, link)
         else:
             self.link_registry[key] = link

{bigraph_schema-1.4.2 → bigraph_schema-1.4.3}/bigraph_schema/edge.py

@@ -8,6 +8,8 @@ Base class for all edges in the bigraph schema.
 
 import inspect
 
+from bigraph_schema.contract import resolve_contract
+
 
 def default_wires(schema):
     """
@@ -37,6 +39,14 @@ class Edge:
     # to the class docstring when this is left empty.
     description = ''
 
+    # Structured superset of `description` (a `ProcessContract`, or a dict of
+    # its fields). Left `None` on the base class — resolves through normal MRO,
+    # so leaving it unset never changes runtime behavior. Subclasses may set it
+    # to advertise per-port / per-config / per-symbol semantics; when unset the
+    # contract is derived from `description` (or the docstring). Read it via the
+    # resolver method below or the module fn `contract.resolve_contract`.
+    contract = None
+
     def __init__(self, config=None, core=None):
         """
         Initialize the edge with a config and simulation core.
@@ -156,4 +166,19 @@ class Edge:
         """
         return self.description or inspect.getdoc(type(self)) or ''
 
+    def describe_contract(self):
+        """
+        Return this edge's resolved :class:`~bigraph_schema.contract.ProcessContract`.
+
+        A declared ``contract`` (class attribute) wins, merged with
+        ``description``; otherwise the contract is derived from ``description``
+        or the class docstring. Returns ``None`` when there is nothing to
+        surface. Never raises.
+
+        (Named ``describe_contract`` rather than ``contract`` because ``contract``
+        is the data slot subclasses populate — a same-named method would shadow
+        it and break declaration.)
+        """
+        return resolve_contract(self)
+
 

{bigraph_schema-1.4.2 → bigraph_schema-1.4.3}/bigraph_schema/methods/apply.py

@@ -1,6 +1,5 @@
 from plum import dispatch
 import numpy as np
-import os
 
 from bigraph_schema.methods.check import check
 from bigraph_schema.methods.default import default
@@ -351,35 +350,8 @@ def _handle_divide_sentinel(value_schema, state, update, path):
     # parity with the per-gen Nextflow path which generates both
     # daughters and only loads daughter_state_0.json forward.
     mother_state = state[mother]
-    # DEBUG: dump schema seen by divide
-    if os.environ.get('VECOLI_DEBUG_DIVIDE'):
-        import sys as _sys
-        print(f'[divide-debug] path={path} mother={mother!r}', file=_sys.stderr, flush=True)
-        print(f'[divide-debug] value_schema type={type(value_schema).__name__}', file=_sys.stderr, flush=True)
-        print(f'[divide-debug] value_schema repr={value_schema!r}', file=_sys.stderr, flush=True)
-        print(f'[divide-debug] mother_state keys={list(mother_state.keys()) if isinstance(mother_state, dict) else type(mother_state).__name__}', file=_sys.stderr, flush=True)
-        if isinstance(mother_state, dict) and 'bulk' in mother_state:
-            bulk_state = mother_state['bulk']
-            print(f'[divide-debug] mother_state[bulk] type={type(bulk_state).__name__}', file=_sys.stderr, flush=True)
-            sub_schema = getattr(value_schema, 'bulk', None)
-            print(f'[divide-debug] value_schema.bulk attr={type(sub_schema).__name__ if sub_schema is not None else "NONE"}', file=_sys.stderr, flush=True)
-            if sub_schema is None and isinstance(value_schema, dict):
-                sub_schema = value_schema.get('bulk')
-                print(f'[divide-debug] value_schema[bulk] dict-lookup={type(sub_schema).__name__ if sub_schema is not None else "NONE"}', file=_sys.stderr, flush=True)
     baselines = _divide_state(value_schema, mother_state,
                               context=mother_state, path=())
-    if os.environ.get('VECOLI_DEBUG_DIVIDE'):
-        import sys as _sys
-        if isinstance(baselines[0], dict) and 'bulk' in baselines[0]:
-            import numpy as np
-            ba = baselines[0]['bulk']
-            ma = mother_state['bulk']
-            try:
-                if hasattr(ba, 'dtype') and ba.dtype.names and 'count' in ba.dtype.names:
-                    print(f'[divide-debug] mother bulk count_sum={int(ma["count"].sum())}', file=_sys.stderr, flush=True)
-                    print(f'[divide-debug] daughter_a bulk count_sum={int(ba["count"].sum())} (expect ~half)', file=_sys.stderr, flush=True)
-            except Exception as e:
-                print(f'[divide-debug] err inspecting baseline: {e}', file=_sys.stderr, flush=True)
 
     # Remove the mother and install the requested daughters.
     del state[mother]

{bigraph_schema-1.4.2 → bigraph_schema-1.4.3}/bigraph_schema/methods/serialize.py

@@ -486,17 +486,42 @@ def render(schema: Node, defaults=False):
     return wrap_default(schema, subrender) if defaults else subrender
 
 
-# Reverse lookup: Node subclass -> registered type name
+# Reverse lookup: Node subclass -> registered type name. Seeded from BASE_TYPES,
+# and extended by the core as it registers further types (e.g. workspace types
+# like `inplace_dict`) via `register_type_name` — so render() can emit a name for
+# any registered type, not only the base set.
 _TYPE_NAME_CACHE = {}
+_BASE_SEEDED = False
+
+
+def _seed_base_types():
+    global _BASE_SEEDED
+    if _BASE_SEEDED:
+        return
+    from bigraph_schema.schema import BASE_TYPES
+    for name, type_cls in BASE_TYPES.items():
+        if isinstance(type_cls, type):
+            _TYPE_NAME_CACHE.setdefault(type_cls, name)
+    _BASE_SEEDED = True
+
+
+def register_type_name(cls, name):
+    """Record a ``Node`` subclass → its registered type name so ``render`` can
+    emit the name for types registered beyond BASE_TYPES. Prefer an explicit
+    registered name (e.g. ``inplace_dict``) over the class's own CamelCase name
+    (types are commonly auto-registered under ``__name__`` too, so first-wins
+    would otherwise keep ``InPlaceDict``)."""
+    if not isinstance(cls, type):
+        return
+    _seed_base_types()
+    existing = _TYPE_NAME_CACHE.get(cls)
+    if existing is None or (existing == cls.__name__ and name != cls.__name__):
+        _TYPE_NAME_CACHE[cls] = name
+
 
 def _node_type_name(cls):
     """Get the registered type name for a Node subclass, if any."""
-    if not _TYPE_NAME_CACHE:
-        # Build cache from BASE_TYPES
-        from bigraph_schema.schema import BASE_TYPES
-        for name, type_cls in BASE_TYPES.items():
-            if isinstance(type_cls, type):
-                _TYPE_NAME_CACHE[type_cls] = name
+    _seed_base_types()
     return _TYPE_NAME_CACHE.get(cls)
 
 @dispatch
@@ -726,6 +751,17 @@ def serialize(schema: Link, state):
     if state.get('_triggers'):
         encode['_triggers'] = state.get('_triggers')
 
+    # Additive: surface the resolved ProcessContract when the live instance
+    # supports one. Guarded so a process without contract support (or any odd
+    # state) never breaks Link serialization.
+    try:
+        from bigraph_schema.contract import resolve_contract
+        contract = resolve_contract(instance) if instance is not None else None
+        if contract is not None:
+            encode['_contract'] = contract.to_dict()
+    except Exception:
+        pass
+
     return encode
 
 

{bigraph_schema-1.4.2 → bigraph_schema-1.4.3}/bigraph_schema/package/discover.py

@@ -8,6 +8,19 @@ from bigraph_schema import Edge
 from bigraph_schema.schema import Node
 
 
+# Submodule / subpackage names that core discovery must never import.
+# Test scaffolding routinely pulls in heavy, test-only optional
+# dependencies (e.g. fastapi/starlette ``TestClient`` needs httpx) and
+# registers no Processes/Steps/Types worth discovering. Importing it can
+# raise arbitrary exceptions and abort the whole walk, so skip it up front.
+SKIP_SUBMODULES = frozenset({"tests", "testing"})
+
+
+def _should_skip_submodule(subname: str) -> bool:
+    """True for test scaffolding that must be excluded from the walk."""
+    return subname in SKIP_SUBMODULES or subname.startswith("test_")
+
+
 def find_edges(mapping, module_name=None):
     discovered = []
     for _, cls in mapping:
@@ -75,7 +88,23 @@ def recursive_dynamic_import(
         visited.add(adjusted)
 
     if isinstance(module, str):
-        adjusted = core.distributions_packages.get(module, module)
+        # A dist name can map to MORE THAN ONE import package (a real package
+        # plus a back-compat shim shipped in the same distribution). Walk EVERY
+        # package for the dist — otherwise an empty shim shadows the real
+        # package and its edges/types/visualizations are never discovered.
+        dist_packages = core.distributions_packages.get(module)
+        if dist_packages is not None:
+            for package in dist_packages:
+                if package in visited:
+                    continue
+                core, pkg_edges, pkg_types, visited = recursive_dynamic_import(
+                    core, package, visited=visited)
+                edges.extend(pkg_edges)
+                types.extend(pkg_types)
+            return core, edges, types, visited
+
+        # Not a known dist name -> treat as an import-package/module name.
+        adjusted = module
         if adjusted in visited:
             return core, edges, types, visited
         visited.add(adjusted)
@@ -83,6 +112,12 @@ def recursive_dynamic_import(
         try:
             module = importlib.import_module(adjusted)
 
+        except (KeyboardInterrupt, SystemExit):
+            # Never swallow interpreter-control signals: a Ctrl-C or an
+            # intentional sys.exit() raised at import time must propagate
+            # so discovery can't trap a deliberate interpreter exit.
+            raise
+
         except ImportError as e:
             # Catch both ModuleNotFoundError (the target itself is missing)
             # and ImportError (the target exists but a dep inside it failed
@@ -97,6 +132,20 @@ def recursive_dynamic_import(
                 print(f"module `{adjusted}` not found during dynamic import")
             return core, edges, types, visited
 
+        except Exception as e:
+            # A submodule can fail at import time with an exception that is
+            # NOT an ImportError — e.g. starlette raising RuntimeError when
+            # an optional test dependency (httpx) is absent, or an OSError
+            # from a module that touches the filesystem at import. One broken
+            # or optional submodule must never abort the entire package walk,
+            # so log a clear warning and skip it. KeyboardInterrupt/SystemExit
+            # are BaseException subclasses and are intentionally not caught
+            # here (handled above), so Ctrl-C still works.
+            print(
+                f"skipping `{adjusted}` "
+                f"({type(e).__name__} raised at import: {e})")
+            return core, edges, types, visited
+
     # Allow module to register types into core
     if hasattr(module, "register_types"):
         core = module.register_types(core)
@@ -108,6 +157,9 @@ def recursive_dynamic_import(
     # Recurse into submodules if this is a package
     if hasattr(module, "__path__"):
         for _, subname, _ in pkgutil.iter_modules(module.__path__):
+            # Never descend into test scaffolding (test_*, tests, testing).
+            if _should_skip_submodule(subname):
+                continue
             submod = f"{adjusted}.{subname}"
             core, sub_edges, sub_types, visited = recursive_dynamic_import(
                 core, submod, visited=visited)

{bigraph_schema-1.4.2 → bigraph_schema-1.4.3/bigraph_schema.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bigraph-schema
-Version: 1.4.2
+Version: 1.4.3
 Summary: A serializable type schema for compositional systems biology
 Author: Eran Agmon, Ryan Spangler
 Requires-Python: >=3.9

{bigraph_schema-1.4.2 → bigraph_schema-1.4.3}/bigraph_schema.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ setup.py
 bigraph_schema/__init__.py
 bigraph_schema/assembly.py
 bigraph_schema/calculi.py
+bigraph_schema/contract.py
 bigraph_schema/core.py
 bigraph_schema/edge.py
 bigraph_schema/json_codec.py
@@ -44,4 +45,6 @@ bigraph_schema/methods/transform.py
 bigraph_schema/methods/validate.py
 bigraph_schema/methods/walk.py
 bigraph_schema/package/__init__.py
-bigraph_schema/package/discover.py
+bigraph_schema/package/discover.py
+tests/test_multi_package_dist_discovery.py
+tests/test_process_contract.py

{bigraph_schema-1.4.2 → bigraph_schema-1.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bigraph-schema"
-version = "1.4.2"
+version = "1.4.3"
 description = "A serializable type schema for compositional systems biology"
 readme = "README.md"
 requires-python = ">=3.9"

bigraph_schema-1.4.3/tests/test_multi_package_dist_discovery.py

@@ -0,0 +1,39 @@
+"""A distribution can ship more than one import package (e.g. a real package
+plus a back-compat shim). Discovery must AGGREGATE all packages for a dist —
+not last-wins-collapse to a single one — else an empty shim can shadow the real
+package and its edges/types/visualizations are never discovered.
+
+Regression for the pbg-superpowers 0.16.0 case: the dist ships both
+``viva_superpowers`` (real) and ``pbg_superpowers`` (shim); last-wins could
+resolve the dist to the empty shim, so the real package's Demo* viz classes
+weren't discovered.
+"""
+import importlib.metadata
+
+from bigraph_schema import Core
+
+
+def test_multi_package_dist_aggregates_not_last_wins(monkeypatch):
+    # A dist ("multi-dist") that ships TWO import packages.
+    fake = {
+        "real_pkg": ["multi-dist"],
+        "shim_pkg": ["multi-dist"],
+        "bigraph_schema": ["bigraph-schema"],
+    }
+    monkeypatch.setattr(
+        importlib.metadata, "packages_distributions", lambda: fake)
+
+    core = Core({})
+
+    packages = core.distributions_packages["multi-dist"]
+    assert isinstance(packages, list)
+    # BOTH packages are present — not just the last-wins one.
+    assert set(packages) == {"real_pkg", "shim_pkg"}
+
+
+def test_distributions_packages_values_are_lists():
+    """Every dist maps to a list of its import packages."""
+    core = Core({})
+    assert all(isinstance(v, list) for v in core.distributions_packages.values())
+    # bigraph-schema is always present and maps to the bigraph_schema package.
+    assert "bigraph_schema" in core.distributions_packages.get("bigraph-schema", [])

bigraph_schema-1.4.3/tests/test_process_contract.py

@@ -0,0 +1,57 @@
+# tests/test_process_contract.py
+from bigraph_schema.contract import ProcessContract, resolve_contract
+
+DESC = """Distributes activated RNAPs across TUs by weighted multinomial sampling.
+
+    n_to_activate = round(f_active · n_total_RNAP) - n_active
+    p_i = max(0, basal_prob_i + sum_j delta_prob[i,j] · bound_TF_j)
+"""
+
+def test_mutable_defaults_isolated():
+    a, b = ProcessContract(summary="a"), ProcessContract(summary="b")
+    a.inputs["x"] = "y"
+    assert b.inputs == {}
+
+def test_from_description_splits_summary_and_math():
+    c = ProcessContract.from_description(DESC)
+    assert c.summary.startswith("Distributes activated RNAPs")
+    assert len(c.math) == 2 and c.math[0].startswith("n_to_activate =")
+
+def test_from_description_none():
+    assert ProcessContract.from_description("") is None
+    assert ProcessContract.from_description(None) is None
+
+def test_merged_preserves_authored_rows_fills_math():
+    authored = ProcessContract(inputs={"RNAs": "reads transcripts"})
+    merged = authored.merged_with_description(DESC)
+    assert merged.inputs == {"RNAs": "reads transcripts"}   # untouched
+    assert merged.math and merged.summary                    # filled from desc
+
+def test_merged_does_not_override_authored_math():
+    authored = ProcessContract(summary="mine", math=["x = 1"])
+    merged = authored.merged_with_description(DESC)
+    assert merged.summary == "mine" and merged.math == ["x = 1"]
+
+class _Declared:
+    contract = ProcessContract(inputs={"p": "reads p"})
+    description = DESC
+
+class _DescOnly:
+    description = DESC
+
+class _Bare:
+    """Plain docstring, no math."""
+
+def test_resolve_declared_merges_description():
+    c = resolve_contract(_Declared())
+    assert c.inputs == {"p": "reads p"}       # authored
+    assert c.math                              # merged from description
+
+def test_resolve_description_only():
+    c = resolve_contract(_DescOnly())
+    assert c.math and not c.inputs
+
+def test_resolve_docstring_fallback_then_none_safe():
+    assert resolve_contract(_Bare()).summary == "Plain docstring, no math."
+    assert resolve_contract(None) is None
+    assert resolve_contract(object()) is None