Architecture

omarchy-pool is a package repository for Omarchy built on three ideas: an immutable package pool plus an index that represents complete releases, signed pacman databases generated from that index, and a thin client that understands releases. It began as a proof of concept answering exactly those three questions — the evidence is kept in poc/RESULTS.md — and now runs as the staging environment at https://omarchy-pool.org.

Packages are standard Arch .pkg.tar.zst archives produced by makepkg; they are never modified. The deployment is a Cloudflare Worker + D1 + R2; the pipeline is a queue of jobs in D1 that workers anywhere pull; GitHub hosts the code and cuts the releases.

The problem

Today edge, rc and stable are three complete directory trees (~275 GB each). Promoting a release copies and re-uploads most of that data, so a bump takes 30–60 minutes even when almost nothing changed.

The publishing layer

• Pool — Cloudflare R2, one directory per source (<source>/<arch>/<filename>, worker/src/r2.ts), the way the mirrors lay out extra/os/x86_64/. A package is uploaded exactly once, whether it came from the Arch mirror sync or from an OPR build; two projects' builds of one filename with different bytes — Arch's asusctl-6.5.0-1 and the OPR's, Arch Linux ARM's libkrunfw and Asahi's — are two objects in two directories, each served by its own repository section. Within one source a filename is one object: an upstream that rebuilds the same version with different bytes (the OPR does, per channel) keeps the object already stored. The rows of the index carry their key (packages.r2_key); the move from the earlier flat layout (<arch>/<filename>, one object per filename whichever source built it) was the one-time relayout job (worker/src/routes/relayout.ts).
• Index — Cloudflare D1. Every package with its full metadata (from .PKGINFO plus the ELF soname graph extracted by pkg-extract) and every release.
• Releases — a release is a pinned selection of package ids for one ring (edge, rc, stable — and lab, below). Promotion creates a new release for the target ring that points at the same selection: an index write, no bytes move. Rollback is the same write pointing at an earlier selection; history is append-only. Stored as deltas: what a ring serves now lives in one table (ring_packages), a release writes only what it changed against its parent (release_deltas), and the full membership is written out for a checkpoint — the first release of a ring, then every 24th, and any older release read by id (a pinned page, a diff, a rollback target), reconstructed from the checkpoint behind it plus the deltas. A release costs hundreds of rows, not thirty thousand (migration 0017). A selection holds one row per source, name and architecture: a package added replaces its own source's build of that name, never another source's — Arch Linux ARM's mesa and asahi-alarm's are two rows, each in its own database, and the order of the pacman include (REPO_ORDER, worker/src/meta.ts) is the only thing that decides between them, as it does between mirrors. A sync drops a name from its own source's rows (remove_from); a maintainer's remove drops it from every source.
• Generated pacman databases — for each ring and source the publisher renders omarchy-<source>-<ring>.db and .files in repo-add format and uploads them; the Worker signs them with its own OpenPGP key (a secret that never leaves Cloudflare, worker/src/signing.ts) and stores them beside the packages (core/x86_64/omarchy-core-stable.db). pacman reads the bucket's custom domain directly — each section's Server = https://pool…/<source>/$arch, the directory its database is in (the include, worker/src/routes/setup.ts, names it from the artifact's key) — and the only thing that differs between rings is the repository name. No worker, no redirect on the read path.

Index schema (D1)

Migrations live in worker/migrations/.

Index API (Worker)

pacman never talks to the worker. The worker never resolves dependencies; it serves data. Decisions are made by the publisher (pkg-repo) and the client.

Staging pipeline (pulled jobs)

Every row below is a pulled job: the Worker's cron queues it in build_tasks on this schedule (JOB_KINDS), a project worker runs it with a per-job token, and a maintainer queues the same by hand (pkg-repo job). Nothing of the pipeline runs on GitHub Actions. The project's workers are three roles of one image (factory/README.md Three roles): pool workers take the rows below, review workers the project's build and the audit, shared community workers the contributors' builds — two of each, one per architecture, on the project's host (RUNBOOK, The Studio host). A community worker is a pair: a broker that holds the worker's token, the agent key and a GitHub token and only receives, processes and answers, and a builder born with nothing that builds one task and dies (factory/bin/broker; SECURITY.md, Isolation). A project worker is its own broker: the build containers it starts hold nothing and reach the agent through agent-proxy.

Every step posts an event; https://omarchy-pool.org renders them. Nothing of the pool's operation runs on GitHub besides CI and the release (since 2026-09-17: no recipe pull requests, no dispatched workflows — a GitHub outage stops the code from changing and nothing else). No worker runs on GitHub: the project's six run on its own host (RUNBOOK, The Studio host). Operations, trust model and the kill switch are in RUNBOOK.md.

The lab: tried before it is promised

edge, rc and stable are the promise: whichever source built a package, it enters edge signature-verified and reaches rc and stable by evidence — the same gates for Arch's packages, Arch Linux ARM's, the Asahi fork's, the OPR's and the factory's. Zero trust: the pool verifies and validates; it does not choose whom to believe. The lab is the fourth ring, beside the three and never on their path: nothing in it is promised, no sync targets it, no promotion comes from it or goes into it (POST /releases refuses both). What it is for:

• the factory's builds land there first — the review build of an approved package publishes into the lab, and the trial job installs it with a real pacman in a clean container against edge, runs the hooks, checks the ABI, and records the transcript beside the audit for the maintainer who decides;
• any object the pool holds can be pinned there, from any source, to be tried in a combination (the Asahi fork's mesa under edge's hyprland, say);
• a machine that wants to try it is one command away: --ring lab writes the lab's sections above edge's, so what is being tried wins by order and its dependencies resolve from edge; a lab with no release yet is edge.

A build leaves the lab for edge by a maintainer's approval (the publish job), never by promotion; retention keeps the lab's last releases like any ring's. The fast lane: a build the trial installed goes to rc and stable with edge — the publish job's token opens those rings only when the trial's verdict was ok, and a fast-track event records it — as a security fix does (the security layer's own fast-track). The maintainer decided the build; the evidence decides the speed.

Promotion by evidence, not by calendar

A promotion happens when the recorded evidence says the source ring is good — and is attempted when that evidence can exist: the sync that changed edge queues edge → rc (routes/factory.ts), rc → stable is attempted every three hours (scheduler.ts) — and is undone automatically when the target ring turns out not to be:

1. Evidence. On both architectures, a real pacman syncs the source ring and downloads a signed sample of every repository (health event), and omarchy-cli runs the ELF-level safety check on every upgrade the ring would apply to two reference systems (abi event, blockers = unsatisfiable symbol versions): the official Arch / Arch Linux ARM base image, and — on x86_64 — an Omarchy installation, the ISO's package set (omacom/omarchy's omarchy-base.packages plus the archinstall base) installed from stable into a container and cached for a week (tests/omarchy-rootfs.sh, ~900 packages) — what users actually have.
2. Gate (pkg-repo gate). Per architecture: the latest health of the source ring is recent and not an error; health did not keep failing (three errors in a day block — a failure the next check recovered from stays in the report as evidence); the soak is met — soak_checks green health checks in a row recorded since the source ring's current release: one for edge → rc (the check the promote job just ran), two for rc → stable (the attempt three hours earlier and this one), so stable is about six hours behind rc and never waits for a calendar; a recent ABI check found no blocker; and the security layer reports no regression — a package the target serves clean today that the source would replace with a version under an open advisory the tracker is sure about (exact match, medium or worse, or exploited in the wild). Clean means examined: a version indexed before the component scan existed has no embedded components and no OSV advisories, and counts as clean for nothing an OSV advisory is about. The fast-track pulls fixes forward; the gate never pushes a known hole. A ring with nothing rendered for an architecture is not evidence against it. If the target already serves the source's head there is nothing to promote. The verdict and its reasons are a gate event.
3. Promote, render, verify. The index write records the previous head; the databases are rendered and signed for both architectures; the target ring gets the same health check on both.
4. Automatic rollback. If that health check fails, the ring is pointed back at the previous release (another index write), re-rendered, and a rollback event says which release failed and which one was restored. Otherwise a promote event confirms it.

Stable moves without a human: the evidence is the reviewer, and a maintainer who disagrees queues a rollback.

Security: advisories with confidence, exposure through the graph

Every object a ring serves is matched against public advisories (security.yml, tables advisories, cve_meta, package_advisories). Each match carries how sure we are — exact (the Arch tracker knows Arch's version), name-version (Debian fixed the same upstream project in a version newer than ours), name-only (still open upstream; possibly affected) — and each CVE whether it is exploited in the wild (KEV) and how likely exploitation is (EPSS). Arch is authoritative: Debian only fills CVEs Arch has no advisory for, and a name whose versions are an order of magnitude apart from Debian's (keystone: assembler vs OpenStack) is treated as a different project.

Fixes travel faster than features: pkg-repo fast-track pulls a clean version into rc/stable as soon as edge has it, with the same render → health → rollback safety net as a promotion, and omarchy-cli security / omarchy-cli upgrade --security-only let a machine apply just those.

Exposure is not stored: the index derives it from the same dependency and soname graph the package page draws — a package is exposed when it declares a vulnerable package or when one of its binaries loads a library the vulnerable package provides (the stronger evidence). The Security page shows both per ring, the package page shows the chain, and the graph marks the nodes.

Architectures

A package row records repo_arch, the architecture of the upstream repository it came from; it is the pool directory (x86_64/…, aarch64/…) and, with the name, the replacement key inside a ring. any packages are per-upstream builds: Arch's and Arch Linux ARM's python-foo-1.0-1-any are different objects in different directories. A ring holds both architectures; render --arch emits one database per source for that architecture.

Extraction (crates/pkg-extract)

Out-of-band: the archive in the pool is byte-for-byte what makepkg produced. For each package the extractor merges .PKGINFO with the ELF facts of every shipped object (DT_SONAME, DT_NEEDED, .gnu.version_r) into a PackageManifest (crates/pkg-manifest). Symbol versions collapse to the highest per (soname, namespace) since GLIBC_2.34 subsumes GLIBC_2.14.

The manifest carries everything repo-add puts in a desc file (pkgbase, builddate, packager, makedepends, filename, …) so databases can be rendered from the index alone.

Statically linked binaries reveal nothing through sonames, so the extractor also reads what they embed (components): the Go modules a Go binary was built with (debug/buildinfo, present in every Go binary since 1.12 — the modinfo string between its sentinels, replacements applied) and the crates a Rust binary was built with when the packager used cargo-auditable (the .dep-v0 ELF section, zlib-compressed JSON; Arch's own Rust packages do not carry it, the factory's recipes could). Named the way OSV names them (Go, crates.io), one index row per module or crate, shown on the package page as Embedded libraries.

Database generation (crates/pkg-repo)

Renders a release into repo-add-compatible archives:

• <repo>.db.tar.gz — one <name>-<version>/desc entry per package;
• <repo>.files.tar.gz — the same plus a files entry;
• detached GPG signatures (.sig) for both.

Validation: an Arch container with Server = https://pkgs.<domain>/$repo/os/$arch runs pacman -Sy and pacman -Sp <pkg> against the generated database. See TESTING.md.

Safety check (crates/pkg-check)

• local::LocalDb — the pacman local database, read-only: installed versions and provides.
• abi::SystemAbi — the shared libraries actually on disk and the symbol versions they define (.gnu.version_d).
• check — for every package the release would install, each requires rule is classified: satisfied by the plan itself, by an installed library/package, a warning (pacman must resolve it from another repository; a library that is not on disk at all is almost always optional to one binary) or a blocker (a library this system has, but too old — it does not define the symbol version the package needs).

Thin client (crates/omarchy-cli)

The client drives pacman rather than replacing it. What it adds:

• knows which release the machine is on and what the ring currently serves (status, upgrade pins pacman to that release);
• safety check before an out-of-band install: fetches the dependency subgraph, reads /var/lib/pacman/local, and refuses when a library on the system does not define a symbol version the package needs — the case that today produces a broken partial upgrade;
• hook preview: check and install list the libalpm hooks pacman would run for the transaction (mkinitcpio, glib-compile-schemas, …) — the .hook files of the system (/usr/share/libalpm/hooks, /etc/pacman.d/hooks, the latter overriding by name) matched against the planned packages by name and by the files they ship, fetched from the ring. Read-only: pacman runs them; poc/crates/pkg-hooks parses and matches;
• mirror discovery and release notifications come from the index, not from pacman -Sy polling. A ring holds every source's build of a name; the client takes one per name in the pool's source_order (the release and graph views carry it — the include's order, what pacman takes from the first section that has the name) and hands pacman the object's own address, <pool>/<source>/<arch>/<filename>;
• MCP (omarchy-cli mcp): the same answers as tools for an assistant on the machine — status, check, info, search, list, security — over stdio (JSON-RPC, one message per line), read-only; installing and upgrading stay with the person at the keyboard (docs/omarchy-cli-mcp.md).

vercmp is a byte-for-byte port of alpm_pkg_vercmp so the client and pacman always agree on ordering. Settings live in /etc/omarchy-cli/config.toml (docs/omarchy-cli.config.toml is the annotated example); the ring and the architecture are checked before any request.

Not on the product path

poc/crates/pkg-store (a redb state store plus a journaled, crash-safe filesystem transaction — the engine that would let the client stop shelling out to pacman) is built and tested but not wired in: the thin client did not need it. (poc/crates/pkg-hooks, once only the types, now parses and matches .hook files for the client's hook preview; running them stays with pacman.) They stay in the workspace so they keep compiling; see poc/README.md. Open work is in TODO.md.