Extensions

A plugin system is healthy when “built in” is provenance, not a secret handshake.

1. Motivation

A central branch makes the first provider easy and the fiftieth one political:

if provider == "sqlite":
    return build_sqlite(config)
if provider == "my_provider":
    return build_my_provider(config)

Every new package now needs a host source edit and release. Inspection may import implementations, and bundled providers receive privileges an external provider cannot reproduce. HeavenBase uses one Registry-backed module protocol instead. A cohesive folder declares records in meta.yaml; a Context installs and inspects those records; typed facades resolve behavior when needed. Built-in and external items share the same descriptor, Registry, resolver, validation, lifecycle, and contract shape.

2. Separate the Extension Concepts

Concept	What it owns	Typical author
Module folder	One cohesive `meta.yaml` plus optional implementation files	Package or provider author
Registry record	One declarative identity such as an entity, backend type, handler, or profile	Module installer
Extension	A workspace entity bundle, dependencies, and optional attached API	Application/domain author
Toolkit family	A workspace-scoped set of callable tools	Agent integration author
MCP profile	Tool, entity, Skill, and serializer scope	Interface/policy author
Tag definition or claim	Open semantic metadata for inspection and candidate selection	Any module author

An Extension is one Registry record kind; it is not the Registry itself. Backends, handlers, logical types, strategies, query operations, serializers, and profiles are peer record kinds rather than fields on a giant Extension object.

3. Understand the Built-In Foundation and Roots

Catalog and MetaSchema are fixed workspace-foundation entities. No Extension can replace them. Capsule is the required Extension root. Toolkit and Prompt are packaged default roots. Agent, Memory, and Database are optional roots that applications enable deliberately. Each Extension declares exact requires identifiers; reopening a workspace recomputes the hard dependency closure from the workspace’s requested roots.

import heavenbase as hb

ws = hb.HeavenBase("extension-demo", preset="debug")
ws.enable_extension("memory")

print(ws.extensions())

Enablement is monotonic. There is no universal disable/unload operation because only an owning domain can explain how to remove its rows, data, indexes, configuration, and derived effects safely.

4. Declare a Distributable Module Folder

A minimal external entity Extension can use this layout:

acme_notes/
├── __init__.py
├── entities.py
└── meta.yaml

The entity remains ordinary public HeavenBase code:

import heavenbase as hb

class AcmeNote(hb.Entity):
    identifier = "acme-note"

    name = hb.field(hb.ShortText)

The descriptor publishes the entity and the Extension that activates it:

manifest_version: 2
coordinate: acme/notes
version: 1.0.0
bundle: acme-notes
items:
  - kind: entity
    identifier: acme-note
    source: path
    target: {module: entities, qualname: AcmeNote}
  - kind: extension
    identifier: acme-notes
    source: inline
    target: definition
    meta:
      dependencies: [entity:acme-note]
      definition:
        identifier: acme-notes
        entities: [acme-note]
        required: false
        requires: []
        setup: null
        api: null
        api_name: null

source: path targets are relative to the module folder. Keep their imports within the captured root or use stable absolute public APIs.

5. Install, Inspect, Resolve, and Enable

from pathlib import Path

import heavenbase as hb


context = hb.Context.load()
modules = context.modules()
receipt = modules.install(Path("acme_notes"))

record = modules.inspect("extension", "acme-notes")[0]
ws = hb.HeavenBase("notes", preset="debug", context=context)
ws.enable_extension("acme-notes")

Note = ws.entities["acme-note"]
note_id = ws.upsert(Note, {"name": "Registry parity"})
print(ws.get(note_id, entity=Note)["name"])

install() captures local executable files into a verified content-addressed artifact and returns an exact receipt. inspect() reads inert record data. enable_extension() resolves the Extension and its declared Entity records through the workspace’s Context before registering canonical classes. Use modules.uninstall(receipt) only when you intentionally want to remove that installed generation. Uninstalling a module does not delete application workspace data.

6. Attach a Workspace-Bound API

An Extension may attach one domain service through api and api_name. The factory receives the workspace, so the service inherits the correct Context, canonical Entity classes, and lifecycle.

class NotesAPI:
    def __init__(self, workspace):
        self.workspace = workspace

    def list(self):
        Note = self.workspace.entities["acme-note"]
        return self.workspace.query(Note).execute().rows()

In a distributable module, publish the factory as a durable heavenbase.executable target in the Extension definition. After enablement, application code uses the attached API, such as ws.notes.list(), while CLI and MCP surfaces remain thin adapters. Programmatic Extension(...).register(resolver=...) remains useful for local or generated definitions. A published package should prefer one meta.yaml so inspection, installation receipts, compatibility, and artifacts remain explicit.

7. Extend Physical Behavior Through Registered Roles

Advanced authors use hb.ext and owning packages for backend types, handlers, strategies, logical types, query operations, Toolkit families, profiles, serializers, and related Registry-backed roles. The rule is the same for every open family:

Publish one canonical record through the target Context’s resolver.
Keep implementation loading behind the typed facade.
Declare exact dependencies and compatibility.
Test built-in/external parity through install, inspect, resolve, use, and uninstall.

Do not add fixed provider scans, privileged import lists, or central planner branches. Do not treat a tag claim as executable proof.

8. Inspect Claims Without Overpromising

modules = ws.context.modules()

claim = modules.tag("backend_type", "inmem", "vector")
print(claim.value)

plan = ws.query(Note).where(Note.name == "Registry parity").explain()
print(plan["steps"])

Module tags are descriptive declarations and candidate hints. Exact handler records, compiler output, and live resource checks decide whether a concrete query runs natively, through an adapter, by portable scan, or not at all. Use explain() for that execution decision.

9. Use the Extension Checklist

Give the module, every record, and every Extension a stable identifier.
Keep one exact meta.yaml at the cohesive module root.
Declare dependencies instead of relying on import order.
Keep path targets inside the captured module root.
Attach domain behavior through one workspace API when identity or lifecycle is real.
Namespace MCP tools and scope profiles to the exact tools, entities, Skills, and serializer they need.
Test a fresh Context restore, inert inspection, activation, ordinary use, and exact-receipt uninstall.
Treat installed executable source as trusted code.

Summary

Built-in and external modules use one meta.yaml folder protocol.
Registry records are inspected before implementations are imported.
Workspace Extensions attach domain behavior through explicit roots and dependencies.

Further Exploration

Related resources:

Extension System - Build and exercise the minimal module above
Architecture - See Context and Registry ownership
Workspace - Understand extension roots and lifecycle
Backends - Inspect registered provider choices
MCP Toolkit - Define Toolkit families and profiles

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Separate the Extension Concepts

3. Understand the Built-In Foundation and Roots

4. Declare a Distributable Module Folder

5. Install, Inspect, Resolve, and Enable

6. Attach a Workspace-Bound API

7. Extend Physical Behavior Through Registered Roles

8. Inspect Claims Without Overpromising

9. Use the Extension Checklist

Summary

Further Exploration

​1. Motivation

​2. Separate the Extension Concepts

​3. Understand the Built-In Foundation and Roots

​4. Declare a Distributable Module Folder

​5. Install, Inspect, Resolve, and Enable

​6. Attach a Workspace-Bound API

​7. Extend Physical Behavior Through Registered Roles

​8. Inspect Claims Without Overpromising

​9. Use the Extension Checklist

​Summary

​Further Exploration

1. Motivation

2. Separate the Extension Concepts

3. Understand the Built-In Foundation and Roots

4. Declare a Distributable Module Folder

5. Install, Inspect, Resolve, and Enable

6. Attach a Workspace-Bound API

7. Extend Physical Behavior Through Registered Roles

8. Inspect Claims Without Overpromising

9. Use the Extension Checklist

Summary

Further Exploration