docs(topology): add runnable invocation examples (#1251)

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>

Author: yuelgrace1810-ops

src/jacobian/domains/topology/operations.py

@@ -505,6 +505,21 @@ def _integral_homology(
     "facets": [["a", "b"], ["b", "c"], ["a", "c"]],
 }
 
+_CANONICAL_CIRCLE = {
+    "vertices": ["a", "b", "c"],
+    "maximal_simplices": [["a", "b"], ["a", "c"], ["b", "c"]],
+    "faces_by_dimension": [
+        {"dimension": 0, "faces": [["a"], ["b"], ["c"]]},
+        {"dimension": 1, "faces": [["a", "b"], ["a", "c"], ["b", "c"]]},
+    ],
+    "dimension": 1,
+    "f_vector": [3, 3],
+    "closure_size": 6,
+    "complex_digest": (
+        "sha256:6f797991bac967e2a8e572707df487061655df0f094cbde0f52f82c5401fc043"
+    ),
+}
+
 type TopologyOperation = (
     InstalledOperation[
         SimplicialComplexRequest, SimplicialComplexCanonicalizationResult
@@ -566,6 +581,17 @@ def _integral_homology(
                 "boundary-matrix",
                 "exact",
             ),
+            invocation_examples=(
+                example(
+                    "circle_integer_chain_complex",
+                    "Construct the oriented integer boundary matrices of a circle.",
+                    {
+                        "complex": _CANONICAL_CIRCLE,
+                        "coefficient_ring": "INTEGER",
+                        "convention": "UNREDUCED",
+                    },
+                ),
+            ),
             version="4",
         )
     ),
@@ -588,6 +614,17 @@ def _integral_homology(
                 "prime-field",
                 "exact",
             ),
+            invocation_examples=(
+                example(
+                    "circle_homology_mod_two",
+                    "Compute H_0 and H_1 over F_2 for a triangle boundary.",
+                    {
+                        "complex": _CANONICAL_CIRCLE,
+                        "prime": 2,
+                        "convention": "UNREDUCED",
+                    },
+                ),
+            ),
             version="4",
         )
     ),

tests/domain/topology/test_topology_capabilities.py

@@ -22,6 +22,28 @@ def topology_services(tmp_path: Path) -> Iterator[DomainTestServices]:
         yield services
 
 
+def test_every_topology_operation_advertises_an_executable_example(
+    topology_services: DomainTestServices,
+) -> None:
+    bundle = build_topology_bundle()
+
+    for operation in bundle.capabilities:
+        spec = operation.spec
+        assert spec.invocation_examples, spec.operation_id
+        example = spec.invocation_examples[0]
+        result = topology_services.core.capabilities.invoke(
+            CapabilityRequest(
+                capability_id=spec.operation_id,
+                input=example.input,
+            )
+        )
+
+        assert result.execution.status is ExecutionStatus.COMPLETED, (
+            spec.operation_id,
+            result.diagnostics,
+        )
+
+
 _CIRCLE = {
     "vertices": ["a", "b", "c"],
     "facets": [["a", "b"], ["b", "c"], ["a", "c"]],