Overview/xpm — package manager

xpm — Future Integration Notes

How xpm is expected to re-enter the X distribution flow, the preconditions before it can be the active install path, and the seams that should stay stable in the meantime. This document records the current understanding from the workspace-level ROADMAP, this repo's README/ROADMAP, and docs/INTEGRATION.md. Nothing here is committed work; it is planning context.

Where xpm stands today

Within the reboot initiative, xpm/xpkg tooling is postponed (workspace ROADMAP, Phase 4). The distro payload is currently packaged with a PKGBUILD + makepkg flow as the x-scripts package and published through the pacman-compatible repository, consumed on installed systems with pacman. xpm is a functioning, well-tested Rust codebase that is not yet wired into the active reboot path.

The honest consequence: documentation of user-facing behaviour may drift from what a distro actually ships today, because the distro ships the pacman path, not xpm. Treat xpm features as the future native path unless the reboot flow adopts them.

What the generations-alignment slice already added

A self-contained slice landed without wiring the resolver, on the feat/generations-alignment branch:

transaction journal (/var/lib/xpm/journal/*.json) and xpm history [--json];
pre-transaction.d/post-transaction.d hooks with the XPM_* environment contract (runner implemented; the hook scripts arrive with x-scripts);
install-reason tracking and filters (xpm query --format tsv, --explicit/--deps);
reason/origin/files metadata in the local database, and real xpm files/xpm info (these two enable x gen restore --pkg on xpm systems).

Still pending from the same design: the resolver wired into the CLI, --orphans, xpm rollback --last and xpm diff <generation>.

When xpm could become active again

Reasons that would pull xpm (and its companion xpkg) back into scope, per the workspace ROADMAP:

The distro needs the native .xp repository as the distribution channel (moving away from consuming the pacman layout for x packages).
The native install path is functional (resolver-backed install for repo names and local .xp files, dependency-aware upgrade, .files database); remaining pieces are rollback/diff and the native .xp repository rollout.
Reproducible, linted packaging (xpkg) with OpenPGP signatures becomes a hard requirement of the payload pipeline.

Until then, xpm should not be treated as a dependency of the distro build, and the reboot flow should not add assumptions about xpm being installed.

Preconditions before xpm becomes the active path

Code-level gaps that must be addressed when the tool is re-activated (honest, from the repo's own roadmap and current main.rs):

Implement rollback and generation diffs. install (repository or local .xp) and dependency-aware upgrade are wired to the resolver; still pending are rollback --last, diff <generation> and linking journal entries to generation ids.
Complete transaction hardening. .pacnew/.pacsave handling, alpm-hooks execution beyond .INSTALL scriptlets, and conflict/rollback tests.
Complete transaction hardening and recovery. The transaction journal and the pre/post-transaction.d hooks are implemented; still open are xpm rollback --last, linking history entries to generation ids, .pacnew/.pacsave configuration-file management, conflict resolution and rollback tests.
Close production-readiness milestones (repo ROADMAP Phase 8 and Phase 9): benchmarks vs pacman, stress testing against a full repository, fuzzing, error-handling audit (partial downloads, corrupt packages, disk full), and post-v1.0 goals (Python bindings, i18n, TUI, smart mirror selection, configurable cache).
Reconcile config inconsistencies such as the GPG keyring default (config.rs uses /etc/pacman.d/gnupg/ while README guidance uses /etc/xpm/gnupg/).

Integration with xpkg

xpm and xpkg are complementary binaries sharing the package format (per docs/INTEGRATION.md):

Tool	Role	Analogy
`xpm`	Package manager — install, remove, upgrade, resolve dependencies	`pacman`
`xpkg`	Package builder — compile, package, lint, manage repos	`makepkg` + `repo-add` + `namcap`

Lifecycle: source recipe (XBUILD/PKGBUILD) -> xpkg build -> .xp package -> repository database -> static hosting -> xpm sync -> xpm install/upgrade (verify signature, extract, run .INSTALL scriptlets, register locally). xpkg can also emit a plain ALPM-style database; xpm reads both standard and xpkg-extended fields (FILENAME, SHA256SUM, URL), keeping backward compatibility with Arch repositories.

The repo's README references docs/INTEGRATION.md for how the tools work together; keep that document in sync whenever the format changes.

Seams that should stay stable

Because xpm may be dormant for a while, the following interfaces should be treated as compatibility surfaces and documented carefully when they change:

Package format: .xp == ALPM .pkg.tar.zst structure (tar.zst with .PKGINFO, .BUILDINFO, .MTREE, optional .INSTALL). Format version is implicit in the .PKGINFO structure; both tools should move in lockstep.
Repository layout: sync endpoint <server>/<repo>.db (+ .files), xpm-native tree at https://equislinux.github.io/x-repo/x/$arch (do not confuse with the pacman endpoint under /repo/x86_64), signatures as detached .sig, keyring as trustedkeys.gpg.
Configuration: /etc/xpm.conf (TOML), user repos under /etc/xpm.d/, $repo/$arch URL variables, sig_level semantics.
Local database layout: /var/lib/xpm/local/<pkg>/ with version and files entries, sync DBs under /var/lib/xpm/sync/.
Scriptlet contract: bash functions sourced from .INSTALL with XPM_ROOT_DIR, XPM_PKG_NAME, XPM_PKG_VERSION environment variables.

Working conventions that also apply later

When xpm work resumes, the workspace conventions apply as they do today: work happens on the x/reboot branch of this repo, commits stay local (no push), commit messages carry no emojis or external-tool references, and each phase closes with local tests before moving on. Keep any integration decision recorded in the repo or folder it belongs to.