# `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 delete(self, resource_id: str, context: ...) -> None: ...
    async def list_children(self, resource_id: str, context: ...) -> list[str]: ...
    async def diff(self, resource_id: str, other_id: str, context: ...) -> str: ...
    async def checkpoint(self, resource_id: str) -> str: ...
    async def rollback(self, resource_id: str, checkpoint_id: str) -> None: ...
    async def create_sandbox(self, resource_id: str) -> "Sandbox": ...
```

---

## `DatabaseResourceHandler`

Full CRUD and checkpoint/rollback for SQLite and remote databases.

| Method | SQLite | PostgreSQL / MySQL / DuckDB |
|--------|--------|-----------------------------|
| `read()` | Queries `sqlite_master` for schema | Not supported (returns graceful failure) |
| `write(sql)` | Executes SQL statement | Not supported |
| `delete()` | `DROP TABLE IF EXISTS` | Not supported |
| `list_children()` | Lists tables and views | Not supported |
| `diff()` | Content-hash schema comparison | Not supported |
| `create_checkpoint()` | `SAVEPOINT <name>` | Not supported |
| `rollback_to()` | `ROLLBACK TO SAVEPOINT <name>` | Not supported |

Remote database operations return a structured not-supported result rather than raising.

```python
from cleveragents.resource.handlers import DatabaseResourceHandler

handler = DatabaseResourceHandler()
checkpoint_id = await handler.checkpoint("my-db")
await handler.rollback("my-db", checkpoint_id)
```

---

## `DevcontainerHandler`

Full protocol implementation for `container.devcontainer` resources.

| Method | Implementation |
|--------|----------------|
| `delete()` | `devcontainer exec rm -rf <path>` |
| `list_children()` | `devcontainer exec ls -1 <path>` |
| `diff()` | Content-hash comparison of resource state |
| `create_sandbox()` | Delegates to `BaseResourceHandler` with lazy activation |

All methods return graceful failure results for missing or stopped containers
rather than raising exceptions.

```python
from cleveragents.resource.handlers import DevcontainerHandler

handler = DevcontainerHandler()
children = await handler.list_children("my-devcontainer:/workspace")
```