Leverage-point depth classification alongside the leverage composite

[razinkele]

Warning

Check the source before implementing. The Geekiyanage abstract was never returned by the literature API — eight scite queries that week hit a persistent ranking fault. This draft is motivated by the paper's stated framing, not replicated from its content. The depth scheme below should be validated against the full text before any code is written; if the paper uses a different taxonomy, follow the paper.

Source papers

• Geekiyanage, Fernando & Teixeira Fernando (2026). Revealing leverage points of anticipatory action for fisheries through a systems thinking lens in developing island states. Climate Risk Management 53:100843. https://doi.org/10.1016/j.crm.2026.100843
• Brons, Mathijs & Kiel (2026). Leveraging change: a soft systems approach to transforming the EU food system. Sustainability Science. https://doi.org/10.1007/s11625-026-01872-2

Alert week: 2026-08-25 (see LITERATURE/2026-08-25.md, item H2).

Motivation

Both papers identify leverage points by intervention depth (parameter → feedback structure → rules → goals/paradigm), not by structural prominence.

SESPy's leverage composite z(betweenness)+z(eigenvector)+z(PageRank) says a node is well-positioned but not how deep an intervention on it would reach. Two nodes with identical scores can therefore imply very different policy asks — one a parameter tweak, the other a change of system goal — and the current output gives the user no way to tell them apart.

Proposal

Extend the leverage output with a categorical leverage_depth column derived from (a) the node's DAPSI(W)R(M) type and (b) whether it participates in a detected feedback loop:

Node	Depth
Pressure / Marine Process and Function	parameter
Activity inside a loop	feedback structure
Measure / response node	rules
Driver	goals / paradigm

Report depth next to the z-score composite in the Leverage module and allow sorting by it.

Acceptance criteria

• leverage_scores() output gains a leverage_depth column with the four classes above (or the paper's taxonomy, if it differs — see the warning).
• Depth assignment documented and configurable via a mapping table, not hard-coded.
• Existing composite ranking unchanged; depth is purely additive.

Effort: moderate.

[razinkele]

Correction — this substantially overlaps a feature that already ships

A multi-agent review of the follow-up plan checked this issue against the code and found the premise is wrong. Verified directly:

• sespy.network.leverage_realm() already exists (sespy/network.py:433) and returns exactly a four-level Meadows taxonomy: parameters | feedbacks | design | intent.
• It is already rendered as the "realm" column in the Leverage module — sespy/modules/analysis_leverage.py:154 (token), :160 (i18n label), :208 (base_cols).

So the motivating gap ("the composite says a node is well-positioned, not how deep an intervention reaches") is already addressed. Worse, the mapping proposed in this issue contradicts the shipped one:

Element type	Shipped leverage_realm	Proposed here
Marine Processes & Functioning	feedbacks	parameter
Ecosystem Services / Goods & Benefits	parameters	(unlisted)
Activities	design	feedback structure (if in a loop)
Measures	"" (documented gap)	rules
Drivers	—	goals / paradigm

Implementing as written would land two conflicting depth columns in one table.

Revised scope

The remaining real contribution is the loop-membership signal — leverage_realm is a pure function of element type and cannot distinguish an Activity inside a feedback loop from one outside it. That is worth adding.

So the first step is reconciliation, not implementation: decide whether to (a) refine leverage_realm with loop membership, or (b) amend its mapping — explicitly not to add a parallel leverage_depth column.

Two constraints for whoever picks this up:

1. leverage_scores() returns dict[str, float] and MosaicSES consumes .values() (multises/comparative.py:47,138). That return shape is a cross-repo contract — changing it breaks MosaicSES. The shipped realm column is the proof of the safe pattern: it was added UI-side with leverage_scores() untouched.
2. The source-paper caveat in the original description still stands and is now confirmed harder than first thought. Four retrieval routes were tried: scite by DOI returns metadata only (contentDenied, no abstract); a scite full-text query returns no excerpts (not indexed); doi.org resolves to an Elsevier redirect shell; ScienceDirect returns HTTP 403. The paper is gold OA (cc-by-nc-nd) but not machine-retrievable — it needs a human-driven fetch via institutional access. Until then any taxonomy change here is unvalidated against the source.