Q&A: Phase 16.4 — SelfOptimiser (rate-limit, dispatcher, dry-run, HOT_SWAP wiring, mocking)

[web3guru888]

Q&A: Phase 16.4 — SelfOptimiser (rate-limiting, dispatch, dry-run, HOT_SWAP wiring)

Issue: #426 | Show & Tell: #427 | Wiki: Phase 16 — SelfOptimiser

---

Q1: Why is _lock held for the entire enact() loop rather than per-action?

A: The coarse lock prevents two concurrent enact() calls from both passing the rate-limit check for the same (module, kind) key simultaneously. If call A and call B both see last_ts=0 and both see the cool-down has not been exceeded, both would succeed — defeating the throttle. Holding one lock serialises all enactments so rate-limit state is always coherent.

If you need parallel enactment for different modules (lower latency at scale), replace the single _lock with a defaultdict(asyncio.Lock) keyed by module_name — then only enactments for the same module are serialised.

---

Q2: What happens if LiveModuleOrchestrator is not injected and a HOT_SWAP_MODULE action arrives?

A: _apply_hot_swap checks if self._orch is None and returns EnactmentStatus.SKIPPED with detail="no orchestrator injected". No exception is raised. This allows SelfOptimiser to function in degraded mode (observe + plan but not swap) when the orchestrator is unavailable or not yet initialised.

---

Q3: How does dry_run=True interact with FLAG_FOR_REVIEW?

A: dry_run is checked at the top of _dispatch() before the match statement, so all actions — including FLAG_FOR_REVIEW — are short-circuited to SKIPPED. Nothing is enqueued to alert_queue in dry-run mode. This makes dry-run a true no-side-effect observation pass.

if cfg.dry_run:
    return self._record(action, EnactmentStatus.SKIPPED,
                        f"dry-run: would enact {action.action_kind.name}", t0)

---

Q4: What is the attempted_at field on EnactmentRecord used for?

A: attempted_at records the monotonic timestamp at which enactment was attempted. ReflectionCycle (Phase 16.5) uses this to:

1. Build a retrospective timeline of which actions were taken and when.
2. Detect stale records — if a record is older than one reflection cycle, discard it from the active window.
3. Calculate time-to-enactment lag: attempted_at - action_creation_time (if planners stamp actions with a creation time).

---

Q5: Can two EnactmentRecords for the same action appear in the same enact() call?

A: No. The loop iterates actions (a Sequence) and produces exactly one EnactmentRecord per element. If the same ImprovementAction object appears twice in the sequence (unlikely but possible if a caller dedupes poorly), it would produce two records with the second subject to rate-limiting (since the first updates _last_enacted immediately on SUCCESS).

---

Q6: How do I mock CognitiveCycle for _apply_tune in tests?

A: Use a simple namespace object with the _detector_config attribute:

import types

mock_cycle = types.SimpleNamespace(
    _detector_config=DetectorConfig(latency_p95_threshold_ms=200.0,
                                    latency_p99_threshold_ms=500.0,
                                    error_rate_threshold=0.05),
)
opt = AsyncSelfOptimiser(cognitive_cycle=mock_cycle)
records = await opt.enact([tune_action])
assert records[0].status == EnactmentStatus.SUCCESS
assert mock_cycle._detector_config.latency_p95_threshold_ms > 200.0

---

Q7: Grafana 4-panel dashboard YAML for SelfOptimiser

panels:
  - title: Enactment Rate (by status)
    type: timeseries
    expr: rate(asi_optimiser_actions_enacted_total[5m])
    legendFormat: "{{action_kind}} / {{status}}"

  - title: Rate-Limited Actions
    type: stat
    expr: increase(asi_optimiser_actions_rate_limited_total[1h])
    legendFormat: "Rate-limited (1h)"

  - title: Hot-Swap Success Rate
    type: gauge
    expr: >
      rate(asi_optimiser_hot_swaps_total{outcome="SUCCESS"}[10m])
      / rate(asi_optimiser_hot_swaps_total[10m])
    thresholds: [0.8, 0.95]

  - title: Enactment Duration p95 (by action_kind)
    type: timeseries
    expr: histogram_quantile(0.95, rate(asi_optimiser_enact_duration_seconds_bucket[5m]))
    legendFormat: "{{action_kind}} p95"