Covenants
In plain words: Design rules index
The short version written for the Snayu team
The index of LychD's 43 numbered design rules (Architecture Decision Records, called Covenants), grouped by area: foundation, core runtime, agents and memory, and senses and networking. Each rule records a decision, its constraints and consequences.
Why read it: Start here to find which design rule owns a question before you change architecture, or to check what a change must preserve.
- 1A design rule says what was decided; it does not prove the feature is built. Check What Actually Works (State of Work) for that.
- 2The list is closed at 42: amend the smallest existing rule instead of adding a new number.
- 3Every change keeps three things in step: the rule (law), the how-to page (operation) and the evidence (source, tests, receipts).
Words on this page, decoded click one for its card
Where it sits in LychD
Design Rule (ADR) Covenant
A written architecture decision: what was decided, why, and what future changes must respect.
It's like: The building code. You can renovate, but not against code.
Click a dot to open that part's card.
In this section 43 pages
0. License Design rule 00: The license Explains why LychD uses the MPL-2.0 license (the Iron Pact): changes you distribute to core files must stay open, while separate files you add can carry their own terms. open → 1. Philosophy Design rule 01: Development philosophy Sets out how LychD is built: Docs-First Development (xDDD), where the written spec comes first, then the domain model, tests, code and observed results. It also explains how the fantasy names relate to real engineering. open → 2. Documentation Design rule 02: Documentation tooling A historical record of why the official docs are plain Markdown built with Zensical and kept in the same repository as the code, and how different kinds of writing (rules, guides, lore) are kept apart. open → 3. Quality Design rule 03: Code quality tools Fixes the shared Python toolchain - uv for dependencies, Ruff for linting and formatting, BasedPyright for strict type checks and pytest for tests - all run through one Makefile so any failure can be reproduced. open → 4. Testing Design rule 04: Testing approach Defines how LychD is tested: pytest with typed fixtures and Polyfactory test data, run inside a dedicated test container, with markers that say what kind of evidence each test provides. open → 5. Extensions Design rule 05: Extensions Decides how features plug into LychD: either as trusted in-process Python contributions accepted by a named owner, or as separate external services. Defines the vocabulary of Plug-in Areas (Extension Domains), packages, contributions and providers. open → 6. Persistence Design rule 06: Persistence Decides that all committed data lives in one PostgreSQL database, the Memory Vault (Phylactery), accessed through async SQLAlchemy and asyncpg. The vault owns connections, transactions and migrations; each feature area owns the meaning of its records. open → 7. Snapshots Design rule 07: Whole-system snapshots Defines how a whole-system checkpoint must be taken and restored: stop new work, drain or park running jobs, pause writers, then capture every store together with a manifest of exact code, config and image versions. open → 8. Containers Design rule 08: Containers and services Decides that LychD runs as rootless Podman containers managed by systemd user units (Quadlets), with no external control plane. The Engine Room (Vessel) always runs in its container; host-native deployment is retired. open → 9. Security Design rule 09: Security boundaries Defines the trust zones of LychD - the server, an optional gateway host, sandboxes for running untrusted code (Tomb) and for foreign agents (Coffin) - what each may hold, and how data leaving for cloud models passes a Privacy Filter. open → 10. Privilege Design rule 10: Host privileges Defines how actions that change the host (starting services, writing units) are requested and performed. The server never gets a shell, root or the Podman socket; it hands typed requests to a host-side helper (Host Reactor). open → 11. Backend Design rule 11: Server application Decides that the Engine Room (Vessel) is one Litestar web application built once in create_app(), run as a single Granian process and event loop, with HTTP, database, extensions and workers assembled and shut down in order. open → 12. Configuration Design rule 12: Configuration Defines how settings are loaded: one typed Settings model from lychd.toml in the Settings Folder (Codex), plus validated Service Config Files (Runes) for models and services, all checked before they can generate infrastructure. open → 13. Layout Design rule 13: Folder layout Defines where LychD keeps files, following XDG: Settings Folder (~/.config/lychd), Data Folder or Crypt (~/.local/share/lychd) and a disposable build cache (~/.cache/lychd), and which paths it may create, change or delete. open → 14. Workers Design rule 14: Background workers Defines how jobs run: each job is first recorded as a Job Record (Run) in the database, then executed by in-process SAQ queue workers (Ghouls). Waiting, cancelling and crash recovery update that record rather than trusting the queue. open → 15. Frontend Design rule 15: Web control panel Defines the Control Panel (Altar): a static SvelteKit front end with no server-side rendering, using TypeScript types generated from the backend's OpenAPI. The backend keeps all validation and data changes; the browser only displays. open → 16. SDLC Design rule 16: Software change lifecycle Defines how a code change moves from request through candidate work, verification and delivery: each handoff keeps its evidence, and only the owner of the target system may apply the change. open → 17. Packaging Design rule 17: Packaging and releases Defines how source, dependencies, the built web UI, license notices and build evidence are bound into inspectable release artifacts. A successful build never means permission to publish, migrate or restart. open → 18. Evolution Design rule 18: Updating the system Defines how LychD adopts upstream updates while keeping local changes: the update is built, merged, migration-rehearsed and verified as an inactive candidate, then started as a new generation with a recorded recovery point. open → 19. CLI Design rule 19: Command line Defines the Command Line (Pulse), the lychd command: a small, closed set of verbs (init, bind, start, stop, status, logs, access, del) that name operator intent and delegate to typed services. open → 20. Agents Design rule 20: Agents Defines an Agent as one typed thinking step with fixed instructions and output contract, while the model, settings, tools and permissions are attached fresh for each step. Built on Pydantic AI. open → 21. Context Design rule 21: Briefing pack assembly Defines how the Briefing Pack (Context) given to a model is built: typed, ordered layers - stable rules, environment, history, continuation and the query - kept within the model's limits. If required material does not fit, the call fails rather than silently truncating. open → 22. Dispatcher Design rule 22: Model selection Defines the Traffic Controller (Dispatcher), which matches a request's needed capability to a ready model and issues a temporary Model Pass (grant). It never starts or stops model runtimes; that is the Stage Manager's job. open → 23. Orchestrator Design rule 23: Model runtime management Defines the Stage Manager (Orchestrator), the single owner of starting and stopping local model runtimes. It plans swaps from fresh state and declared conflicts, drains active passes first, and performs host changes through systemd. open → 24. Graph Design rule 24: Step maps and pausing Defines how a workflow runs as a Step Map (Graph) using Pydantic Graph: serial steps, checked against a pinned manifest, that can checkpoint, Pause (Stasis) for approvals or hardware, and resume without replaying from the start. open → 25. HitL Design rule 25: Human approval Defines the Approval Step (consent): an agent may propose an effect but never authorize it. The exact proposed call pauses for a human verdict or matches a pre-approved standing rule, then resumes through the same durable path. open → 26. A2A Design rule 26: Agent-to-agent calls Defines the Agent-to-Agent Line (Intercom): how one independent LychD install asks another for bounded work, sending requests and results, never weights, credentials or internal state. The receiver decides how to do the work. open → 27. Memory Design rule 27: Long-term memory Defines Long-term Memory (Archive): records, sources, policy and lifecycle stored in PostgreSQL with pgvector indexes behind LychD's own interfaces. Retrieval frameworks may help but never own storage, curation or training eligibility. open → 28. Workflow Design rule 28: Workflows and apps Defines the Workflow Engine (Spellweaver): who owns each Workflow (Pattern) and its versions, how an App (Composition) publishes workflows, and how one exact workflow version is selected, run, paused and migrated. open → 29. Observability Design rule 29: Observability Defines how logs, events and traces make execution understandable without becoming authority. Every record states who produced it, about what and how it was captured; the office doing an effect keeps the authoritative record. open → 30. Webcrawler Design rule 30: Web fetching Defines the Web Fetcher (Scout): every web action - search, fetch, extract, crawl, render, download and so on - is a separate permitted effect with its own limits, and fetched content is treated as untrusted with its source kept. open → 31. Simulation Design rule 31: What-if simulation Defines the What-if Simulator (Shadow): exploring alternative branches against a pinned starting point, with separate roles proposing (Dancer) and reviewing (Hunter) branches, while the target owner decides any real change. open → 32. Identity Design rule 32: Personas and attribution Defines the Persona Keeper (Mirror): it owns persona definitions and revisions, binds an exact persona version to a job, and keeps attribution between people and machinery. It does not authenticate users or grant permissions. open → 33. Training Design rule 33: Model training Defines the Model Trainer (Soulforge): only explicitly admitted data can become a training corpus, training runs in isolation, and the resulting model must pass independent evaluation and an explicit promotion decision before serving. open → 34. Evaluation Design rule 34: Evaluation Defines the Evaluator (Drift): it tests an exact version of a model, workflow or app against a declared goal and real conditions, using versioned test suites and rubrics, and reports findings with uncertainty. open → 35. Assimilation Design rule 35: Adopting outside code Defines how external code or ideas are re-written as attributable local LychD code under the Smith area: the result is only a candidate that must pass review, testing and a separate promotion before use. open → 36. Vision Design rule 36: Vision and images Defines Vision & Media (Prism): images, video and documents are handled as tracked artifacts with custody, permissions and safe decoding, and every transformation keeps a record of its source. open → 37. Audio Design rule 37: Voice and audio Defines Voice (Echo): speech-to-text and text-to-speech treat audio as a timeline with capture consent, privacy, interruption and delivery tracking, rather than as text with an attachment. open → 38. IAM Design rule 38: Identity and access Defines the Security Desk (Ward) as the single authority for who someone is and what they may do: principals, users, credentials, sessions, ID Badges (Sigils), roles and grants, all starting with zero power. open → 39. VPN Design rule 39: Private network (VPN) Defines the Tether extension: a self-hosted WireGuard tunnel giving the operator a private road to the host. It provides reachability only, never permissions inside LychD. open → 40. Proxy Design rule 40: Reverse proxy Defines the Veil extension: Caddy as an optional, separately managed reverse proxy handling TLS, certificates and routes for remote access, without becoming a second authority over the application. open → 41. Toll Design rule 41: Payments Defines Toll, an optional payments area with two parts: a ledger for quotes, budgets and accounting, and a separate gate that performs one verified, hard-to-reverse settlement. Models and responses can never authorize spending. open → 42. Multinode Design rule 42: Multiple machines Defines how one operator's control plane can delegate bounded work to other machines they own through node agents (Legion), without sharing the database or letting a scheduler override what each node knows about itself. open →
The original text Underlined words open their plain-English card.
The Word binds what the Will would raise.
A CovenantDesign Rule (ADR) explains an architectural choice and what a future change must preserve. Each numbered record gives the decision, the constraints that shaped it, and its consequences. Read the current text for current law; version history preserves earlier rulings.
For a first reading, follow Doctrine, then the question that brought you here. For an operating procedure, enter the Sepulcher. For an implementation claim, consult State of Work: a decision can govern a body part long before that part can be used.
The Return from Myth to Law
The Great Work gives architecture its constitutional pressure. To act on that pressure, engineering needs invariants it can implement, test, refuse, and repair. The table traces that return from myth to law; the images themselves supply no technical proof:
| Constitutional pressure | Engineering return | Owning CovenantsDesign Rule (ADR)s |
|---|---|---|
| A boundary creates perspective without claiming the whole | explicit scope, isolation, and least authority | Security, Layout, IAM |
| A name makes an act answerable | stable identity, attribution, and consequence | Graph, Identity |
| Memory must remain corrigible | provenance, retention, correction, and recovery | Persistence, Memory |
| Imagination cannot write reality by itself | isolated simulation and an explicit promotion gate | HitL, Simulation |
| Another center remains real | consent, refusal, revocation, and bounded delegation | HitL, IAM, A2A |
| Coherence must not require one planetary throne | operator-controlled runtimes, node-local refusal, and bounded federation | Containers, Orchestrator, A2A, Multinode |
| A changed form does not erase its source | privacy lineage, local transformation, and exact declassification | Security, Persistence, Context |
| Power must meet consequence | correlated evidence and adversarial evaluation | Observability, Evaluation |
| Repair may change the vessel | versioned creation, rollback, evolution, and promotion | SDLC, Evolution, Assimilation |
The full cosmology lives in Transcendence. A CovenantDesign Rule (ADR) may name the telos it serves, but its decision must stand on technical requirements and consequences.
Foundation and Governance
| Question | CovenantDesign Rule (ADR) |
|---|---|
| Which reciprocal boundary and contribution terms govern covered code and separate work? | 00 — License |
| How do lore, evidence, code, and the current documentation topology govern one another? | 01 — Philosophy |
| Which historical stack and register discipline formed the HexanomiconOfficial Docs? | 02 — Documentation |
| Which tools and gates define repository quality? | 03 — Quality |
| Which tests prove which kinds of behavior? | 04 — Testing |
| How may native and external organs extend the body? | 05 — Extensions |
Body, Host, and Runtime
| Question | CovenantDesign Rule (ADR) |
|---|---|
| Where does committed state live? | 06 — Persistence |
| What must a recoverable snapshot bind together? | 07 — Snapshots |
| How are rootless service bodies manifested? | 08 — Containers |
| Which trust boundaries protect the host, data, and network? | 09 — Security |
| How are privileged effects proposed, authorized, and recovered? | 10 — Privilege |
| Which application architecture governs the VesselEngine Room? | 11 — Backend |
| How are Settings and RunesService Config Files loaded, composed, and validated? | 12 — Configuration |
| Which paths does LychD own, preserve, or refuse to delete? | 13 — Layout |
| How are durable jobs executed and recovered? | 14 — Workers |
| Which browser architecture and transport boundary govern the AltarControl Panel? | 15 — Frontend |
| How does a software change move from intent through verified delivery and subsequent revision? | 16 — SDLC |
| How are source, packages, images, and receipts bound into a release? | 17 — Packaging |
| How may the body alter itself without severing recovery? | 18 — Evolution |
| Which command grammar and destructive safeguards govern the PulseCommand Line (CLI)? | 19 — CLI |
Agency, Memory, and Consequence
| Question | CovenantDesign Rule (ADR) |
|---|---|
| What is an Agent and how is its capability assembled? | 20 — Agents |
| How is bounded ContextBriefing Pack assembled and governed? | 21 — Context |
| How are capability demand, state, and grants resolved? | 22 — Dispatcher |
| How are physical readiness and scarce resources converged? | 23 — Orchestrator |
| How do graphs checkpoint, pause, resume, and delegate? | 24 — Graph |
| How does human consent survive pause and re-admission? | 25 — HitL |
| How may sovereign LichesThe Assistants address one another? | 26 — A2A |
| How are Seeds admitted, retrieved, corrected, and reanimated? | 27 — Memory |
| Who owns an application, its exact score, casting, coordination, and protected authorship? | 28 — Workflow |
| Which evidence makes an execution legible without granting authority? | 29 — Observability |
| How are search, fetch, render, and extraction effects contained? | 30 — Webcrawler |
| How are speculative worlds isolated, judged, and promoted? | 31 — Simulation |
| How are Persona, SigilID Badge, attribution, and revision bound? | 32 — Identity |
| How are training corpora admitted and resulting weights promoted? | 33 — Training |
| How are capabilities tried, calibrated, and compared? | 34 — Evaluation |
| How does foreign craft pass through Lab, test, and promotion? | 35 — Assimilation |
Senses, Network, and Federation
| Question | CovenantDesign Rule (ADR) |
|---|---|
| How are visual artifacts transformed with provenance intact? | 36 — Vision |
| How are speech and audio transported, retained, and interrupted? | 37 — Audio |
| How do SigilsID Badges, roles, grants, and revocation enforce identity? | 38 — IAM |
| How does the Tether admit remote peers and routes? | 39 — VPN |
| How does the Veil terminate transport without becoming application authority? | 40 — Proxy |
| How are paid effects reserved, signed, committed, and reconciled? | 41 — Toll |
| How may many physical nodes serve one sovereign control plane? | 42 — Multinode |
Changing a Covenant
The numbered CovenantDesign Rule (ADR) register ends at 42 and is closed. Find the smallest existing CovenantDesign Rule (ADR) that owns a new architectural decision, then amend or rewrite it. Do not add another CovenantDesign Rule (ADR) number. When a decision is reversed, version history keeps the displaced law legible.
Every change preserves three seams:
- Law: the CovenantDesign Rule (ADR) states the decision and its invariants.
- Operation: the owning SepulcherThe Body, AltarControl Panel, or CompositionApp page shows how that law is used.
- Evidence: State and its linked source, tests, lockfiles, or receipts show what has entered matter.
Authoring mechanics and verification commands belong in CONTRIBUTING.