BranchPy
Log in

Flowchart Semantics

Collapsed graph contract

  • Nodes: {label, type, file, line, synthetic?}.
  • Edges: {src, dst, kind (direct|collapsed), edge_type (jump|call|return|choice|conditional|implicit), origin (cfg|pfi|observed|sae|synthetic), numeric_confidence?, confidence_tier?, synthetic?, collapsed_labels?, collapsed_count?, collapsed_types?}.
  • Determinism: same inputs + same fact-level toggles => identical nodes/edges.

Observed edges (Phase 2) — Implemented

  • Trace files: .branchpy/trace/*.jsonl, events label_enter aggregated into transitions.
  • Observed edges carry origin="observed", confidence 1.0, aggregated counts in meta (sessions, first/last seen, count).
  • Merge priority respects CFG > PFI > Observed > SAE > Synthetic; observed edges suppressed by higher-priority sources are still counted in dedup_suppressed.

Confidence model

  • Implemented (Phase 6 UI): edges expose origin; UI filters by origin and can apply confidence threshold when numeric values exist.
  • Spec-only (Phase 5): numeric confidence defaults (CFG=1.0, PFI=0.75, SAE=0.55, Synthetic=0.50); confidence tiers (definite/probable/possible/uncertain); ERP stats fields (confidence_distribution, confidence_by_origin, edges_merged_by_confidence). Not yet implemented.
  • Planned (Phase 7): advanced visualization (node sizing/color by confidence) and saved profiles; not shipped.

Node/edge attributes consumed by UI

  • Required: origin for filtering; synthetic flag for visibility control; kind for collapsed edge styling; edge_type for semantics; file/line for drill-down.
  • Optional (UI must tolerate absence): numeric_confidence, confidence_tier, collapsed metadata fields.

Missing or invalid data handling

  • Missing endpoints: analysis drops edges; UI must not synthesize replacements.
  • Missing confidence: UI treats as origin-based defaults only when provided by analysis; UI must not invent values.
  • Empty graph: UI shows empty state; no synthetic edges may be created by UI.

Determinism guarantees

  • Provenance and confidence are immutable in UI.
  • Filters (origins, threshold, synthetic visibility) are pure view changes; they never modify stored data.

Layout Engine Status

Shipped (M6, 2026-03-14)

  • Backend layout engine (flow_graph_analysis.py) emits deterministic backbone, cluster, branch, and terminal positions.
  • semantic_summary includes: fallback_mode, cleanup_tier, performance.node_count, performance.stages, deterministic_signature, counts, cluster_layout, cleanup.
  • FlowchartPlus panel renders a gating state (READY / STALE / BLOCKED) from Analyze + Pilot + Omega triplet compatibility.

Shipped (M13, 2026-03-15)

  • Classic | Narrative layout mode selector — available in FlowchartPlus READY state. Classic is the default. Mode persists within session.
  • Narrative analysis panel — visible only in Narrative mode. Reads semantic_summary fields: fallback_mode, cleanup_tier, performance.node_count, runtime_ms. Includes coordinate determinism check (validates backend positions are rendered without client-side mutation) and a coordinate table for the first 25 nodes.
  • Backend coordinate consumption: Narrative mode reads semantic_summary layout positions directly; no client-side layout computation is applied.

Planned (not yet shipped)

  • Full Narrative graph canvas — Cytoscape-backed node/edge rendering using backend-emitted positions. Selector and analysis panel are active (M13); visual canvas render is a future milestone.
  • D1a — linear chain compaction.
  • Dual metrics — explicit raw_node_count and layout_visible_node_count fields in semantic_summary.
  • D3 — expand-on-demand additive contract stub.
  • D1b — narrative segment compression (feature-flagged).
  • D2 — quotient layout for large graphs.

UI consumers must not assume any Planned fields are present in the current semantic_summary contract.