# Magic Runtime - AI Context File
# https://magic.threadsync.io/llms.txt
# Version: 2.0.0
# Last Updated: 2026-02-10

## WHAT IS MAGIC

Magic is a sandboxed controller runtime for Python. It executes business logic as isolated, contract-bound controllers with capability-based security.

Key concept: Controllers are plugins, not code changes. They declare inputs, outputs, and capabilities. The runtime enforces these contracts at boundaries.

## WHEN TO USE MAGIC

Use Magic when:
- You need to run AI-generated business logic safely
- You want hot-deployable plugins without restarts
- You need audit logging of all capability usage
- You want contract validation at request/response boundaries
- You need isolated execution with resource limits

Do NOT use Magic when:
- You need a traditional web framework (use FastAPI/Django)
- You're building a simple CRUD app
- You don't need isolation or contract enforcement

## ARCHITECTURE

```
Request → Nginx (TLS) → Magic Runtime → Controller (sandboxed) → Response
                              ↓
                     [PostgreSQL, Redis, External APIs]
                              ↓
                     [Prometheus Metrics, Structured Logs]
```

Controllers run in sandboxed environments with:
- CPU/memory limits
- Network egress allowlists
- Filesystem restrictions
- Timeout enforcement

## CONTROLLER CONTRACT SCHEMA

Every controller must have a contract file (YAML or JSON):

```yaml
name: string                    # Controller identifier
version: string                 # Semantic version

input:                          # JSON Schema for request validation
  type: object
  required: [field1, field2]
  properties:
    field1: { type: string }

output:                         # JSON Schema for response validation
  type: object
  required: [result]
  properties:
    result: { type: string }

capabilities:                   # Required capabilities (default: none)
  - db:read                     # Read from database
  - db:write                    # Write to database
  - http:egress:                # Outbound HTTP
      allow:
        - api.example.com
  - secrets:read:               # Access secrets
      keys: [API_KEY]
  - queue:publish               # Publish to message queue
  - cache:read                  # Read from cache
  - cache:write                 # Write to cache
  - fs:temp                     # Temporary filesystem access

resources:                      # Resource limits
  cpu: 0.5                      # CPU cores (0.1 to 2.0)
  memory: 256Mi                 # Memory limit
  timeout: 30s                  # Execution timeout

observability:                  # Observability requirements
  log_fields: [field1]          # Fields to include in logs
  metrics:                      # Custom metrics to emit
    - controller_duration_seconds
```

## CONTROLLER IMPLEMENTATION

Controllers are Python classes or functions:

```python
from magic import Controller, contract

@contract("./invoice_sync.contract.yaml")
class InvoiceSyncController(Controller):

    async def execute(self, input: dict) -> dict:
        # Input is already validated against contract schema
        customer_id = input["customer_id"]

        # Structured DB API (requires db:read capability)
        # Use self.db.query_one / self.db.query — NOT raw SQL
        customer = await self.db.query_one(
            "customers", where={"id": customer_id}
        )

        # Outbound HTTP only works if declared in capabilities
        stripe_key = await self.secrets.get("STRIPE_KEY")
        response = await self.http.post(
            "https://api.stripe.com/v1/invoices",
            json=input["invoice_data"],
            headers={"Authorization": f"Bearer {stripe_key}"}
        )

        # Return must match output schema
        return {
            "sync_id": response["id"],
            "status": "completed"
        }
```

> **Important:** Use the structured DB API by default (`self.db.query()`, `self.db.query_one()`,
> `self.db.insert()`, `self.db.update()`). Raw SQL is only available via the `db:rawsql`
> escape hatch capability, which is denied by default in production policy.
> See /security.html for details.

## CAPABILITY REFERENCE

| Capability | Description | Audit Fields |
|------------|-------------|--------------|
| db:read | Structured read (self.db.query, self.db.query_one) | table, query_hash |
| db:write | Structured write (self.db.insert, self.db.update, self.db.delete) | table, operation, row_count |
| db:rawsql | Raw SQL escape hatch (denied by default in prod policy) | query_text, query_hash |
| http:egress | Outbound HTTP | host, method, status |
| secrets:read | Access secrets by key | key_name |
| queue:publish | Publish messages | queue_name, message_count |
| queue:subscribe | Consume messages | queue_name |
| cache:read | Read from cache | key_pattern |
| cache:write | Write to cache | key, ttl |
| fs:temp | Temp file operations | operation, path_hash |

All capability usage is logged with X-Request-ID correlation.

## ERROR CATALOG

Magic uses structured errors with E-codes organized by category:

```json
{
  "error": {
    "code": "E1003",
    "category": "CONTRACT",
    "message": "Input validation failed",
    "details": {
      "field": "customer_id",
      "constraint": "format",
      "expected": "uuid"
    },
    "request_id": "req_abc123"
  }
}
```

| Code Range | Category | HTTP Status | Meaning |
|------------|----------|-------------|---------|
| E1001-E1005 | CONTRACT | 400 | Contract/schema validation failures |
| E2001-E2005 | CAPABILITY | 403 | Capability violations (undeclared, denied by policy) |
| E3001-E3005 | EXECUTION | 500/429 | Runtime failures (timeout, OOM, unhandled exception) |
| E4001-E4005 | DEPLOYMENT | 400/500 | Deploy and lifecycle failures |
| E5001-E5005 | AUTH | 401/403 | Authentication and authorization |

Full error catalog with resolutions: /errors.html

## CLI COMMANDS

Magic CLI can run in two modes:

### Container mode (production / evaluation — v2.0+)
Prefix all commands with `docker compose exec runtime`:

```bash
# Create new controller
docker compose exec runtime magic new controller InvoiceSync

# Validate controller contract
docker compose exec runtime magic validate ./controllers/invoice_sync/

# Run controller
docker compose exec runtime magic run InvoiceSync --input '{"customer_id": "..."}'

# Deploy controller to runtime
docker compose exec runtime magic deploy ./controllers/invoice_sync/

# List deployed controllers
docker compose exec runtime magic list

# View controller logs
docker compose exec runtime magic logs InvoiceSync --follow

# Rollback controller
docker compose exec runtime magic rollback InvoiceSync --to v1.0.0
```

### Host mode (development — v2.1+ via pipx)
If installed locally via `pipx install magic-runtime`:

```bash
# Create new controller
magic new controller InvoiceSync

# Validate controller contract
magic validate ./controllers/invoice_sync/

# Run controller locally
magic run InvoiceSync --input '{"customer_id": "..."}'

# Deploy controller to runtime
magic deploy ./controllers/invoice_sync/

# List deployed controllers
magic list

# View controller logs
magic logs InvoiceSync --follow

# Rollback controller
magic rollback InvoiceSync --to v1.0.0
```

## CONVENTIONS

1. Controller names: PascalCase (InvoiceSync, CustomerOnboard)
2. Contract files: controller_name.contract.yaml
3. One controller per directory
4. All inputs/outputs must be JSON-serializable
5. No global state - controllers are stateless
6. Use dependency injection for services

## DOCUMENTATION

For deeper context, see:
- /contracts.html - Complete contract specification
- /security.html - Security model and hardening guide
- /errors.html - Full error catalog with codes and resolutions
- /quick-start.html - Quick start tutorial
- /user-guide.html - User guide and operations
- /kubernetes.html - Kubernetes deployment status and roadmap

## GENERATING CONTROLLERS WITH AI

When generating a Magic controller:

1. Start with the contract (input/output schemas, capabilities)
2. Validate the contract is complete and minimal
3. Implement the controller class
4. Only use declared capabilities
5. Return data matching output schema
6. Handle errors with structured exceptions

Example prompt pattern:
"Generate a Magic controller that [description]. It needs to [capabilities]. Input is [schema]. Output is [schema]."

## LINKS

- Homepage: https://magic.threadsync.io
- Contracts: https://magic.threadsync.io/contracts.html
- Security: https://magic.threadsync.io/security.html
- Errors: https://magic.threadsync.io/errors.html
- Deploy: https://magic.threadsync.io/deploy-center.html
- Quick Start: https://magic.threadsync.io/quick-start.html
- User Guide: https://magic.threadsync.io/user-guide.html
- Frontend Integration: https://magic.threadsync.io/frontend-integration.html
- Kubernetes: https://magic.threadsync.io/kubernetes.html
- Releases: https://magic.threadsync.io/releases.html
- ThreadSync: https://www.threadsync.io