> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Extension System

> Enable built-in system/prompt extensions, register custom entity extensions, and extend backends, handlers, and storage strategies.

<Note>
  *Extensions add entity types and storage behavior without changing the workspace API.*
</Note>

<br />

## 1. What Extensions Do

HeavenBase extensions register additional entity types or developer hooks into a workspace. The workspace API stays the same: you still call `register`, `upsert`, `query`, and `get`.

Two layers matter in 0.1.1.5:

* **Entity extensions** add optional entity types through `ExtensionSpec` and `ws.enable_extension(...)`.
* **Developer extensions** register backends, handlers, storage strategies, and query ops through `hb.ext`.

<br />

## 2. Built-In System and Prompt Extensions

Every workspace enables the required `system` extension automatically during construction. You do not call `enable_extension("system")` in application code.

The `system` and default-loaded `prompt` extensions register built-in persistent entities:

| Entity id         | Role                                                      |
| ----------------- | --------------------------------------------------------- |
| `sys-catalog`     | Concrete object discovery                                 |
| `sys-metaschema`  | Workspace structure, capabilities, and enabled extensions |
| `sys-prompt`      | Callable prompt rows from `prompt`                        |
| `sys-translation` | Prompt-bound translations from `prompt`                   |
| `sys-capsule`     | Executable Capsule manifests                              |
| `sys-toolkit`     | Toolkit manifests and Capsule references                  |

Capsule and Toolkit are part of `system`; Prompt and Translation are part of the default-loaded `prompt` extension.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

ws = hb.HeavenBase("ext-demo", preset="debug")

print("system" in ws.extensions())
print("prompt" in ws.extensions())
print("sys-capsule" in ws.entities)
```

When you register a prompt in a workspace, HeavenBase ensures the `prompt` extension is enabled. Use `hb.Prompt(...).register(ws=ws)` through the root package API.

<br />

## 3. Inspect Enabled Extensions

Use `ws.extensions()` for enabled extension metadata, or query `MetaSchema` for published extension rows:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
print(list(ws.extensions()))

ext_rows = (
    ws.query(hb.MetaSchema)
    .where(hb.MetaSchema.kind == "extension")
    .select("subject_id", "name", "desc")
    .execute()
    .rows()
)

print([row["subject_id"] for row in ext_rows])
```

The `system` and `prompt` rows include `meta.entities` with their built-in entity ids.

<br />

## 4. Register a Custom Entity Extension

Package authors register entity extensions in the process registry before workspaces load them:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb
from heavenbase.ext import Extension, ExtensionSpec, register_extension


class AuditLog(hb.Entity):
    identifier = "audit-log"

    event = hb.field(hb.ShortText)
    payload = hb.field(hb.Json).default({})


register_extension(
    Extension(
        ExtensionSpec(
            identifier="audit",
            name="Audit Log",
            desc="Optional audit rows for demo extensions.",
            entities=(AuditLog,),
            tags=("audit",),
        )
    )
)

ws = hb.HeavenBase("ext-custom", preset="debug")
ws.enable_extension("audit")
ws.register(AuditLog)
ws.upsert(
    AuditLog,
    {"object_id": "a1", "name": "startup", "event": "startup", "payload": {"ok": True}},
)
```

To enable custom extensions on every new workspace, set `heavenbase.extensions.default` in config to a comma-separated list or array of extension ids.

<br />

## 5. Extend Backends and Handlers

Lower-level extension authors use `heavenbase.ext` (also `hb.ext`) to register backends, handler plugins, logical types, storage strategies, and query operations. Workspace routing picks them up through registries instead of central edits.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.ext import registered_backend_identifiers, registered_ops

print("sqlite" in registered_backend_identifiers())
print("eq" in registered_ops())
```

Discover supported combinations through the public capability index:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

hb.capabilities.logical_types()
hb.capabilities.backends(hb.Vector, hb.VectorIndex, op="near")
```

Use this surface when you ship a new storage provider or compiler, not for everyday workspace application code. See `demos/04_extension_backend_template.py` for a custom operation example.

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [Extensions](/features/extensions) - Entity and developer extension reference
  * [Architecture](/introduction/architecture) - Where extensions sit in the core path
  * [Catalog](/features/catalog) - System entities from the `system` extension
  * [Prompt](/features/utilities/prompt) - Callable prompts backed by `sys-prompt`
  * [Capsules](/features/capsules) - Executable manifests under `sys-capsule`
  * [Backends](/features/backends) - Backend families extensions can register
</Tip>

<br />