Show & Tell — Phase 18.1 HorizonPlanner: Multi-Horizon Goal Decomposition

[web3guru888]

Show & Tell — Phase 18.1: HorizonPlanner Architecture

Companion to Issue #450 | Phase 18 Planning: Discussion #449

What is the HorizonPlanner?

Until now, ASI:BUILD's planning stack treated all goals as equal-priority work items. The HorizonPlanner adds temporal scale awareness: every goal is assigned to one of three planning horizons based on how much time remains before its deadline.

---

Full Data Flow

GoalRegistry.add_goal(goal_id, deadline_ns)
        │
        ▼
HorizonPlanner.classify(goal_id, deadline_ns)
        │
        ├── delta_ms ≤ 10 000 ms  ──► SHORT  bucket (min-heap, deadline order)
        ├── delta_ms ≤ 300 000 ms ──► MEDIUM bucket (min-heap, deadline order)
        └── delta_ms > 300 000 ms ──► LONG   bucket (min-heap, deadline order)
                │
                │  [background rebalance loop, every 1 s]
                │  Goals crossing boundary are moved between heaps
                ▼
CognitiveCycle._temporal_step()
        │
        ├── drain(SHORT,  n=8)  ──► PlanExecutor (immediate dispatch)
        ├── drain(MEDIUM, n=4)  ──► PlanExecutor (next-tick dispatch)
        └── drain(LONG,   n=1)  ──► GoalDecomposer (sub-goal expansion)

---

PlanningHorizon Boundaries

Horizon	Default window	Typical use case
SHORT	≤ 10 000 ms	Sensor responses, safety reactions, real-time actuator commands
MEDIUM	≤ 300 000 ms	Module optimisation runs, data collection tasks, federation sync
LONG	> 300 000 ms	Architecture evolution goals, multi-day training runs, strategic objectives

Boundaries are HorizonConfig-tunable — a latency-sensitive deployment might use short_horizon_ms=500.

---

Rebalance Algorithm

Goals can slide between horizons as real time passes:

Every rebalance_interval_s (default 1 s):
  For each horizon H in [SHORT, MEDIUM, LONG]:
    surviving = []
    for (deadline_ns, gid) in heap[H]:
      delta_ms = (deadline_ns - now_ns) / 1e6
      new_H = classify(delta_ms)
      if new_H != H:
        push (deadline_ns, gid) → heap[new_H]   # promote / demote
      else:
        surviving.append(...)
    heap[H] = heapify(surviving)

A LONG goal with 6 minutes left becomes MEDIUM → then SHORT as deadlines approach. No manual re-registration required.

---

CognitiveCycle Integration

# Phase 17 baseline
async def _temporal_step(self) -> None:
    await self._temporal_orchestrator.run_cycle()

# Phase 18.1 addition
async def _temporal_step(self) -> None:
    await self._temporal_orchestrator.run_cycle()
    urgent = await self._horizon_planner.drain(PlanningHorizon.SHORT, n=8)
    for gid in urgent:
        goal = await self._goal_registry.get(gid)
        await self._plan_executor.submit(goal)

---

Prometheus Metrics

Metric	Type	What it tells you
asi_horizon_classified_total{horizon}	Counter	Volume of goals entering each horizon
asi_horizon_rebalanced_total{from_h,to_h}	Counter	Horizon transitions (promotion/demotion rate)
asi_horizon_drained_total{horizon}	Counter	Goals dispatched per horizon per tick
asi_horizon_bucket_size{horizon}	Gauge	Current backlog per horizon
asi_horizon_rebalance_duration_seconds	Histogram	Cost of rebalance pass

PromQL alerts

# SHORT horizon backlog growing — may miss deadlines
asi_horizon_bucket_size{horizon="short"} > 32

# Rebalance taking too long (> 100ms)
histogram_quantile(0.95, rate(asi_horizon_rebalance_duration_seconds_bucket[5m])) > 0.1

# Rapid demotion MEDIUM→SHORT — planning horizon too optimistic
rate(asi_horizon_rebalanced_total{from_h="medium",to_h="short"}[2m]) > 5

---

Open Questions

1. Drain quota per horizon — fixed n per _temporal_step() or proportional to bucket size?
2. Goal expiry — should goals with deadline_ns < now_ns be auto-dropped from heaps during rebalance, or forwarded to PlanExecutor with an EXPIRED flag?
3. Persistent horizon state — should HorizonBucket contents survive a TemporalOrchestrator restart (snapshot), or is re-registration from GoalRegistry preferred?

---

Drop benchmark ideas, integration questions, or horizon-boundary suggestions below 👇