11. Backend: The Vessel

Requirements

• Architectural Scalability: The framework must support an unbound router system, allowing routes to be defined in isolation and "registered" without circular dependency issues.
• Federated Logic Assimilation: The system requires a formal Extension Context registration surface to allow disparate organs to graft runtime-facing logic onto the Vessel without coupling themselves to a global app object.
• Persistence Efficiency (DRY): Mandatory minimization of code duplication between database models and API schemas through automated Data Transfer Object (DTO) generation.
• High-Throughput Serialization: The backend must natively support high-performance binary serialization (e.g., msgspec) to integrate with the Phylactery's (06) binary transmutation hooks.
• Extensible Initialization: The framework must support a formal plugin protocol for the injection of configuration and lifecycle hooks at boot time.
• Dual-Mode Bootstrapping: The architecture must handle two distinct operational realities—a heavy Server Mode for asynchronous rituals and a lightweight CLI Mode for system management—within a unified entry point.

Considered Options

Decision Outcome

Litestar is adopted as the foundational web framework for the Vessel. It provides the structure required for a federated system where logic is treated as a set of pluggable organs.

1. The Modular Registry (The Extension Context)

The application rejects the use of a global app object. Instead, logic is assimilated via a registration protocol:

• The Context: During boot, the system initializes an ExtensionContext. This object is passed only to organs participating in in-process runtime grafting. It is the host-provided grafting surface for that binding path, not the whole Extension Protocol defined in ADR 05.
• Assembly: The application factory iterates through these registered objects, collecting unbound Router instances and standalone Controller classes. These are then grafted onto the Vessel to assemble the final API surface. This prevents circular imports and allows for the seamless addition of new interfaces without a global app object.

2. The Initialization Protocol (Duality)

Application logic is encapsulated within custom initialization plugins that implement the framework's native protocols:

• Server Context (Deep Awakening): When executed by an ASGI server, the plugin initializes heavy infrastructure, including background Ghouls (14), observability exporters, and the full connection pool to the Phylactery.
• CLI Context (Lightweight Manifestation): When executed as a management tool, the plugin skips web-related infrastructure and injects custom management commands directly into the command group, ensuring near-instantaneous response times.

3. High-Performance Transmutation

To ensure the Vessel can handle the massive execution history and cognitive state dumps stored in the Phylactery (06), the backend is configured for binary efficiency.

• msgspec Integration: The framework utilizes msgspec as its primary serialization engine.
• Binary Hooks: The Vessel leverages the custom codec hooks defined in the persistence layer. This allows the backend to receive raw binary JSONB from the database and pass it directly to the interface without intermediate string encoding, bypassing the "Double Encoding" CPU tax.
• The Tomb config is a generated runtime envelope with only task-safe fields.
• The Tomb config is derived data, never an alternate source of truth.
• The Tomb schema forbids secret fields and infrastructure authority fields.
• Provider/API keys are never serialized into Tomb payloads.
• The Tomb cannot override queue, network, or authority policy.

4. Automated Data Integrity

To ensure the persistence layer remains the single source of truth, the Vessel utilizes SQLAlchemyDTO factories from Litestar's native DTO system. When the Phylactery (06) schema changes, the API schema auto-projects it. There are no manually maintained Pydantic "shadow schemas" for ORM models in the Vessel codebase.

5. Dual-Plane Trust Delta

Backend scope is now explicitly control-plane only.

• Vessel owns API, orchestration, control-plane queue policy, persistence access, and promotion authority.
• Vessel agents can plan, score, route, validate, and gate HitL.
• When a Vessel-side agent needs unsafe execution, it serializes only the hand-work into a Tomb job; the agent itself does not migrate into the Tomb.
• The Tomb mounts only task/workspace/artifact regions with minimal write scope.
• Suggested Tomb regions:
  • ~/.local/share/lychd/tomb/jobs/ — one subdirectory per SAQ job to prevent file collisions between concurrent Ghouls
  • ~/.local/share/lychd/tomb/workspaces/
  • ~/.local/share/lychd/tomb/artifacts/
  • ~/.local/share/lychd/tomb/cache/
• The Tomb must not mount writable Codex, provider secrets, or host trigger/signaling paths. If a job profile needs configuration-shaped facts, the profile receives no Codex mount by default or a read-only/sanitized projection.
• The Tomb may receive a narrow queue-only SAQ/Postgres execution credential for execution-plane job claiming, acknowledgement, and retry bookkeeping, but no control-plane database authority.
• The Tomb runs no agent logic, graph runners, or LLM calls. It is a brainless executor. See Workers (14) for the full doctrine.

6. The Four Covenants of the Vessel

These are non-negotiable implementation laws for all code written against the Vessel. They are the direct consequence of choosing Litestar to support the federated, decoupled extension architecture. Agents and human contributors must adhere to them without exception.

I. The Unbound Routing Law

Mandate: All routes must be defined in standalone Controller classes or unbound Router instances. The application factory collects these from the ExtensionContext and grafts them onto the Vessel at boot — they must have zero knowledge of the application object at definition time.

# ✅ Correct — unbound, collectable
from litestar import Controller, get, Router

class RuneController(Controller):
    path = "/runes"

    @get("/")
    async def list_runes(self) -> list[RuneDTO]: ...

router = Router(path="/api", route_handlers=[RuneController])

# In register(context): context.add_router(router)

II. The DTO Mandate (Death to Boilerplate)

Mandate: Use Litestar's SQLAlchemyDTO factories to derive read/write/patch schemas directly from ORM models. The database model is the single source of truth; the DTO is a projection of it.

# ✅ Correct — schema derived from ORM, no duplication
from litestar.contrib.sqlalchemy.dto import SQLAlchemyDTO
from litestar.dto import DTOConfig

class RuneReadDTO(SQLAlchemyDTO[RuneModel]):
    config = DTOConfig(exclude={"secret_field"})

class RuneWriteDTO(SQLAlchemyDTO[RuneModel]):
    config = DTOConfig(include={"name", "runic", "config"})

III. The Repository Law (Advanced Alchemy)

Mandate: All CRUD operations must use SQLAlchemyAsyncRepository from advanced_alchemy. The repository is injected via Litestar's dependency system, keeping the data access layer reusable across the HTTP layer, the SAQ worker layer, and the agent graph layer.

# ✅ Correct — repository injected, decoupled from HTTP cycle
from advanced_alchemy.repository import SQLAlchemyAsyncRepository
from litestar import get
from litestar.di import Provide

class RuneRepository(SQLAlchemyAsyncRepository[RuneModel]):
    model_type = RuneModel

async def provide_rune_repo(db_session: AsyncSession) -> RuneRepository:
    return RuneRepository(session=db_session)

@get("/runes", dependencies={"repo": Provide(provide_rune_repo)})
async def list_runes(repo: RuneRepository) -> list[RuneReadDTO]:
    return await repo.list()

IV. The Native Response Law

Mandate: - Altar (HTMX): Use Litestar's HTMXRequest and HTMXResponse types. Use HTMXPlugin for global configuration. Return Template responses with hx-swap headers natively. - Oculus (Observability): Use Litestar's built-in OpenTelemetryPlugin for tracing Agent Thought Traces. Do not introduce opentelemetry-instrumentation-fastapi or equivalent shims.

# ✅ Correct — native plugins, no external shims
from litestar.contrib.htmx.plugins import HTMXPlugin
from litestar.plugins.opentelemetry import OpenTelemetryPlugin, OpenTelemetryConfig
from litestar import Litestar

app = Litestar(
    plugins=[
        HTMXPlugin(),
        OpenTelemetryPlugin(config=OpenTelemetryConfig(tracer_provider=...)),
    ],
)

Policy Table

Consequences