Layer 1: Runtime

Overview

The Runtime Layer (L1) is the foundational layer of ARAL, providing the execution environment, resource management, and platform abstraction for AI agents. It serves as the bedrock upon which all other layers are built.

Responsibilities

microchip Process Management

Lifecycle control, spawning, and termination of agent processes

gauge Resource Allocation

CPU, memory, storage, and network resource management

layer-group Platform Abstraction

Uniform interface across different execution environments

triangle-exclamation Error Handling

Fault detection, recovery, and graceful degradation

Architecture

Key Components

1. Process Management

Controls the agent’s lifecycle from initialization to termination.

interface ProcessManager {
  // Lifecycle control
  start(): Promise<void>
  stop(graceful: boolean): Promise<void>
  restart(): Promise<void>

  // Status monitoring
  getStatus(): ProcessStatus
  isHealthy(): boolean

  // Event hooks
  onStart(callback: () => void): void
  onStop(callback: () => void): void
  onError(callback: (error: Error) => void): void
}

// Example implementation
class AralRuntime implements ProcessManager {
  async start(): Promise<void> {
    // Initialize runtime
    await this.loadConfig()
    await this.initializeResources()
    await this.registerShutdownHandlers()

    console.log('Agent runtime started')
  }

  async stop(graceful: boolean = true): Promise<void> {
    if (graceful) {
      // Allow current operations to complete
      await this.drainQueue()
      await this.closeConnections()
    }

    await this.releaseResources()
    console.log('Agent runtime stopped')
  }
}

from abc import ABC, abstractmethod
from typing import Callable

class ProcessManager(ABC):
    """Interface for agent process management"""

    @abstractmethod
    async def start(self) -> None:
        """Start the agent process"""
        pass

    @abstractmethod
    async def stop(self, graceful: bool = True) -> None:
        """Stop the agent process"""
        pass

    @abstractmethod
    def get_status(self) -> ProcessStatus:
        """Get current process status"""
        pass

class AralRuntime(ProcessManager):
    async def start(self) -> None:
        # Initialize runtime
        await self.load_config()
        await self.initialize_resources()
        await self.register_shutdown_handlers()

        print("Agent runtime started")

    async def stop(self, graceful: bool = True) -> None:
        if graceful:
            # Allow current operations to complete
            await self.drain_queue()
            await self.close_connections()

        await self.release_resources()
        print("Agent runtime stopped")

2. Resource Management

Allocates and monitors compute resources (CPU, memory, I/O).

microchip CPU Management

{
  "resources": {
    "cpu": {
      "limit": "2000m",      // 2 CPU cores max
      "request": "500m",     // 0.5 CPU cores guaranteed
      "throttling": "enabled"
    }
  }
}

Best Practices:

• Set reasonable limits to prevent resource exhaustion
• Monitor CPU usage and throttle if needed
• Use worker pools for CPU-intensive tasks

memory Memory Management

{
  "resources": {
    "memory": {
      "limit": "2Gi",        // 2GB max
      "request": "512Mi",    // 512MB guaranteed
      "swap": "disabled"
    }
  }
}

Best Practices:

• Set memory limits to prevent OOM kills
• Implement memory leak detection
• Use streaming for large data processing
• Clear caches periodically

hard-drive Storage Management

{
  "resources": {
    "storage": {
      "persistent": "/data",
      "ephemeral": "/tmp",
      "maxSize": "10Gi"
    }
  }
}

Best Practices:

• Separate persistent from ephemeral storage
• Implement disk space monitoring
• Use cleanup policies for temp files

network-wired Network Management

{
  "resources": {
    "network": {
      "bandwidth": "100Mbps",
      "connections": 1000,
      "timeout": 30000
    }
  }
}

Best Practices:

• Limit concurrent connections
• Implement connection pooling
• Set appropriate timeouts
• Use circuit breakers for external services

3. Platform Abstraction

Provides a uniform interface across different execution environments.

interface PlatformAbstraction {
  // Environment detection
  getPlatform(): Platform  // 'node' | 'python' | 'deno' | 'bun'
  getVersion(): string

  // File system operations
  readFile(path: string): Promise<Buffer>
  writeFile(path: string, data: Buffer): Promise<void>

  // Process operations
  spawn(command: string, args: string[]): ChildProcess

  // Network operations
  fetch(url: string, options?: RequestInit): Promise<Response>
}

// Example: Node.js implementation
class NodePlatform implements PlatformAbstraction {
  getPlatform(): Platform {
    return 'node'
  }

  getVersion(): string {
    return process.version
  }

  async readFile(path: string): Promise<Buffer> {
    return fs.promises.readFile(path)
  }

  spawn(command: string, args: string[]): ChildProcess {
    return child_process.spawn(command, args)
  }
}

4. Error Handling & Recovery

Detects faults and implements recovery strategies.

class RuntimeErrorHandler {
  private retryConfig = {
    maxRetries: 3,
    backoffMs: 1000,
    maxBackoffMs: 30000
  }

  async executeWithRetry<T>(
    fn: () => Promise<T>,
    context: string
  ): Promise<T> {
    let lastError: Error

    for (let attempt = 0; attempt < this.retryConfig.maxRetries; attempt++) {
      try {
        return await fn()
      } catch (error) {
        lastError = error as Error

        // Log the error
        console.error(`${context} failed (attempt ${attempt + 1}):`, error)

        // Calculate backoff
        const backoff = Math.min(
          this.retryConfig.backoffMs * Math.pow(2, attempt),
          this.retryConfig.maxBackoffMs
        )

        // Wait before retry
        await new Promise(resolve => setTimeout(resolve, backoff))
      }
    }

    throw new RuntimeError(
      `${context} failed after ${this.retryConfig.maxRetries} attempts`,
      lastError
    )
  }

  async handleCriticalError(error: Error): Promise<void> {
    // Log error
    await this.logError(error)

    // Notify monitoring systems
    await this.notifyMonitoring(error)

    // Attempt graceful shutdown
    await this.gracefulShutdown()
  }
}

class RuntimeErrorHandler:
    def __init__(self):
        self.retry_config = {
            'max_retries': 3,
            'backoff_ms': 1000,
            'max_backoff_ms': 30000
        }

    async def execute_with_retry(self, fn, context: str):
        """Execute function with exponential backoff retry"""
        last_error = None

        for attempt in range(self.retry_config['max_retries']):
            try:
                return await fn()
            except Exception as error:
                last_error = error

                # Log the error
                print(f"{context} failed (attempt {attempt + 1}): {error}")

                # Calculate backoff
                backoff = min(
                    self.retry_config['backoff_ms'] * (2 ** attempt),
                    self.retry_config['max_backoff_ms']
                )

                # Wait before retry
                await asyncio.sleep(backoff / 1000)

        raise RuntimeError(
            f"{context} failed after {self.retry_config['max_retries']} attempts",
            last_error
        )

Configuration Example

Complete runtime configuration in agent manifest:

{
  "aral": {
    "version": "1.0",
    "profile": "ARAL-CORE"
  },
  "layers": {
    "runtime": {
      "platform": "node",
      "version": "20.0.0",
      "resources": {
        "cpu": {
          "limit": "2000m",
          "request": "500m"
        },
        "memory": {
          "limit": "2Gi",
          "request": "512Mi"
        },
        "storage": {
          "persistent": "/data",
          "ephemeral": "/tmp",
          "maxSize": "10Gi"
        }
      },
      "lifecycle": {
        "startupTimeout": 30000,
        "shutdownTimeout": 10000,
        "healthcheck": {
          "enabled": true,
          "interval": 10000,
          "timeout": 5000
        }
      },
      "errorHandling": {
        "maxRetries": 3,
        "backoffStrategy": "exponential",
        "circuitBreaker": {
          "enabled": true,
          "threshold": 5,
          "timeout": 60000
        }
      }
    }
  }
}

Best Practices

gauge Resource Limits

✅ DO:

• Set explicit resource limits
• Monitor resource usage
• Implement graceful degradation
• Use resource quotas in production

❌ DON’T:

• Leave resources unlimited
• Ignore memory leaks
• Skip health checks

triangle-exclamation Error Handling

✅ DO:

• Implement retry with exponential backoff
• Log all errors with context
• Use circuit breakers for external deps
• Fail fast on non-recoverable errors

❌ DON’T:

• Swallow errors silently
• Retry indefinitely
• Block on failed operations

rotate Lifecycle Management

✅ DO:

• Implement graceful shutdown
• Clean up resources on exit
• Handle SIGTERM/SIGINT signals
• Drain queues before stopping

❌ DON’T:

• Force kill processes
• Leave connections open
• Lose in-flight requests

layer-group Platform Abstraction

✅ DO:

• Use abstraction interfaces
• Test on multiple platforms
• Document platform requirements
• Handle platform-specific quirks

❌ DON’T:

• Hardcode platform assumptions
• Skip cross-platform testing
• Use platform-specific APIs directly

Security Considerations

Caution

Security Requirements: Layer 1 MUST implement security controls as defined in ARAL-SECURITY.

shield Resource Isolation

• Use OS-level isolation (containers, sandboxes)
• Implement resource quotas per agent
• Prevent resource exhaustion attacks
• Monitor for suspicious resource usage

lock Process Security

• Run with least privilege
• Drop unnecessary capabilities
• Use secure defaults
• Validate all inputs at boundaries

file-lines Audit Logging

• Log all lifecycle events
• Log resource allocation changes
• Log error conditions
• Ensure log integrity

Performance Optimization

• Use worker threads/processes for CPU-heavy tasks
• Implement job queues with priority
• Cache computation results
• Profile and optimize hot paths

• Use streaming for large data
• Implement memory pooling
• Clear caches periodically
• Monitor heap usage

• Use async I/O operations
• Batch database queries
• Implement connection pooling
• Use CDN for static assets

Monitoring & Observability

Key metrics to track:

interface RuntimeMetrics {
  // Process metrics
  uptime: number
  restartCount: number

  // Resource metrics
  cpuUsage: number       // percentage
  memoryUsage: number    // bytes
  diskUsage: number      // bytes

  // Performance metrics
  requestsPerSecond: number
  averageLatency: number
  errorRate: number

  // Health status
  isHealthy: boolean
  lastHealthCheck: Date
}

Testing

import { describe, it, expect } from 'vitest'
import { AralRuntime } from './runtime'

describe('Runtime Layer', () => {
  it('should start and stop gracefully', async () => {
    const runtime = new AralRuntime()

    await runtime.start()
    expect(runtime.getStatus()).toBe('running')

    await runtime.stop(true)
    expect(runtime.getStatus()).toBe('stopped')
  })

  it('should enforce resource limits', async () => {
    const runtime = new AralRuntime({
      resources: { memory: { limit: '100Mi' } }
    })

    await runtime.start()

    // Try to allocate more than limit
    await expect(
      runtime.allocate({ memory: '200Mi' })
    ).rejects.toThrow('Resource limit exceeded')
  })
})

import pytest
from aral.runtime import AralRuntime

@pytest.mark.asyncio
async def test_runtime_lifecycle():
    """Test runtime start and stop"""
    runtime = AralRuntime()

    await runtime.start()
    assert runtime.get_status() == 'running'

    await runtime.stop(graceful=True)
    assert runtime.get_status() == 'stopped'

@pytest.mark.asyncio
async def test_resource_limits():
    """Test resource limit enforcement"""
    runtime = AralRuntime(
        resources={'memory': {'limit': '100Mi'}}
    )

    await runtime.start()

    # Try to allocate more than limit
    with pytest.raises(ResourceLimitError):
        await runtime.allocate(memory='200Mi')

Next Steps

database Layer 2: Memory

Build on runtime with state management

code Coming Soon

See runtime implementation examples

rocket Coming Soon

Deploy runtime in production

book Specification

Read the formal requirements

---

ℹ️

Information

Layer 1 is the foundation. Get this right, and all other layers will benefit from a solid, secure, and performant base.