# LoopX Extension vs Built‑In Capability Boundary Rules Explained

> Understand LoopX boundary rules: Kernel, Capability, Provider, and Extension. Learn how LoopX separates core features from installable components for robust architecture.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: deep-dive
- Published: 2026-09-04

---

**LoopX enforces four strict architectural boundaries—Kernel, Capability, Provider, and Extension—to separate permanent core features from optional installable components.**

The LoopX system, developed in the `huangruiteng/loopx` repository, uses a layered architecture to maintain stability while enabling extensibility. Understanding the boundary rules between **built‑in capabilities** (shipped with the product) and **extensions** (optional provider packages) is essential for developers building on or contributing to the platform.

## The Four Architectural Boundaries

LoopX defines four distinct ownership layers that prevent extensions from interfering with core system guarantees:

| Boundary | Core Responsibility | Location in Codebase |
|----------|---------------------|----------------------|
| **Kernel** | Owns durable goal state, todos, gates, evidence, quota, recovery, and scheduling truth | `loopx/kernel/` (referenced in README.md lines 66‑69) |
| **Capability** | Defines a **stable, provider‑neutral contract** that produces one bounded, verifiable outcome from LoopX state | `loopx/capabilities/` |
| **Provider** | Calls external systems or local implementations; returns observations, effect results, and read‑back data | Implementation varies (built‑in or extension) |
| **Extension** | Packages an **optional provider** and manages lifecycle (`install`, `enable`, `upgrade`, `disable`, `rollback`) | `extensions/` or `packages/` for distribution |

These boundaries ensure that extensions **never own kernel state** or modify capability contracts—they merely deliver alternative provider implementations.

## How Built‑In Capabilities Work

Built‑in capabilities are permanent features shipped with every LoopX installation. They define three things:

- The **contract** (input/output schema)
- **Validation rules** for provider read‑backs
- A **default provider implementation**

### Locating Built‑In Capabilities

Built‑in capabilities reside under `loopx/capabilities/` and are documented in [`loopx/capabilities/README.md`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/README.md). Each capability has its own subdirectory with documentation and implementation.

```bash

# List all shipped capabilities

loopx capability list --format json

# Inspect the built-in Issue Fix capability

loopx capability show issue-fix --format json

```

The `issue-fix` capability lives at `loopx/capabilities/issue_fix/`, with detailed documentation in [`loopx/capabilities/issue_fix/README.md`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/issue_fix/README.md). This exemplifies how built‑in capabilities are **always available** without any extension installation.

## How Extensions Extend (Without Overriding)

Extensions enter the architecture only when a capability needs a **non‑default provider**. An extension:

- Packages provider code in `extensions/<provider-name>/`
- Registers runtime lifecycle hooks
- Remains **stateless** with respect to the kernel

### Extension Installation and Activation Workflow

```bash

# Install an optional provider for the "explore" capability

loopx extension install explore-openai-provider

# Enable the new provider

loopx extension enable explore-openai-provider

# Run explore capability (now using the extension's provider)

loopx capability show explore --format json

```

The `explore-openai-provider` extension does **not** modify `loopx/capabilities/explore/` or any kernel files. As documented in [`extensions/explore-openai-provider/README.md`](https://github.com/huangruiteng/loopx/blob/main/extensions/explore-openai-provider/README.md), it only supplies an alternative provider implementation.

## Registering a Custom Provider via Extension

Developers can create custom providers using the extension registration API. The capability contract remains unchanged—the extension merely adds a new provider to the registry.

```python
from loopx.extensions import register_provider

@register_provider('my_custom_provider')
def fetch_data(state):
    # External API call or local computation

    return {"result": "ok", "observations": [...]}

```

After registration, the capability can select this provider at runtime:

```bash
loopx capability run my-capability --provider my_custom_provider

```

The `register_provider` decorator adds the function to the extension registry without altering the capability definition or kernel state.

## Comparison: Built‑In vs Extension Boundaries

| Aspect | Built‑In Capability | Extension |
|--------|---------------------|-----------|
| **Permanence** | Shipped with LoopX; cannot be uninstalled | Optional; can be installed, disabled, or removed |
| **State ownership** | May interact with kernel state | **Never** owns kernel state |
| **Contract control** | Defines and owns the capability contract | Must conform to existing contract |
| **Lifecycle** | Fixed with product release | Managed via `install`, `enable`, `disable`, `rollback` |
| **Code location** | `loopx/capabilities/` | `extensions/` or external packages |

## Critical Boundary Enforcement Rules

According to the LoopX source code, these rules are architecturally enforced:

1. **Extensions are not control‑plane owners** — They deliver providers; they do not manage kernel scheduling or goal state.
2. **Capability contracts are provider‑neutral** — The same capability can run with built‑in or extension providers without code changes.
3. **Provider read‑backs are validated by the capability** — The capability layer, not the extension, validates that provider results satisfy the contract.
4. **Extension lifecycle hooks are runtime‑only** — Installation and enablement do not modify capability definitions or kernel data structures.

## Key Files for Understanding Boundaries

| File Path | Purpose |
|-----------|---------|
| [`README.md`](https://github.com/huangruiteng/loopx/blob/main/README.md) (lines 66‑73, *Capability surface* section) | High‑level overview of four boundaries and their interactions |
| [`loopx/capabilities/README.md`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/README.md) | Index of all shipped built‑in capabilities |
| [`docs/reference/extensions.md`](https://github.com/huangruiteng/loopx/blob/main/docs/reference/extensions.md) | Extension lifecycle specification and plugin architecture |
| [`loopx/capabilities/issue_fix/README.md`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/issue_fix/README.md) | Concrete example of built‑in capability structure |
| `extensions/<provider-name>/README.md` | Example: optional provider packaged as extension |

## Summary

- LoopX **kernel** owns all durable state—extensions can never modify it directly.
- **Built‑in capabilities** are permanent, provider‑neutral contracts in `loopx/capabilities/`.
- **Extensions** only package optional providers and manage their lifecycle—no capability or kernel ownership.
- The `register_provider` decorator (from `loopx.extensions`) is the sanctioned extension point for adding providers.
- Consult [`docs/reference/extensions.md`](https://github.com/huangruiteng/loopx/blob/main/docs/reference/extensions.md) and the README's *Capability surface* section for authoritative boundary specifications.

## Frequently Asked Questions

### Can an extension modify a built‑in capability's contract?

No. Extensions strictly implement existing capability contracts. The contract—input schema, validation rules, and output guarantees—is owned by the capability layer and cannot be altered by extensions. An extension that needs different contract semantics must target a different capability or propose changes to the core repository.

### What happens if I disable an extension that is currently active?

The capability falls back to its default provider or fails gracefully with a provider‑unavailable error. Because extensions do not own kernel state, disabling one cannot corrupt goals, todos, or scheduling data. The extension lifecycle is documented in [`docs/reference/extensions.md`](https://github.com/huangruiteng/loopx/blob/main/docs/reference/extensions.md).

### How do I know whether a capability is built‑in or requires an extension?

Run `loopx capability list --format json`. Built‑in capabilities show `source: "core"`; extension‑provided capabilities indicate their source extension. The capability catalog at [`loopx/capabilities/README.md`](https://github.com/huangruiteng/loopx/blob/main/loopx/capabilities/README.md) also documents all shipped capabilities.

### Can I use multiple providers for the same capability simultaneously?

Yes. The capability contract permits runtime provider selection via `--provider` flags or configuration. You can enable multiple provider extensions and switch between them per invocation without reinstalling or reconfiguring the capability itself.