Show & Tell: Phase 5 Implementation Architecture — OnlineLearningAdapter ABC, 12-PR Sequence, and the Path to a Self-Improving Cognitive Loop

[web3guru888]

How Phase 5 turns design into running code

Four Phase 5 milestones are designed and wikied. Now the question is: what does the implementation look like end-to-end?

I just opened Issue #204 with the full implementation sprint tracker. This thread walks through the key architectural decisions.

---

The OnlineLearningAdapter ABC

All four Phase 5 milestones share a common write-back pattern: compute a proposed update, pass it through a safety gate, then apply it to the module's state and/or Blackboard. This commonality is extracted into a single abstract base class:

class OnlineLearningAdapter(ABC):
    @abstractmethod
    async def compute_update(self, blackboard_snapshot: dict) -> WeightDelta | None: ...

    @abstractmethod
    async def apply_update(self, delta: WeightDelta) -> None: ...

    def safety_gate(self, delta: WeightDelta) -> bool:
        return delta.confidence >= 0.3

This lives in integration/online_learning.py. Every Phase 5 component — STDPLearningAdapter, CoalitionFormationAdapter, MemoryConsolidatorAdapter, ConsciousnessPlanner — subclasses it.

Why a shared ABC?

• Testability: mock the ABC once, test all subclasses with the same harness
• Safety: the safety gate is a single chokepoint — every Phase 5 write must pass through it
• Composability: a Phase5Orchestrator can hold a list[OnlineLearningAdapter] and call compute_update on all in parallel

---

The 12-PR Sequence

The implementation order is determined by data flow dependencies:

Tier 0: OnlineLearningAdapter ABC (blocks all Phase 5 PRs)
         └─ Safety gate hook into safety_module

Tier 1: Phase 5.1 — STDPLearningAdapter, FederatedHotReload, KGTransactionalWriter
         └─ Required by: Phase 5.2 (uses STDP signal), Phase 5.3 (uses KG writer)

Tier 2: Phase 5.2 — StigmergyAdapter, CoalitionFormationAdapter, role negotiation
         (can start after Tier 1-C)

Tier 3: Phase 5.3 — MemoryConsolidatorAdapter, episodic retrieval
         (after Tier 1-E, the KG writer)

Tier 4: Phase 5.4 — GWTInferenceBridge, ConsciousnessPlanner
         (self-contained after Tier 0; doesn't need 5.1–5.3 to start)

Phase 5.4 can actually land first after Tier 0, because ConsciousnessPlanner reads existing Blackboard keys — it doesn't depend on the new write-back adapters from 5.1–5.3.

---

WeightDelta — the universal unit of Phase 5 change

@dataclass
class WeightDelta:
    source_module: str       # which module generated this delta
    parameter_path: str      # dotted path to the parameter being updated
    delta: Any               # actual tensor / numeric update
    confidence: float        # [0.0, 1.0] — safety gate threshold
    metadata: dict           # provenance: tick_id, phase, source_data_hash

WeightDelta is the lingua franca of Phase 5. Every adaptive update — STDP synaptic change, federated weight reload, memory salience recalculation, goal reordering — is represented as a WeightDelta before being applied. This makes every Phase 5 change:

• Auditable: the Blockchain module can hash-chain WeightDelta records
• Reversible: the safety module can hold a delta in a buffer and apply/reject
• Comparable: the MeshResultAggregator can merge WeightDelta objects using the WEIGHTED strategy

---

What I'm watching for in the first Phase 5 PRs

1. Is the safety gate tested under adversarial inputs? A confidence=0.299 delta that just misses the gate — does it fail gracefully?
2. Does ConsciousnessPlanner correctly handle Φ = 0.0? The regression test: when IIT Φ drops to zero, the planner should fall back to the original goal order without panicking.
3. SLEEP_PHASE timing: MemoryConsolidatorAdapter runs during SLEEP_PHASE, but SLEEP_PHASE isn't a real CognitiveCycle phase — it's a bio_inspired module state. The integration needs a Blackboard event to trigger consolidation, not a direct CognitiveCycle hook.

Thread below for discussion — especially interested in the SLEEP_PHASE triggering mechanism.

[web3guru888]

Implementation Notes — OnlineLearningAdapter Design Walkthrough

The OnlineLearningAdapter ABC is deliberately minimal — here's why each design choice was made.

---

Why compute_update takes a blackboard_snapshot dict

Instead of injecting the live Blackboard reference into every adapter, we pass a snapshot. This:

1. Prevents mid-computation mutations — the adapter sees a consistent point-in-time view
2. Enables testing without a real Blackboard — pass a plain dict in unit tests
3. Bounds latency — the snapshot is taken once; the adapter can't hold the Blackboard lock while computing

The CognitiveCycle creates the snapshot atomically before calling compute_update:

snapshot = blackboard.snapshot(namespaces=["bio_inspired.*", "mesh.*", "consciousness.*"])
await adapter.compute_update(snapshot)

---

Why safety gate is synchronous

safety_gate(delta) is synchronous and runs before apply_update. The pattern:

async def tick(self, snapshot: dict) -> None:
    delta = await self.compute_update(snapshot)  # async — may touch I/O
    if delta is None:
        return  # nothing to update
    if not self.safety_gate(delta):  # sync — fast path rejection
        await self._log_rejection(delta)
        return
    # For non-trivial deltas, also check with the formal safety module:
    if delta.confidence < 0.7:
        verdict = await self._safety_adapter.verify(delta.to_ethical_context())
        if not verdict.approved:
            return
    await self.apply_update(delta)  # async — modifies module state

The two-stage approach: fast synchronous gate (always runs), formal async verification (only for lower-confidence updates). This keeps the hot path fast.

---

The NAMESPACE class variable pattern

Each adapter declares its namespace at the class level:

class STDPLearningAdapter(OnlineLearningAdapter):
    NAMESPACE = "online.stdp"

class CoalitionFormationAdapter(OnlineLearningAdapter):
    NAMESPACE = "mesh.coalition"

This means you can query all online learning events by namespace prefix, regardless of adapter type. The Blackboard namespace table in #176 was designed with this in mind.

Full wiki: Online-Learning-Adapter