Canonical Architecture

Original Spanish Source

# Alexandria — Living Library Nervous System

**System:** bastion-universalis  
**Namespace:** `alexandria::`  
**Contract:** `.alexandria/contract.yml`  
**Repo mode:** `living_library`  
**Architecture version:** `1.0.0-PTOLEMY`  
**First record:** [FIRST_RECORD_ALEX-001.md](../docs/archivum/alexandria/FIRST_RECORD_ALEX-001.md) · registry: `.alexandria/records/registry.yml`

## What Alexandria is

Alexandria is a **repository architecture**. Not a rulebook, not a policy layer, not
documentation about the system — it is the structural design of a repository that holds
its own history and that can be read correctly by people who do not share a vocabulary.

The premise: one repository, many readers. A systems engineer, a designer, a legal
filer, and someone who has never opened a terminal are all looking at the same files.
None of them is wrong. Alexandria's job is to make the same truth legible at four
different altitudes without any of them having to pretend to be another.

Three mechanisms carry that:

| Mechanism | Question it answers | Where |
|---|---|---|
| **Eight facets** | *What kind of thing am I looking at?* | `contract.yml → facets` |
| **Trust gradient** | *Is this real or is this a sketch?* | `contract.yml → trust_gradient` |
| **Four explain modes** | *Say it in my language* | `tools/alexandria_explain.py` |

The rest of this document is the concrete shape of those three.

## The four readers

The same health state, rendered four ways. No mode is a simplification of another —
each is the full state in a different register.

| Mode | Reader | Register |
|---|---|---|
| `five_year_old` | anyone, no systems background | how the library *feels*, plus the citizen summary |
| `developer` | implementer | every check by name, status, detail, suggested action |
| `stakeholder` | decision maker, non-technical | status, pulse, citizen summary — one line |
| `poet` | narrative, speeches, filings | the organism speaks in its own voice |

```bash
python tools/alexandria_explain.py --mode=stakeholder
```

`--mode=all` emits every register at once. `--json` wraps it for machines.

## The eight facets

Facets are **lenses over the same code**, not folders. A file belongs to a facet by
path, and the facet declares what that file is allowed to import. This is how the repo
stays legible without being reorganized every time someone new arrives.

| # | Facet | Paths | May import | Color |
|---|---|---|---|---|
| 1 | `inbound_gateways` | `main.py`, `graphql_schema.py` | use_cases, core_domain | `#00FF88` |
| 2 | `outbound_clients` | `runtime/**`, `docs/connectors/**` | core_domain | `#00AAFF` |
| 3 | `use_cases` | `services/**`, `scripts/**` | core_domain, persistence | `#FF6600` |
| 4 | `persistence` | `database.py`, `schemas/**`, `repositories/**`, `*.db` | core_domain | `#AA00FF` |
| 5 | `background_workers` | `runtime/workers/**`, `vortex/**` | use_cases, core_domain | `#FFCC00` |
| 6 | `crypto_auth` | `midi_handler.py`, `ai/**` | core_domain | `#FF0066` |
| 7 | `event_streams` | `var/nexus/**`, `tools/nexus_transport.py`, `tools/alexandria_team_sync.py` | core_domain | `#00FFCC` |
| 8 | `diagnostics` | `tools/**`, `var/**`, `logs/**`, `tests/**` | `*` | `#FFFFFF` |

The colors are not decoration — they are the facet's identity across the dashboard,
the system map, and the cartografía overlay. The same green always means gateway.

Import boundaries are checked, not suggested: `alexandria_health.py` reports
`import_boundaries` as a first-class check with a violation count.

## The trust gradient

The gradient exists so that **nobody has to know, by reading a file, whether it is real
or a sketch** — the path already says it. This matters most for people who work in the
repo without being systems people: a designer should be able to move fast inside a lane
without accidentally implying that something is production.

| Level | Name | Boundary check | Paths |
|---|---|---|---|
| 0 | `sandbox` | none | `sandbox/**` |
| 1 | `experimental` | `warn_only` | `static/official/alexandria-design/**` |
| 2 | `proposed` | enforced | `tools/**`, `services/**`, `runtime/**`, `static/official/alexandria/**` |
| 3 | `canonical` | enforced | `architecture/**`, `docs/politica/**`, `.alexandria/contract.yml`, `README.md`, `licencia.md` |

The design lane sits at level 1 with `warn_only` **deliberately**. It is not a lower
grade of work — it is a zone where exploration is not penalized and where nothing is
mistaken for shipped. Promotion out of it is an explicit act, not a drift.

## The organism

Health is not a badge. It is a state with a color and a motion, driven by real checks —
`canonical_files`, `contract`, `import_boundaries`, `library_map`, `library_status`,
`sharepoint_sync`, `team_sync`, `tests`.

| State | Color | Animation |
|---|---|---|
| `resting` | `#00FF88` | slow_breathe |
| `growing` | `#FFCC00` | quick_sparkle |
| `healing` | `#00AAFF` | wave |
| `stressed` | `#FF6600` | rapid_blink |
| `critical` | `#FF0066` | alarm_pulse |

Nothing blinks unless a check actually failed. The animation is a readout, not an
ornament — if the library is breathing slowly it is because the tests passed.

Tagline: *every tongue. one living memory.* · Protocol line: *the living library protocol*

## Records — how history is kept

The library keeps deposits, not commits. Each record in `.alexandria/records/registry.yml`
is an immutable entry with a sequence number, a primary facet, a trust level, its
artifacts by path and role, its dependencies, and — critically — two fields that most
architectures do not have:

- **`boundary_notes`** — every known gap, at green/yellow level, stated in the record
  itself. A record can be `hecho_verificado` and still carry yellow notes. Honesty about
  the edges is part of the deposit, not an afterthought.
- **`explain_like_im_five`** — the deposit in plain language, written at deposit time by
  whoever made it. This is the four-readers principle enforced at the data layer: no
  record enters the library without being sayable to someone outside it.

Thirteen records are deposited: `ALEX-001` … `ALEX-011`, `ALEX-CATRINA-001`,
`ALEX-DESIGN-COORD-001`. Records `ALEX-003` … `ALEX-008` are retroactive backfills of
architecture that already existed — history is recovered, not rewritten.

Deposits are hashed with `blake2b-256`. Generated paths (`.alexandria/state/`,
`.alexandria/outputs/`, `var/`, `logs/`) carry `policy: do_not_edit_manually`.

## Protected zones

`contract.yml → protected.never_autorewrite` covers `licencia.md`, `README.md`,
`architecture/README.md`, `architecture/LIBRARY_STATUS.md`, `docs/politica/**`, `*.md`,
and the contract itself. The rule is `propose_changes_first` — proposals land in
`.alexandria/proposals/` and wait for the operator.

## Agent rules

| Phase | Steps |
|---|---|
| `before_edit` | read_contract → team_sync_claim → read_library_map → run_health_check |
| `after_edit` | run_health_check → update_library_map_if_structural → render_dashboard → team_sync_handoff |
| `final_confirmation` | summarize_changed_files → summarize_validation_result → emit_organism_pulse |

## Lineage

Alexandria descends from a norm but is not one. The norm states the obligation; the
architecture is how the repository discharges it.

**Parent norm:** `::::artemisa::::universalis` → [ARTEMISA_UNIVERSALIS.md](../docs/archivum/ARTEMISA_UNIVERSALIS.md)  
**Consolidation manifest:** `.alexandria/artemisa-consolidation.yml`  
**Status:** Artemisa consolidation layer — production 2026-06-30  
**Status command:** `python tools/alexandria_artemisa.py --status`

Per the contract's own description: *Alexandria is the repo nervous system; Nexus is
live communication; Bastion DS is mandatory visual law.*

## Grok worktree lanes

| Lane | Command |
|---|---|
| Bastion main (this session) | `grok bastion` |
| Alexandria | `grok alexandria` |
| Mappings | `grok mappings` |
| Nexus | `grok nexus` |
| Catrina | `grok catrina` |
| Circus (VJ / visual mesh) | `grok circus` |
| Artemisa (ERP/ORP/GRP) | `grok artemisa` |

Install once: `powershell -File tools/install-grok-lanes.ps1`  
Spec: `architecture/GROK_WORKTREE_LANES.md` · registry: `.alexandria/worktrees.yml`

## Human entry

| Need | Command / URL |
|---|---|
| Health | `python tools/alexandria_health.py` |
| Map | `python tools/alexandria_map.py --write` |
| Dashboard | http://127.0.0.1:8800/alexandria/ |
| Team sync | `python tools/alexandria_team_sync.py --status` |
| Explain | `python tools/alexandria_explain.py --mode=five_year_old` |

## Full specification source

Canonical design document (Obsidian):

`C:\Users\alfonso\OneDrive - Terrauniversalis\#terrasarchivum\#terras\Documents 1\Obsidian Vault\Alexandria.md`

In-repo contract and tooling are authoritative for runtime behavior.

## Production surfaces

```text
.alexandria/                     nervous system (contract, schemas, state)
tools/alexandria_*.py            executable tooling
static/official/alexandria/      served dashboard (unicornd :8800)
static/official/alexandria-design/ Claude Design workspace
var/nexus/messages.jsonl         team communication bus
```

## Nexus integration

Alexandria team sync posts to Nexus Transport (`127.0.0.1:8812`), proxied at `/nexus-api` on unicornd `:8800`.

Alexandria state API runs at `127.0.0.1:8813`, proxied at `/alexandria-api`.

## Agent lanes

| Agent | Lane | Workspace |
|---|---|---|
| Grok | orchestrator | repo + tools |
| Codex | implementer | repo + tools |
| Claude Design | visual | `static/official/alexandria-design/` |
| Operator | governance | architecture |