Add pseudocode for pgr_makeBiconnectedPlanar and pgr_makeMaximalPlanar wrappers

Community bonding deliverable: pseudocode for both C++ wrapper classes.

- pgr_makeBiconnectedPlanar: non-mutating visitor, EdgeIndexMap via
  std::map + associative_property_map, 4-parameter overload
- pgr_makeMaximalPlanar: mutating visitor (calls add_edge), additional
  VertexIndexMap requirement, 5-parameter overload

Key deviation from proposal Section 10.4: makeMaximalPlanar visitor
must be mutating to keep graph state consistent for Case B detection
in triangulation_visitor::end_face(). Confirmed by makeConnected.hpp
mutable graph pattern.

Error reporting uses throw std::string(...) matching all existing
pgRouting drivers.

Author: Mohit242-bit

pseudocode_makeBiconnectedPlanar.md

@@ -0,0 +1,243 @@
+# Pseudocode: pgr_makeBiconnectedPlanar C++ Wrapper
+
+**GSoC 2026 — Community Bonding Deliverable**
+**Author:** Mohit Rawat (@Mohit242-bit)
+
+---
+
+## Overview
+
+This document describes the pseudocode for the C++ wrapper class `Pgr_makeBiconnectedPlanar`
+that will call `boost::make_biconnected_planar` and return the set of edges needed to make
+a connected planar graph biconnected while preserving planarity.
+
+**Return type:** `II_t_rt` (two BIGINT fields: `start_vid`, `end_vid`)
+The `seq` column is generated by the C SRF wrapper as `call_cntr + 1`, not stored in the struct —
+same pattern as `pgr_makeConnected`.
+
+**Files modeled after:**
+- `include/components/makeConnected.hpp` — for the wrapper class structure and mutable graph pattern
+- `include/planar/boyerMyrvold.hpp` — for planarity testing and the planar module pattern
+- `src/planar/boyerMyrvold_driver.cpp` — for the driver error handling pattern
+- `src/components/makeConnected_driver.cpp` — for the `II_t_rt` return and SRF pattern
+
+---
+
+## Wrapper Class: `Pgr_makeBiconnectedPlanar<G>`
+
+```
+FILE: include/planar/makeBiconnectedPlanar.hpp
+
+CLASS Pgr_makeBiconnectedPlanar<G> : public Pgr_messages
+
+  TYPES (inherited from graph G):
+    V   = vertex_descriptor
+    E   = edge_descriptor
+    E_i = edge_iterator
+
+  PUBLIC:
+    FUNCTION makeBiconnectedPlanar(graph) -> vector<II_t_rt>:
+        RETURN generateMakeBiconnectedPlanar(graph)
+
+  PRIVATE:
+    FUNCTION generateMakeBiconnectedPlanar(graph) -> vector<II_t_rt>:
+
+        // ──────────────────────────────────────────────
+        // Step 1: Compute planar embedding via Boyer-Myrvold
+        // ──────────────────────────────────────────────
+        // NOTE: The existing boyerMyrvold.hpp only does a boolean planarity check.
+        //       We need the embedding as a side-effect, so we call
+        //       boyer_myrvold_planarity_test with the embedding parameter directly.
+        //       This is NEW code — not reusing boyerMyrvold.hpp.
+
+        embedding = vector<vector<edge_descriptor>>(num_vertices(graph.graph))
+
+        CHECK_FOR_INTERRUPTS()
+
+        is_planar = boyer_myrvold_planarity_test(
+            boyer_myrvold_params::graph = graph.graph,
+            boyer_myrvold_params::embedding = &embedding[0]
+        )
+
+        IF NOT is_planar:
+            throw std::string("Graph is not planar.")
+
+        // ──────────────────────────────────────────────
+        // Step 2: Build EdgeIndexMap
+        // ──────────────────────────────────────────────
+        // pgRouting's UndirectedGraph is:
+        //   adjacency_list<vecS, vecS, undirectedS, Basic_vertex, Basic_edge>
+        //
+        // Basic_edge has: source, target, id, cost
+        // It does NOT have property<edge_index_t, int> as an interior property.
+        //
+        // Therefore boost::get(edge_index, g) will NOT work.
+        // We must construct the edge index map explicitly using std::map.
+        //
+        // The standalone tests use property<edge_index_t, int> in the graph
+        // definition, which is why get(edge_index, g) works there.
+        // pgRouting's graph does not have this — confirmed from base_graph.hpp.
+
+        edge_index_map = std::map<edge_descriptor, int>
+        edge_count = 0
+        FOR (ei, ei_end) = edges(graph.graph); ei != ei_end; ++ei:
+            edge_index_map[*ei] = edge_count++
+
+        edge_index_pmap = boost::associative_property_map<EdgeIndexMap>(edge_index_map)
+
+        // ──────────────────────────────────────────────
+        // Step 3: Custom visitor (NON-MUTATING)
+        // ──────────────────────────────────────────────
+        // For makeBiconnectedPlanar, the visitor does NOT call add_edge().
+        // The algorithm identifies all needed edges in a single pass without
+        // re-reading adjacency, so non-mutating is correct here.
+        //
+        // This is DIFFERENT from makeMaximalPlanar which MUST be mutating.
+
+        STRUCT pgr_collect_edges_visitor:
+            result: vector<pair<V, V>>&
+
+            FUNCTION visit_vertex_pair(u, v, g):
+                result.push_back({u, v})
+                // NOTE: No add_edge() call — intentionally non-mutating
+
+        collected_edges = vector<pair<V, V>>
+        visitor = pgr_collect_edges_visitor{collected_edges}
+
+        // ──────────────────────────────────────────────
+        // Step 4: Call Boost algorithm
+        // ──────────────────────────────────────────────
+        // Using Overload 1 (4 parameters) because we have an explicit EdgeIndexMap.
+        // Cannot use Overload 3 (2 parameters, calls get(edge_index, g)) since
+        // pgRouting's graph has no interior edge_index_t property.
+
+        TRY:
+            boost::make_biconnected_planar(
+                graph.graph,
+                &embedding[0],
+                edge_index_pmap,
+                visitor
+            )
+        CATCH boost::exception -> rethrow
+        CATCH std::exception  -> rethrow
+        CATCH ...              -> rethrow
+
+        // ──────────────────────────────────────────────
+        // Step 5: Map Boost descriptors → pgRouting IDs
+        // ──────────────────────────────────────────────
+        // graph[descriptor].id gives the original pgRouting vertex ID.
+        // This is provided by Pgr_base_graph — "spoonfed" by the framework.
+        // No manual ID map construction needed.
+
+        results = vector<II_t_rt>(collected_edges.size())
+        FOR i = 0; i < collected_edges.size(); i++:
+            src_id = graph[collected_edges[i].first].id     // pgRouting vertex ID
+            tgt_id = graph[collected_edges[i].second].id    // pgRouting vertex ID
+            results[i] = {src_id, tgt_id}
+
+        log << "Edges to add for biconnectivity: " << results.size()
+
+        RETURN results
+```
+
+---
+
+## Driver: `makeBiconnectedPlanar_driver.cpp`
+
+```
+FILE: src/planar/makeBiconnectedPlanar_driver.cpp
+
+FUNCTION pgr_do_makeBiconnectedPlanar(
+    edges_sql,
+    return_tuples,      // OUT: II_t_rt**
+    return_count,       // OUT: size_t*
+    log_msg,
+    notice_msg,
+    err_msg
+):
+
+    TRY:
+        // Get edges from SQL
+        hint = edges_sql
+        edges = get_edges(edges_sql, true, false)
+        // true = normal, false = no reverse_cost required
+
+        IF edges.empty():
+            *notice_msg = "No edges found"
+            RETURN
+
+        hint = nullptr
+
+        // Build undirected graph
+        undigraph = pgrouting::UndirectedGraph()
+        undigraph.insert_edges(edges)
+
+        // Call wrapper
+        fn = Pgr_makeBiconnectedPlanar<UndirectedGraph>()
+        results = fn.makeBiconnectedPlanar(undigraph)
+
+        // Return results
+        IF results.empty():
+            // Already biconnected — return 0 rows (not an error)
+            *return_tuples = NULL
+            *return_count = 0
+            RETURN
+
+        *return_tuples = pgr_alloc(results.size(), *return_tuples)
+        FOR i = 0 to results.size():
+            *(*return_tuples + i) = results[i]
+        *return_count = results.size()
+
+    // Error handling: standard pgRouting pattern
+    CATCH AssertFailedException:
+        *err_msg = except.what()
+    CATCH const std::string&:       // <-- This catches our "Graph is not planar" etc.
+        *err_msg = to_pg_msg(ex)
+        *log_msg = hint ? to_pg_msg(hint) : to_pg_msg(log)
+    CATCH std::exception:
+        *err_msg = except.what()
+    CATCH ...:
+        *err_msg = "Caught unknown exception!"
+```
+
+---
+
+## Error Reporting
+
+All errors use `throw std::string(...)` — the standard pgRouting pattern.
+The driver's `catch (const std::string &ex)` block converts this to a PostgreSQL error message
+via `to_pg_msg()`.
+
+| Condition | Error Message |
+|-----------|---------------|
+| Graph not planar | `"Graph is not planar."` |
+| Graph not connected | `"Graph is not connected. Use pgr_makeConnected first."` |
+| No edges | Notice: `"No edges found"` (not an error) |
+| Already biconnected | Returns 0 rows (natural output, not an error) |
+
+**Note on connectivity check:** The proposal specifies checking connectivity as a precondition.
+Implementation decision: either check explicitly in the wrapper using `connected_components()`,
+or let `make_biconnected_planar` fail naturally on disconnected input. Will verify which
+approach is cleaner during Week 1 coding.
+
+---
+
+## Key Design Decisions
+
+1. **Non-mutating visitor:** Correct for `makeBiconnectedPlanar`. The algorithm identifies all
+   edges in a single pass over articulation points without re-reading adjacency structure.
+   (See roadmap's visitor design table for comparison with `makeMaximalPlanar`.)
+
+2. **EdgeIndexMap constructed locally:** `std::map<E, int>` wrapped in
+   `boost::associative_property_map`. pgRouting's `UndirectedGraph` does NOT have interior
+   `edge_index_t` property (confirmed from `base_graph.hpp` line 186-190 and `basic_edge.hpp`).
+
+3. **Vertex ID mapping via `graph[descriptor].id`:** Provided by `Pgr_base_graph` through
+   the `Basic_vertex` struct. No manual vertex ID map needed.
+
+4. **Embedding computed internally:** Always runs `boyer_myrvold_planarity_test` with embedding
+   parameter. The existing `boyerMyrvold.hpp` only does boolean check without embedding —
+   we call the Boost function directly with the embedding parameter.
+
+5. **Return type `II_t_rt`:** Same as `pgr_makeConnected`. Two fields: `d1` (start_vid),
+   `d2` (end_vid). The `seq` column is added by the C SRF wrapper.