aiel-runtime 0.5.3

AIEL Runtime adapter used by the Execution Plane to load and execute user projects.

AIEL Runtime — Governed Execution Runtime for AI Workloads

aiel-runtime is the execution runtime used by the AIEL Execution Plane to load, validate, and execute customer AI workloads from immutable deployment snapshots.

It is the runtime boundary between:

• customer-defined execution contracts
• platform-governed execution infrastructure

The runtime is intentionally focused on:

• deterministic execution
• snapshot loading
• contract validation
• export invocation
• runtime normalization
• execution isolation compatibility
• observability integration

Developer-facing ergonomics belong to aiel-sdk.

Deployment and operational workflows belong to aiel-cli.

aiel-runtime exists to execute workloads consistently and safely inside the Execution Plane.

---

Why the Runtime Exists

Most AI orchestration frameworks stop at workflow composition.

Production systems require significantly more:

• deterministic execution
• version-aware runtime loading
• immutable deployment artifacts
• governed integration access
• execution traceability
• runtime isolation
• execution contracts
• timeout enforcement
• normalized invocation protocols
• reproducible runtime environments

The Execution Plane requires a stable runtime adapter capable of loading customer workloads from immutable snapshots and executing them under platform governance.

aiel-runtime is that execution adapter.

---

Position in the Platform

The AI Execution Layer is composed of multiple coordinated systems.

Component	Responsibility
aiel-sdk	Defines executable contracts locally
aiel-cli	Packages and deploys snapshots
aiel-runtime	Loads and executes snapshots
Control Plane	Governs releases, workspaces, policies, and promotion
Data Plane	Stores snapshots, traces, memory, manifests, and rollout state
Execution Plane	Orchestrates governed runtime execution

The runtime is the execution boundary of the platform.

It does not decide:

• release eligibility
• rollout policy
• promotion logic
• deployment governance

Those responsibilities belong to the Control Plane.

The runtime focuses exclusively on execution behavior.

---

Runtime Responsibilities

The runtime is responsible for:

• loading immutable snapshots
• importing entry_point.py
• hydrating the SDK registry
• validating export contracts
• invoking tools, agents, flows, routers, HTTP handlers, and MCP metadata
• normalizing execution responses
• collecting execution metadata
• supporting timeout enforcement
• supporting runtime isolation boundaries
• returning deterministic execution envelopes

The runtime is intentionally narrow in scope.

It is not:

• a deployment system
• a package manager
• a CI platform
• an orchestration authoring framework
• a sandbox implementation
• a policy engine

Those concerns belong to surrounding platform layers.

---

Execution Model

The runtime executes workloads from immutable deployment snapshots.

A snapshot is a versioned filesystem artifact containing:

• entry_point.py
• local modules
• workflow code
• dependency metadata
• runtime manifest metadata

The runtime imports entry_point.py.

Decorators from aiel-sdk register executable exports into the in-memory registry.

The runtime then validates and invokes those exports through a normalized execution protocol.

---

Architecture Flow

┌─────────────────────────────┐
│ Developer Code              │
│ entry_point.py              │
└────────────┬────────────────┘
             │
             │ aiel push
             ▼
┌─────────────────────────────┐
│ Immutable Snapshot          │
│ (versioned artifact)        │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ Execution Plane             │
├─────────────────────────────┤
│ Snapshot Download           │
│ Runtime Provisioning        │
│ Runtime Isolation           │
│ Policy Enforcement          │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ aiel-runtime                │
├─────────────────────────────┤
│ Load snapshot               │
│ Import entry_point.py       │
│ Hydrate registry            │
│ Validate contracts          │
│ Resolve invocation          │
│ Execute export              │
│ Collect logs + traces       │
│ Normalize response          │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│ Structured Runtime Response │
└─────────────────────────────┘

---

Runtime Lifecycle

The runtime follows a deterministic execution lifecycle.

1. Request Intake

The runtime receives a JSON request through:

• stdin
• CLI arguments
• Execution Plane orchestration

The request is parsed into a normalized internal protocol structure.

---

2. Snapshot Resolution

The runtime resolves the snapshot root from:

EP_FILES_ROOT

Example:

export EP_FILES_ROOT=/tmp/ep/snapshots/<tenant>/<project>/<release>/files

The snapshot must contain:

entry_point.py

---

3. Registry Reset

The runtime resets the SDK registry before loading the snapshot.

This prevents registry leakage across warm process reuse.

---

4. Snapshot Import

The runtime:

• adds the snapshot root to sys.path
• imports entry_point.py
• allows decorators to register exports

---

5. Contract Validation

The runtime validates:

• export signatures
• registry consistency
• supported export shapes
• invocation compatibility

Validation is delegated to aiel-sdk.

---

6. Context Hydration

The runtime builds a normalized execution context.

The context may contain:

• request ID
• trace ID
• tenant ID
• workspace ID
• project ID
• user ID
• runtime version
• SDK version
• snapshot ID
• deadline metadata

The runtime also exposes:

• structured logging
• remaining time helpers
• execution metadata

---

7. Invocation

The runtime dispatches execution based on:

• action
• kind
• handler name
• protocol payload

Supported execution actions:

• describe
• invoke
• execute

---

8. Timeout Enforcement

Async functions are awaited with timeout enforcement.

Sync functions are executed through controlled worker execution paths to support timeout handling.

---

9. Response Normalization

All runtime responses are normalized into a stable envelope.

Responses include:

• success status
• HTTP status
• result payload
• error metadata
• execution metadata
• timing information
• trace information
• runtime logs

---

Snapshot Model

The runtime is snapshot-first.

Snapshots are immutable deployment artifacts controlled by the platform.

Typical snapshot layout:

files/
  entry_point.py
  tools/
    core.py
  agents/
    main.py
  flows/
    onboarding.py
  mcp_server/
    core.py
  requirements.txt

The runtime does not install dependencies dynamically.

Runtime environments must be pre-baked and curated by the platform.

This avoids:

• dependency drift
• runtime mutation
• unpredictable cold starts
• unreviewed dependency execution

---

Snapshot Identification

The runtime computes a deterministic snapshot identifier using:

• file paths
• file contents
• snapshot hashing

Ignored paths typically include:

• .git/
• .venv/
• __pycache__/

Snapshot identifiers support:

• runtime cache keys
• rollout correlation
• deployment traceability
• version-aware execution
• reproducibility

---

Runtime Protocol

The runtime exposes a normalized stdin → stdout protocol.

This allows:

• subprocess execution
• container execution
• platform orchestration
• language-neutral invocation
• deterministic response parsing

---

Describe Action

The describe action returns the registry execution surface.

Request

{
  "schema_version": "v1",
  "action": "describe"
}

Response

{
  "schema_version": "v1",
  "ok": true,
  "result": {
    "sdk_version": "X.Y.Z",
    "runtime_version": "X.Y.Z",
    "tools": ["normalize_email"],
    "agents": ["collect_personal_data"],
    "flows": ["driver_onboarding"],
    "routers": ["route_driver_flow"],
    "http_handlers": [
      {
        "method": "POST",
        "path": "/driver/onboard"
      }
    ],
    "mcp_servers": [
      {
        "name": "driver_support",
        "tools": ["lookup_existing_driver"]
      }
    ]
  }
}

The describe action is used by the Execution Plane for:

• capability discovery
• runtime introspection
• deployment validation
• MCP metadata exposure
• execution routing

---

Invoke Action

The invoke action executes a registered export.

Request

{
  "schema_version": "v1",
  "action": "invoke",
  "kind": "tool",
  "name": "normalize_email",
  "payload": {
    "email": "[e-mail]",
    "ctx": {
      "request_id": "req_123",
      "workspace_id": "w_1",
      "project_id": "p_1"
    }
  }
}

Response

{
  "schema_version": "v1",
  "ok": true,
  "result": {
    "email": "[e-mail]"
  }
}

---

Execute Action

The execute action bypasses the SDK registry and invokes a Python handler directly.

This model is similar to AWS Lambda-style invocation.

Example handler:

def aiel_handler(event, context):
    return {"ok": True}

Example request:

{
  "schema_version": "v1",
  "action": "execute",
  "handler": "entry_point.aiel_handler",
  "event": {}
}

This execution model is useful for:

• lightweight runtime handlers
• compatibility scenarios
• custom execution entrypoints
• direct runtime invocation

---

Supported Export Types

Export Type	Runtime Behavior
Tool	Executes callable action
Agent	Executes stateful orchestration step
Flow	Executes workflow entry point
Router	Executes routing decision
HTTP Handler	Exposed through platform-managed HTTP routing
MCP Metadata	Exposed through platform-managed MCP surfaces

The Execution Plane is responsible for mapping:

• HTTP requests
• MCP requests
• external triggers

into runtime invocation payloads.

---

Runtime Context

Exports receive a normalized runtime context.

The context provides:

• execution metadata
• structured logging
• trace metadata
• timing helpers
• workspace/project identity

Example:

@tool("normalize_email")
def normalize_email(ctx, payload):
    ctx.log("normalize_email.completed")
    return {"email": payload["email"].lower()}

Available fields may include:

• ctx.request_id
• ctx.trace_id
• ctx.workspace_id
• ctx.project_id
• ctx.snapshot_id
• ctx.runtime_version
• ctx.sdk_version

---

Structured Logging

Runtime logs are emitted through:

ctx.log(...)

Example:

ctx.log(
    "normalize_email.completed",
    level="INFO",
    email="[e-mail]",
)

Structured logs are attached to the runtime response envelope and may later be persisted by platform telemetry systems.

---

Runtime Response Envelope

All runtime responses follow a normalized structure.

Example:

{
  "schema_version": "v1",
  "ok": true,
  "http_status": 200,
  "result": {},
  "error": null,
  "meta": {
    "request_id": "uuid",
    "trace_id": "trace_123",
    "duration_ms": 12,
    "snapshot_id": "sha256...",
    "runtime_version": "x.y.z",
    "sdk_version": "x.y.z",
    "logs": []
  }
}

The normalized response model simplifies:

• orchestration
• telemetry
• retries
• debugging
• execution replay
• rollout analysis

---

Error Model

Errors are normalized into a stable taxonomy.

Example:

{
  "schema_version": "v1",
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Tool not found: normalize_email"
  }
}

Supported error categories may include:

Error Code	Purpose
VALIDATION_ERROR	Invalid request or contract
NOT_FOUND	Missing export or handler
SECURITY_VIOLATION	Restricted operation detected
TIMEOUT	Execution exceeded deadline
USER_CODE_ERROR	Exception thrown by customer code
INTERNAL	Runtime or snapshot failure

This stable error taxonomy allows the Execution Plane to reason about runtime outcomes consistently.

---

Runtime Isolation Model

The runtime assumes that hard isolation boundaries are enforced by the Execution Plane.

Typical platform responsibilities include:

• process isolation
• container isolation
• read-only snapshots
• CPU limits
• memory limits
• timeout enforcement
• network restrictions
• secret injection
• tenant separation

The runtime performs defense-in-depth checks where practical.

Hard security boundaries belong to the platform infrastructure layer.

---

Import Policy Enforcement

The runtime may perform static import inspection before execution.

This is intended as defense-in-depth validation.

Restricted import roots may include:

• subprocess
• ctypes
• low-level system access modules

Import policies may depend on runtime capabilities.

Example capabilities:

{
  "network": false,
  "subprocess": false,
  "ctypes": false
}

The platform should remain the primary enforcement boundary.

---

Runtime Bundles

The Execution Plane may expose curated runtime bundles.

---

Minimal Runtime

aiel-runtime==X.Y.Z
aiel-sdk==X.Y.Z

Used for:

• core workflows
• tools
• routers
• HTTP handlers

---

AI Runtime

aiel-runtime[ai]==X.Y.Z

May include curated AI dependencies:

• LangGraph
• LangChain Core
• LangSmith

The platform should pin and allowlist runtime bundles.

---

Version Compatibility

The runtime and SDK are designed for lockstep compatibility.

Recommended policy:

aiel-runtime==X.Y.Z
aiel-sdk==X.Y.Z

The Data Plane manifest should include:

• runtime identifier
• SDK version
• snapshot hashes

This supports:

• deterministic execution
• cache stability
• reproducibility
• rollback safety

---

Runtime Entrypoint

The Execution Plane invokes:

python -m aiel_runtime.runner

The runtime may receive:

• stdin protocol requests
• CLI arguments
• environment metadata

---

Local Development

The runtime can be executed locally for:

• snapshot validation
• protocol testing
• export inspection
• smoke testing

---

Install Runtime

python -m pip install -U pip
python -m pip install -e .

Optional AI bundle:

python -m pip install "aiel-runtime[ai]"

---

Describe Exports

aiel-runtime --files-root "$PWD" --action describe --pretty

Or:

echo '{"schema_version":"v1","action":"describe"}' | \
aiel-runtime --files-root "$PWD" --pretty

---

Invoke a Tool

aiel-runtime \
  --files-root "$PWD" \
  --action invoke \
  --kind tool \
  --handler normalize_email \
  --event '{"email":"[e-mail]"}' \
  --pretty

---

Execute a Handler

aiel-runtime \
  --files-root "$PWD" \
  --action execute \
  --handler entry_point.aiel_handler \
  --event '{"hello":"world"}' \
  --pretty

---

Environment Variables

Variable	Purpose
EP_FILES_ROOT	Snapshot root
AIEL_PRETTY_JSON	Pretty-print runtime responses
AIEL_AUTO_CTX	Auto-discover local context

---

Recommended Snapshot Structure

my-project/
├── entry_point.py
├── tools/
│   └── core.py
├── agents/
│   └── onboarding.py
├── flows/
│   └── driver_flow.py
├── mcp_server/
│   └── support.py
└── requirements.txt

The runtime requires:

entry_point.py

All executable exports should be registered during import time.

---

Operational Guarantees

When used inside the AIEL Execution Plane, the runtime supports:

• deterministic execution
• immutable deployment loading
• normalized invocation behavior
• contract validation
• structured runtime telemetry
• timeout-aware execution
• stable response envelopes
• export introspection
• runtime reproducibility
• governed execution integration

---

Troubleshooting

entry_point.py Not Found

The snapshot root must contain:

entry_point.py

Fix:

aiel-runtime --files-root /path/to/project

---

Missing SDK

Example:

ModuleNotFoundError: aiel_sdk

Fix:

python -m pip install aiel-sdk

Prefer installing through the runtime package:

python -m pip install aiel-runtime

---

Missing Optional AI Dependencies

Example:

ImportError: aiel_core.langgraph is not available

Fix:

python -m pip install "aiel-runtime[ai]"

Or install required dependencies explicitly.

---

Registry Leakage

The runtime resets the registry before snapshot loading.

The Execution Plane should avoid reusing the same process across unrelated tenants or projects unless explicitly designed for isolation reuse.

---

Contract Validation Failure

Typical causes:

• invalid export signatures
• unsupported return shapes
• decorator misuse
• registry inconsistencies

Validate locally:

aiel-runtime --files-root "$PWD" --action describe

---

Timeout Failures

Example:

{
  "ok": false,
  "error": {
    "code": "TIMEOUT"
  }
}

Potential causes:

• long-running synchronous execution
• blocked I/O
• unbounded loops
• network waits

The platform should enforce appropriate timeout policies.

---

Relationship to the SDK

The SDK defines executable contracts.

The runtime executes those contracts.

Typical flow:

Developer Code
    ↓
aiel-sdk decorators
    ↓
Registry exports
    ↓
aiel-cli packages snapshot
    ↓
Execution Plane loads snapshot
    ↓
aiel-runtime imports entry_point.py
    ↓
Runtime executes exports

---

Relationship to the Execution Plane

The runtime is intentionally designed to be orchestrated by the Execution Plane.

The Execution Plane provides:

• isolation
• governance
• rollout orchestration
• deployment control
• policy enforcement
• observability infrastructure
• snapshot distribution
• runtime provisioning

The runtime provides:

• deterministic execution
• export loading
• invocation handling
• response normalization
• execution telemetry

---

Testing

Recommended runtime validation tests:

• snapshot load succeeds
• describe returns exports
• tool invocation succeeds
• flow invocation succeeds
• contract violations fail predictably
• registry resets correctly
• timeout handling works
• error normalization remains stable

Example:

python -m pip install pytest
pytest -q

---

Summary

aiel-runtime is the governed execution runtime of the AI Execution Layer.

It loads immutable snapshots, hydrates execution contracts, validates exports, invokes workloads, and normalizes execution behavior for the Execution Plane.

The runtime is intentionally narrow in scope:

• deterministic
• version-aware
• contract-driven
• execution-focused

The platform surrounding the runtime provides governance, orchestration, rollout control, and operational infrastructure required for production AI systems.