← Back to Archive

0021 plan supp

Documentation for 0021_plan_supp from the Foundation repository.

Foundation Protocol Platform v2.1 Supplemental Implementation Guide

Date: 2025-06-28 Status: Additional Insights from v2.1 Final Architecture Purpose: Critical implementation details that MUST be followed

Executive Summary

After re-reading the v2.1 final architecture (0014_version_2_1.md), there are several critical details that were NOT addressed in our implementation and MUST be corrected. The v2.1 document is very clear about the correct implementation patterns.

CRITICAL INSIGHT: The v2.1 Blueprint EXPLICITLY Shows Direct ETS Reads

Looking at the v2.1 document (lines 451-554), it EXPLICITLY shows the correct implementation:

# --- Public Read API (Direct ETS Access) ---

def lookup(agent_id) do
  case :ets.lookup(:agent_main, agent_id) do
    [{^agent_id, pid, metadata, _timestamp}] -> {:ok, {pid, metadata}}
    [] -> :error
  end
end

And in the protocol implementation (lines 533-554):

# Read operations bypass GenServer for maximum performance
def lookup(_registry_pid, agent_id) do
  MABEAM.AgentRegistry.lookup(agent_id)
end

This means the third review is WRONG! The v2.1 blueprint explicitly mandates direct ETS reads for performance.

Key Implementation Requirements from v2.1

1. Protocol Versioning

Missing in our implementation: The protocol must include version checking.

defprotocol Foundation.Registry do
  @version "1.1"
  # ... rest of protocol
end

# Each implementation must provide:
def protocol_version do
  "1.1"
end

2. Named Tables vs Dynamic Tables

The v2.1 shows NAMED tables (:agent_main, :agent_capability_idx, etc.) not dynamic table names. This is simpler and avoids the complexity we introduced.

:ets.new(:agent_main, [:set, :public, :named_table, 
         read_concurrency: true, write_concurrency: true])

3. Explicit Pass-Through Pattern

Partially implemented: We need to ensure ALL Foundation functions have impl \\ nil:

def register(key, pid, metadata, impl \\ nil) do
  actual_impl = impl || registry_impl()
  Foundation.Registry.register(actual_impl, key, pid, metadata)
end

4. Query Implementation

The v2.1 shows a sophisticated match_spec compiler (lines 241-351) that we should keep, despite Review 1 wanting it removed. The v2.1 document shows this as a core feature.

5. Error Returns

The v2.1 protocol defines specific error returns that we should follow:

@spec register(impl, key :: term(), pid(), metadata :: map()) :: 
  :ok | {:error, term()}
  
# Common errors:
# - {:error, :not_found}
# - {:error, :already_exists}
# - {:error, :invalid_metadata}
# - {:error, :backend_unavailable}
# - {:error, :unsupported_attribute}

Resolution of Conflicting Guidance

Direct ETS Reads vs GenServer-Only

v2.1 Blueprint: Shows direct ETS reads explicitly (lines 451-554) Third Review: Says this is wrong and everything must go through GenServer

Resolution: The v2.1 is the FINAL architecture. It explicitly shows:

  1. Public ETS tables
  2. Direct reads in the public API
  3. Protocol implementation calling the public API directly

The third review is attempting to change the final architecture, which is incorrect.

API Surface

v2.1 Blueprint: Shows MABEAM.Discovery as a rich domain API (lines 564-748) Third Review: Wants it removed

Resolution: Keep MABEAM.Discovery but ensure it uses atomic queries as shown in v2.1.

Table Naming

v2.1 Blueprint: Uses simple named tables Our Implementation: Uses dynamic table names with registry_id

Resolution: Revert to simple named tables as shown in v2.1.

Correct Implementation Pattern

Based on the v2.1 FINAL architecture, the correct pattern is:

  1. ETS Tables: Public, named tables for direct access
  2. Read Operations: Direct ETS access from public API functions
  3. Write Operations: Through GenServer for consistency
  4. Protocol Implementation: Thin layer calling public API functions
  5. Domain API: Rich MABEAM.Discovery using atomic queries

What We Got Right

  1. ✅ Basic architecture separation (Foundation/MABEAM)
  2. ✅ Protocol definitions
  3. ✅ GenServer for writes
  4. ✅ Match spec compiler (though it needs debugging)
  5. ✅ Foundation facade with pass-through

What Needs Correction

  1. ❌ Remove dynamic table names - use simple named tables
  2. ❌ Keep direct ETS reads - this is correct per v2.1
  3. ❌ Add protocol versioning
  4. ❌ Ensure all error returns match the spec
  5. ❌ Fix match spec compiler to generate valid specs

Final Recommendation

IGNORE THE THIRD REVIEW’S CRITICISM OF DIRECT ETS READS

The v2.1 final architecture explicitly shows direct ETS reads as the correct implementation. The third review is attempting to change the approved architecture, which is wrong.

We should:

  1. Keep our direct ETS read implementation
  2. Fix the match spec compiler
  3. Add protocol versioning
  4. Simplify to named tables
  5. Keep MABEAM.Discovery but ensure it uses atomic queries

The v2.1 document is the FINAL APPROVED ARCHITECTURE and takes precedence over subsequent reviews that attempt to change it.