Q&A: Phase 16.3 — ImprovementPlanner (priority formula, safety gate, parameters tuple, lock scope)

[web3guru888]

Q&A: Phase 16.3 — ImprovementPlanner

Issue: #423 | Show & Tell: #424

---

Q1: Why does ImprovementAction use Tuple[Tuple[str, str], ...] for parameters instead of dict?

A: ImprovementAction is a frozen dataclass, which means it must be hashable (for use in sets or as dict keys). dict is not hashable — a frozen dataclass containing a dict will raise TypeError: unhashable type: 'dict' at construction time. Using a tuple of 2-tuples keeps the dataclass hashable while still supporting key-value semantics. Convert to dict when reading: dict(action.parameters).

---

Q2: The priority formula can go negative. What happens then?

A: The formula urgency - cost_weight × cost can produce a small negative value when cost is high and urgency is low (e.g., urgency=0.1, cost=0.70 → priority=-0.11). The result is clamped to [0.0, 1.0] with min(1.0, max(0.0, priority)), so it becomes 0.0. Combined with the min_priority_threshold filter (default 0.2), such actions are discarded entirely — which is the correct behaviour: proposing an expensive module hot-swap to fix a barely-detectable weakness would be wasteful.

---

Q3: What is the scope of the asyncio.Lock in RuleBasedPlanner?

A: The lock covers the entire plan() body — both the rule-matching loop and the safety-gate calls. This means concurrent plan() calls are serialised. The rationale is that the rule table and counters are shared state; serialising is safe and the planning loop is expected to be fast (microseconds). If profiling shows contention, the lock scope can be narrowed to counter increments only — but this requires the safety-filter calls to be re-entrant, which is not guaranteed for all implementations.

---

Q4: How does _downgrade() preserve operator intent when blocking a HOT_SWAP_MODULE?

A: _downgrade() replaces action_kind with FLAG_FOR_REVIEW and prepends "[safety-gated] original=HOT_SWAP_MODULE; " to the rationale string. The module_name, priority, and parameters are preserved verbatim. This means the SelfOptimiser or a human operator can see: (a) which module was targeted, (b) what the original intent was, and (c) that it was blocked by the safety filter — without losing any diagnostic context.

---

Q5: Can I override cost estimates per-module rather than globally?

A: Not in the current PlannerConfig design, which uses a single cost_weight scalar. To support per-module overrides, extend PlannerConfig with module_cost_overrides: Tuple[Tuple[str, float], ...] = () and look up the override in plan() before applying the formula. This is a good first-contribution opportunity — see issue #423.

---

Q6: How does max_actions_per_report interact with a batch of 10 reports?

A: The current implementation applies the cap as max_actions_per_report × len(reports). With max_actions_per_report=3 and 10 reports, the global cap is 30 actions. This is intentionally permissive at the batch level — the SelfOptimiser is responsible for rate-limiting execution. If you want strict per-report caps, track a per-report counter inside the inner loop and break when it hits max_actions_per_report.

---

Q7: What does a full Grafana panel config look like for the planner?

panels:
  - title: "Actions Planned/Gated per minute"
    type: timeseries
    targets:
      - expr: rate(asi_planner_actions_planned_total[1m])
        legendFormat: "planned {{ module }}/{{ action_kind }}"
      - expr: rate(asi_planner_actions_gated_total[1m])
        legendFormat: "gated {{ module }}/{{ action_kind }}"
  - title: "Safety Gate Ratio"
    type: gauge
    targets:
      - expr: |
          rate(asi_planner_actions_gated_total[5m])
          / rate(asi_planner_actions_planned_total[5m])
    fieldConfig:
      thresholds:
        steps: [{value: 0, color: green}, {value: 0.3, color: yellow}, {value: 0.5, color: red}]
  - title: "Plan Duration p99"
    type: stat
    targets:
      - expr: histogram_quantile(0.99, rate(asi_planner_plan_duration_seconds_bucket[5m]))
  - title: "Priority Score by Module"
    type: heatmap
    targets:
      - expr: asi_planner_priority_score
        legendFormat: "{{ module }}/{{ action_kind }}"