← Back to DocsPerimeter

README

Documentation for README from the Foundation repository.

Foundation Perimeter Documentation

Overview

Foundation Perimeter implements the revolutionary “Defensive Perimeter / Offensive Interior” pattern specifically designed for BEAM-native AI systems. This documentation set provides comprehensive guidance for implementing, deploying, and operating Foundation Perimeter in production environments.

Documentation Structure

📋 Core Documentation

  1. Foundation Perimeter Architecture

    • Four-Zone Architecture for BEAM AI systems
    • Zone mapping to Foundation/Jido components
    • Performance optimization strategy
    • Strategic value and benefits

  2. Foundation Perimeter Contracts

    • AI-native type system integration
    • Contract specifications for all zones
    • Foundation-specific type definitions
    • Validation patterns and implementations

  3. Foundation Perimeter Implementation

    • Technical implementation details
    • Service integration patterns
    • Performance optimization techniques
    • Production readiness considerations

🧪 Quality Assurance

  1. Foundation Perimeter Testing
    • Comprehensive testing strategy
    • Performance benchmarking
    • Property-based testing patterns
    • Load testing and validation

🚀 Operations

  1. Foundation Perimeter Deployment

    • Production deployment guide
    • Configuration management
    • Monitoring and observability
    • Performance tuning strategies

  2. Foundation Perimeter Migration Guide

    • Step-by-step migration process
    • Compatibility assessment
    • Risk mitigation strategies
    • Rollback procedures

Quick Start

Prerequisites

  • Foundation: Version 2.0.0+
  • Jido System: Version 1.0.0+
  • Elixir: Version 1.15+
  • OTP: Version 26+

Installation

# mix.exs
defp deps do
  [
    {:foundation_perimeter, "~> 1.0"},
    {:stream_data, "~> 0.5", only: [:test]}
  ]
end

Basic Configuration

# config/config.exs
import Config

config :foundation,
  perimeter_enabled: true

config :foundation, Foundation.Perimeter,
  enforcement_config: %{
    external_level: :strict,
    service_level: :optimized,
    coupling_level: :none,
    core_level: :none
  }

Simple Contract Example

defmodule MyApp.ExternalAPI do
  use Foundation.Perimeter
  
  external_contract :create_ml_program do
    field :name, :string, required: true, length: 1..100
    field :schema_fields, {:list, :map}, required: true
    field :foundation_context, foundation_context(), required: true
    
    validate :ensure_schema_validity
  end
  
  def create_program(params) do
    # Validation happens automatically via external_contract
    # params are guaranteed to be valid here
    Foundation.MLPrograms.create(params)
  end
end

Architecture Overview

Foundation Perimeter implements a Four-Zone Architecture that strategically places validation boundaries across Foundation/Jido integration points:

┌─────────────────────────────────────────────────────────┐
│ Zone 1: External Perimeter (Maximum Validation)        │
│ ├── DSPEx program creation                              │
│ ├── Jido agent deployment                               │
│ ├── ML pipeline execution                               │
│ └── Multi-agent coordination                            │
├─────────────────────────────────────────────────────────┤
│ Zone 2: Service Boundaries (Strategic Validation)      │
│ ├── Foundation.Registry operations                      │
│ ├── Foundation.MABEAM coordination                      │
│ ├── Foundation.Coordination services                    │
│ └── Cross-service communication                         │
├─────────────────────────────────────────────────────────┤
│ Zone 3: Coupling Zone (Productive Coupling)            │
│ ├── Foundation ↔ Jido direct calls                     │
│ ├── Shared data structure access                        │
│ ├── Agent coordination optimization                     │
│ └── Signal routing enhancement                          │
├─────────────────────────────────────────────────────────┤
│ Zone 4: Core Engine (Zero Validation)                  │
│ ├── Foundation.Core protocols                           │
│ ├── Signal routing hot paths                            │
│ ├── BEAM message optimization                           │
│ └── Foundation telemetry core                           │
└─────────────────────────────────────────────────────────┘

Key Benefits

🚀 Performance Revolution

  • 60% validation overhead reduction (14% → 6.5% of request time)
  • Protocol dispatch optimization (4ms → 1ms for Foundation protocols)
  • Zero coupling penalty between Foundation and Jido
  • Microsecond core operations maintained

🔒 Enterprise Security

  • Strategic validation placement only where it adds value
  • AI-native input sanitization for LLM integration
  • Comprehensive audit logging with zone-specific context
  • Circuit breaker protection against validation failures

🏗️ Architectural Excellence

  • Foundation-native integration with existing protocols
  • Productive coupling enablement for related components
  • Clear separation of concerns across validation zones
  • BEAM-optimized patterns throughout the architecture

🔧 Operational Simplicity

  • Single repository for Foundation/Perimeter development
  • Unified testing of Foundation contracts
  • Simplified debugging with clear zone boundaries
  • Foundation-specific optimization without external dependencies

Implementation Phases

The Foundation Perimeter implementation follows a four-phase approach:

Phase 1: Foundation Infrastructure (Weeks 1-2)

  • Install Perimeter services in Foundation supervision tree
  • Configure basic validation and monitoring
  • Establish telemetry and error handling

Phase 2: External Perimeter (Weeks 3-4)

  • Migrate external APIs to Zone 1 validation
  • Implement external contract validation
  • Test with production traffic patterns

Phase 3: Service Boundaries (Weeks 5-6)

  • Migrate Foundation services to Zone 2 strategic boundaries
  • Add service boundary validation with performance optimization
  • Enable cross-service communication enhancements

Phase 4: Coupling Optimization (Weeks 7-8)

  • Enable Zone 3 productive coupling between Foundation/Jido
  • Remove artificial boundaries and validation overhead
  • Achieve full performance benefits and optimization

Performance Expectations

Before Foundation Perimeter

external_request                                    # 0ms
|> Foundation.Services.validate_everywhere()       # 14ms (current overhead)
|> Foundation.Registry.lookup()                    # 2ms  
|> Foundation.Coordination.coordinate()            # 8ms
|> Foundation.Core.execute()                       # 5ms
# Total: 29ms (48% validation overhead)

After Foundation Perimeter

external_request                                    # 0ms
|> Foundation.Perimeter.External.validate()        # 5ms (Zone 1 only)
|> Foundation.Registry.lookup()                    # 2ms (Zone 2, cached)
|> Foundation.Coordination.coordinate()            # 8ms (Zone 3, no validation)
|> Foundation.Core.execute()                       # 5ms (Zone 4, no validation)
# Total: 20ms (25% validation overhead - 60% improvement)

Getting Help

Documentation Navigation

Support Resources

  • Foundation Issues: Report issues with Foundation integration
  • Performance Questions: Performance optimization and tuning
  • Migration Support: Assistance with migration planning and execution
  • Architecture Reviews: Architectural guidance and best practices

Implementation Prompts

This directory contains self-contained implementation prompts for each component of Foundation Perimeter. Each prompt includes complete context, requirements, specifications, and comprehensive test requirements following Foundation’s testing standards.

Available Prompts

  1. PROMPT_01_VALIDATION_SERVICE.md - Core ValidationService implementation

    • GenServer with ETS caching and performance monitoring
    • Foundation telemetry integration and circuit breaker protection
    • Comprehensive test suite with UnifiedTestFoundation

  2. PROMPT_02_CONTRACT_REGISTRY.md - Contract discovery and registration

    • GenServer-based contract registry with ETS caching
    • Dynamic contract discovery and zone-aware categorization
    • Hot-reloading support and optimized lookup patterns

  3. PROMPT_03_EXTERNAL_CONTRACTS.md - Zone 1 external contract implementation

    • Macro-based DSL for external contract definition
    • Compile-time validation function generation
    • Comprehensive field validation with constraints and error reporting

  4. PROMPT_04_SERVICE_BOUNDARIES.md - Zone 2 service boundary implementation

    • Strategic boundary contracts for service-to-service communication
    • Service trust levels and adaptive validation
    • Performance optimization with caching and minimal validation modes

  5. PROMPT_05_COUPLING_ZONES.md - Zone 3 coupling zone optimization

    • Ultra-fast validation for tight coupling scenarios
    • Hot-path detection and adaptive optimization
    • Load-aware validation scaling with minimal overhead

  6. PROMPT_06_CORE_ENGINE.md - Zone 4 core engine zero-overhead implementation

    • Zero validation overhead with compile-time contract verification
    • Trust-based operation with optional performance profiling
    • Maximum performance for critical internal operations

Using the Prompts

Each prompt is completely self-contained and can be executed independently in a fresh context. They include:

  • Complete context about Foundation Perimeter and the Four-Zone Architecture
  • Detailed specifications with code examples and API definitions
  • Comprehensive test requirements following Foundation’s event-driven testing philosophy
  • Performance targets and success criteria
  • Integration patterns with Foundation services and telemetry

Test-Driven Development

All prompts follow Foundation’s testing standards:

  • No Process.sleep/1 usage (event-driven coordination only)
  • Foundation.UnifiedTestFoundation for proper test isolation
  • Telemetry-driven assertions with assert_telemetry_event
  • Performance verification with measurable targets
  • Property-based testing where applicable

Contributing

Foundation Perimeter is designed to evolve with Foundation’s development. Contributions should:

  1. Follow Four-Zone Architecture principles
  2. Maintain Foundation integration patterns
  3. Include comprehensive tests for all zones
  4. Document performance impact of changes
  5. Preserve backward compatibility where possible

License

Foundation Perimeter follows the same license as the Foundation project.

Foundation Perimeter represents the evolution of BEAM-native AI systems toward strategic validation placement, productive coupling, and enterprise-grade performance. This documentation provides everything needed to implement, deploy, and operate Foundation Perimeter successfully in production environments.