Architecture

A workspace is not a database; it is the air-traffic controller that refuses to become an airplane.

1. Motivation

A data application often grows one global registry for providers, another for plugins, and a third set of imports that quietly decides which built-ins exist. That makes inspection import code, makes external packages second-class, and lets two workspaces accidentally share machine state. HeavenBase 0.1.2.2 uses one standard-library Registry kernel, one Context owner, and one module-folder protocol. Built-in and external records follow the same install, inspect, resolve, validation, and lifecycle path. The workspace then coordinates only the schemas, backends, routing, rows, and tools that belong to that application boundary. This matters because extension provenance should answer “where did this record come from?”, not “which privileged branch executes it?”

2. Keep the Public Mental Model Small

Most applications need one import, one workspace, and explicit exits from query results:

import heavenbase as hb


class Product(hb.Entity):
    name = hb.field(hb.ShortText)
    price = hb.field(hb.Float)


ws = hb.HeavenBase("shop", preset="debug")
ws.register(Product)
ws.upsert(Product, {"name": "Oak desk", "price": 129.0})

rows = (
    ws.query(Product)
    .where(Product.price < 150)
    .select("name", "price")
    .execute()
    .rows()
)

HeavenBase(...) creates an absent durable workspace or compatibly reopens it. register() establishes schema; row CRUD never creates schema as a side effect. Query transforms return new immutable values, execute() recomputes, and rows() explicitly crosses the ResultFrame transport boundary.

3. See the Three Ownership Boundaries

Context owns machine configuration, the Registry store, module resolution, and live workspace identity.
ModuleService owns declarative records, exact meta.yaml discovery, verified local artifacts, inspection, resolution, and lifecycle.
Workspace owns application schemas, backend instances, placement, query routing, rows, fixed metadata entities, enabled extensions, and agent-facing tools.

hb.DEFAULT_CONTEXT is a convenience for unbound calls. An explicitly constructed Context remains the authority for every nested lookup in its workspaces.

4. Understand the Workspace Foundation

Catalog and MetaSchema are fixed workspace-foundation entities. They are not replaceable extension content. Catalog describes concrete objects; MetaSchema projects safe schema, placement, extension, and Registry-backed metadata for inspection. Capsule is the required extension root because Toolkits persist callable references through Capsule rows. Toolkit and Prompt are packaged default roots. Agent, Memory, and Database are optional roots. A workspace snapshots requested optional roots and recomputes exact Extension.requires dependencies when it reopens.

ws = hb.HeavenBase("research", preset="debug")
ws.enable_extension("memory")

print(ws.extensions())
print(ws.query(hb.MetaSchema).where(hb.MetaSchema.kind == "entity").execute().rows())

Extension enablement is monotonic. HeavenBase has no universal disable operation because an extension may own rows, physical data, derived effects, or cleanup policy that only its domain can explain.

5. Follow Data from Meaning to Storage

An Entity class compiles into an isolated EntitySchema. Registration resolves each field’s authored storage rule against installed placement profiles and the workspace’s named backends. The result is one canonical storage plan. Writes materialize and validate a logical row, group physical fragments by backend, and execute row operations. Reads reverse those routes and merge fragments by stable object_id. Successful non-foundation writes publish Catalog rows after the data mutation. Queries follow the same ownership direction:

Query value
  -> workspace placement evidence
  -> registered operation and handler records
  -> provider-owned compiler
  -> backend execution
  -> detached ResultFrame

Handlers compile logical operations; backends execute neutral fragments. An exact handler key or descriptive module tag is not proof of native execution. Query.explain() reports the selected native, adapter, scan, fallback, or unsupported route.

6. Treat Modules as Data Before Code

Every cohesive built-in or external module folder uses one exact meta.yaml. Its items may declare entities, extensions, backend types, handlers, operations, reducers, strategies, logical types, Toolkit families, MCP profiles, serializers, tags, or other registered roles.

modules = ws.context.modules()

record = modules.inspect("backend_type", "inmem")[0]
claim = modules.tag("backend_type", "inmem", "vector")

print(record["identifier"])
print(claim.value)

Inspection is inert: it reads Registry data without materializing implementation targets. Resolution imports or restores code only when behavior is actually needed. Static semantic claims live in the subject record’s meta.tags; optional tag definitions add diagnostics without closing the vocabulary. Local source: path modules are captured as immutable content-addressed artifacts during installation. Remote acquisition, signatures, and ecosystem trust remain future work.

7. Keep Queries and Results as Values

There is no mutable QueryBuilder. Each query method returns a new hb.Query, so branching is ordinary assignment:

base = ws.query(Product).where(Product.price < 150)
names = base.select("name")
total = base.count().execute().scalar()

print(names.execute().rows())
print(total)

Each execute() returns a newly detached hb.ResultFrame. Use rows(), scalar(), to_pandas(), to_pyarrow(), to_numpy(), to_pydantic(), or to_daft() to choose the consumer boundary explicitly. One workspace can route a query across multiple backends, but independent providers do not become a distributed transaction. Portable scan or fold execution is deliberate when a provider cannot prove equivalent native semantics.

8. Find the Current Source Owners

Area	Source owner	Responsibility
Context and modules	`src/heavenbase/context/`, `src/heavenbase/modules/`, `src/heavenbase/utils/registry/`	Machine state, Registry, descriptors, resolution, artifacts
Workspace	`src/heavenbase/workspace/`	Setup, schema, rows, query, graph, Catalog, MetaSchema, MCP
Placement	`src/heavenbase/placement/`, `src/heavenbase/strategies/`	Storage rules, profiles, plans, bindings
Query values	`src/heavenbase/query/`, `src/heavenbase/filters/`	Immutable request syntax and validation
Execution	`src/heavenbase/execution/`	Frames, fragments, row operations, portable handler contracts
Providers	`src/heavenbase/backends/`, `src/heavenbase/database/`	Backend construction, compilers, provider execution
Agent surfaces	`src/heavenbase/capsule/`, `src/heavenbase/toolkit/`, `src/heavenbase/mcp/`	Callable persistence, Toolkit families, profiles, serving
Optional domains	`src/heavenbase/extensions/`	Prompt, Agent, Memory, and Database extension behavior

The retired heavenbase.registry, heavenbase.storage, heavenbase.handlers, heavenbase.frame, and heavenbase.discovery packages are not compatibility surfaces.

9. Preserve the Architectural Invariants

Add an open extension through Registry records and the shared module protocol, not a central provider switch.
Keep Context ownership explicit when isolation matters; do not fall back to ambient defaults inside a bound workspace.
Register schema before CRUD and keep row operations free of hidden schema lifecycle.
Treat tags as descriptive metadata and explain() as concrete execution evidence.
Keep CLI, dashboard, MCP, and other interfaces thin over owning APIs.
Treat installed executable modules, Capsules, pickle data, and local artifacts as trusted code or trusted-local data.

These rules keep the common user path short without hiding the boundaries that advanced integrations need.

Summary

Context, workspace, and module ownership remain explicit.
Registry records are data before implementations are imported.
Query values, execution plans, and detached frames keep boundaries inspectable.

Further Exploration

Related resources:

Workspace - Open and own an application boundary
Extensions - Understand Registry-backed module contributions
Extension System - Build an external module folder
Routing - Resolve field placement
Query - Work with immutable queries and frames
Catalog - Inspect objects and structure

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Keep the Public Mental Model Small

3. See the Three Ownership Boundaries

4. Understand the Workspace Foundation

5. Follow Data from Meaning to Storage

6. Treat Modules as Data Before Code

7. Keep Queries and Results as Values

8. Find the Current Source Owners

9. Preserve the Architectural Invariants

Summary

Further Exploration

​1. Motivation

​2. Keep the Public Mental Model Small

​3. See the Three Ownership Boundaries

​4. Understand the Workspace Foundation

​5. Follow Data from Meaning to Storage

​6. Treat Modules as Data Before Code

​7. Keep Queries and Results as Values

​8. Find the Current Source Owners

​9. Preserve the Architectural Invariants

​Summary

​Further Exploration

1. Motivation

2. Keep the Public Mental Model Small

3. See the Three Ownership Boundaries

4. Understand the Workspace Foundation

5. Follow Data from Meaning to Storage

6. Treat Modules as Data Before Code

7. Keep Queries and Results as Values

8. Find the Current Source Owners

9. Preserve the Architectural Invariants

Summary

Further Exploration