# `cleveragents.resource` — Resource System

The `resource` package provides the resource type schema, handler
infrastructure, and the type-inheritance resolution system.  Resources
are the managed external entities (files, databases, containers, LSP
servers, cloud services) that plans read from and write to.

See [ADR-008](../adr/ADR-008-resource-system.md),
[ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md), and
[ADR-042](../adr/ADR-042-resource-type-inheritance.md) for design rationale.

---

## Type Inheritance

### `resolve_inheritance_chain(type_name, registry) → list[str]`

Returns the full inheritance chain for a resource type, from the type
itself up to the root.  Raises `ResourceTypeCircularInheritanceError` if
a cycle is detected, or `ResourceTypeInheritanceDepthError` if the chain
exceeds `MAX_CHAIN_DEPTH` (default: 16).

```python
from cleveragents.resource import resolve_inheritance_chain

chain = resolve_inheritance_chain("container.docker", registry)
# → ["container.docker", "container", "resource"]
```

### `resolve_fields(type_name, registry) → dict[str, Any]`

Merges field definitions from the full inheritance chain, with child
fields overriding parent fields.

### `is_subtype_of(child, parent, registry) → bool`

Returns `True` if `child` is a subtype of `parent`.

```python
from cleveragents.resource import is_subtype_of

is_subtype_of("container.docker", "container", registry)  # True
```

### `find_subtypes(parent, registry) → list[str]`

Returns all registered types that are subtypes of `parent`.

### `validate_chain(chain) → None`

Validates a pre-computed inheritance chain for cycles and depth.

### `TypeRegistryMap`

Type alias: `dict[str, ResourceTypeDefinition]`.  The registry maps type
names to their definitions.

---

## Inheritance Errors

| Exception | Description |
|-----------|-------------|
| `ResourceTypeCircularInheritanceError` | Cycle detected in type hierarchy |
| `ResourceTypeInheritanceDepthError` | Chain exceeds `MAX_CHAIN_DEPTH` |
| `ResourceTypeParentNotFoundError` | Parent type not registered |
| `ResourceTypeParentRemovalError` | Attempt to remove a type that has children |

---

## Constants

| Constant | Value | Description |
|----------|-------|-------------|
| `MAX_CHAIN_DEPTH` | `16` | Maximum inheritance chain depth |

---

## Resource Handlers

Resource handlers live in `cleveragents.resource.handlers` and implement
CRUD, checkpoint, and rollback operations for specific resource types.
Built-in handlers include:

| Handler | Resource Types |
|---------|---------------|
| Database handler | `sqlite`, `postgresql`, `mysql`, `duckdb` |
| Container handler | `container.docker`, `container.podman` |
| LSP handler | `lsp.*` |
| File handler | `file`, `directory` |
| Cloud handler | `cloud.*` |

Each handler implements the `ResourceHandler` protocol:

```python
class ResourceHandler(Protocol):
    async def read(self, resource_id: str, context: ...) -> Any: ...
    async def write(self, resource_id: str, data: Any, context: ...) -> None: ...
    async def checkpoint(self, resource_id: str) -> str: ...
    async def rollback(self, resource_id: str, checkpoint_id: str) -> None: ...
```