Architecture

Two release binaries

What happens on a search

1. A simple omg search or omg info call takes an optimized path. Search may query a running daemon; Debian package info can read the local APT database directly.

2. When a daemon answers, it checks its in-memory cache.

3. On a daemon cache miss, the daemon searches its in-memory package index and remote sources.

4. The daemon caches that result and returns it to the CLI.

5. If the daemon is unavailable, the CLI uses the same direct backend path. On Arch, official repositories and the AUR can be queried in parallel.

What happens on a runtime switch

1. The CLI detects the runtime type and checks whether the requested version is installed.

2. If not, it downloads the release from its configured provider and checks the integrity data available for that provider.

3. The version is extracted under versions/runtime/version in the OMG data directory.

4. The current symlink records the selected version. When a project pin exists, the shell hook prepends that concrete version directory to PATH.

Cache tiers

# omg.status is exactly 32 bytes, laid out as:
#   offset 0   4 bytes   magic 0x4F4D4753 ("OMGS")
#   offset 4   4 bytes   format version
#   offset 8  16 bytes   four u32 counts: total, explicit, orphan, updates
#   offset 24  8 bytes   unix timestamp in seconds

# Hook helpers accept the file only when its owner, size, format, and age pass
# validation. When it is missing or stale, check current state with omg status.
omg-ec   # explicitly installed packages in Bash or Zsh
omg-uc   # updates available in Bash or Zsh

IPC protocol

• Transport is a Unix domain socket with length-delimited framing.
• Messages use a compact binary serialization format chosen for low latency.
• Requests cover search, package info, system status, security audits, explicit package listings, and cache or health controls.
• A daemon cache hit returns the stored result. A miss searches the in-memory index and, when the command needs them, the native databases and remote sources.
• Without a running daemon, the CLI falls back to direct package-manager queries instead of failing.

# frame = [ length ][ version prefix ][ bitcode payload ]
#   both peers reject a version prefix they do not understand

# 1. the CLI writes one request frame
# 2. the daemon decodes it and routes it to a handler
# 3. the daemon writes one response frame
# 4. a decode error fails the call; it is never reported as an empty success

# The socket path resolves from OMG_SOCKET_PATH, then $XDG_RUNTIME_DIR/omg.sock.
# Without XDG_RUNTIME_DIR, Unix uses /run/user/$UID/omg.sock when available,
# otherwise a validated private /tmp/omg-$UID directory or home fallback.
# It will not use another user's socket when ownership checks fail.
omg daemon-status

Security paths

1. Runtime and self-update downloads verify expected SHA-256 digests.

2. AUR key preparation uses gpg to inspect and import required keys.

3. omg audit slsa verifies a Sigstore hashedrekord artifact signature and Rekor signed entry timestamp. It does not verify a Merkle inclusion proof or establish build provenance.

4. In v0.1.223, omg audit needs omgd and queries supported OSV ecosystems. Current main has a direct fallback and native Arch and Fedora advisory paths.

5. Arch installs and updates check policy.toml against prepared transactions. Native APT, DNF, and Homebrew mutations refuse explicit policy.

Background workers and shutdown

• A status refresh worker probes runtime versions, counts vulnerabilities, updates caches, and rewrites the binary status file and JSON snapshot.
• An optional ALSA scanner periodically fetches Arch security advisories and matches them against installed packages.
• On SIGINT or SIGTERM the daemon stops accepting connections, lets active requests finish, stops workers, and cleans up the socket.