Design Goal

PIEF is an interchange format by which package managers export the current contents and current selection state of one package database, profile, prefix, or installation scope.

The format is not a transaction log, an audit log, or a replay format. Consumers MUST NOT infer current system state by replaying historical package operations. A PIEF export is a snapshot of what the package manager currently believes to be installed, selected, protected, or reachable in the active installation universe.

The primary consumer question is:

Which currently active package roots were intentionally selected by an
administrator, manifest, OS image, profile, or comparable policy source?

A secondary question is:

Which currently active package artifacts exist only because they are required
by those roots?

The format is designed to merge reports from package managers that may coexist on a system: distro package managers, application managers, language-specific global installers, user-level package managers, immutable profile systems, and content-addressed stores.

Non-goals

PIEF does not record every operation ever performed.

PIEF does not require a package manager to explain how the current state was reached.

PIEF does not require rollback tools to translate a rollback into synthetic remove/install operations.

PIEF does not assume that the system was produced by an imperative sequence of package-manager commands.

PIEF does not treat old generations, inactive profiles, cache entries, or garbage-collectable store paths as part of the active inventory unless the export explicitly names them as active.

Terminology

scope

A package namespace and installation universe whose package identities can be interpreted together. Examples include apt:/, rpm:/, flatpak:system, flatpak:user:1000, homebrew:/opt/homebrew, npm:/usr/local, pipx:user:1000, and nix:profile:/nix/var/nix/profiles/system.

snapshot

A complete observation of one scope at one package-database state.

root

A current top-level selection. A root may be a package, group, module profile, manifest entry, Nix profile element, Flatpak app, Homebrew cask, pipx app, Cargo-installed binary crate, OS image component, or comparable current selection.

artifact

A concrete installed thing: package, formula, cask, runtime, snap, crate, Python distribution in a managed venv, Nix store path, or comparable object.

selection

The current policy relationship between an artifact and the active roots.

base

The artifact or root belongs to the active base image, bootstrap set, system profile, installer manifest, or equivalent current platform baseline.

manual

The artifact or root is currently selected by an administrator, manifest, profile, or explicit global-install request.

auto

The artifact is currently present because it is required, recommended, supplied as a runtime, or otherwise reachable from a current root, but is not itself a current root.

unknown

The exporter can prove the artifact is active, but cannot determine whether it is base, manual, or auto.

Format

A PIEF stream is JSON Lines. The stream consists of one snapshot record, zero or more root records, zero or more artifact records, optional edge records, and one snapshot-end record.

A consumer MUST interpret records only within the same snapshot_id. A consumer MUST NOT combine records from different snapshots as if they were one transaction history.

A producer SHOULD write snapshots atomically when writing to disk. If atomic replacement is not available, a consumer SHOULD ignore a snapshot that lacks a matching snapshot-end record.

Time Values

PIEF distinguishes observation time from package-selection time.

observed_at describes when the snapshot was exported.

selected_at, installed_at, or first_observed_at, if present, describe timestamps remembered by the package database for a root or artifact.

Time values SHOULD include a realtime timestamp, a boot ID, and a monotonic or boottime timestamp when the event occurred during a boot for which that data was available.

Example:

{
  "realtime": "2026-05-18T15:04:05.123456Z",
  "boot_id": "7bb7e2b58f5e4e0f9b2c3e7f4e7a9f11",
  "monotonic_usec": 812345678,
  "clock_status": "unknown"
}

A realtime timestamp alone is not sufficient for ordering early-boot or first-install events on systems whose wall clock may not yet be set. Monotonic timestamps are only comparable within one boot and therefore must be paired with a boot identifier.

Snapshot Record

{
  "record": "snapshot",
  "format": "pief",
  "format_version": 1,
  "snapshot_id": "01JVR6K2ZCFAT3RZ3Z2W0V6S1G",
  "scope": "apt:/",
  "producer": {
    "name": "apt",
    "version": "3.0.3",
    "exporter": "inventory-apt"
  },
  "database": {
    "kind": "dpkg+apt",
    "root": "/",
    "generation": "opaque-manager-defined-value",
    "complete": true
  },
  "observed_at": {
    "realtime": "2026-05-18T15:04:05.123456Z",
    "boot_id": "7bb7e2b58f5e4e0f9b2c3e7f4e7a9f11",
    "monotonic_usec": 812345678,
    "clock_status": "synchronized"
  }
}

Root Record

A root record describes a current top-level selection.

{
  "record": "root",
  "snapshot_id": "01JVR6K2ZCFAT3RZ3Z2W0V6S1G",
  "scope": "apt:/",
  "root_id": "root:manual:vim",
  "root_kind": "package",
  "selection": "manual",
  "selector": {
    "name": "vim",
    "native": "vim:amd64"
  },
  "source": {
    "kind": "administrator-request"
  }
}

Base systems are also roots:

{
  "record": "root",
  "snapshot_id": "01JVR6K2ZCFAT3RZ3Z2W0V6S1G",
  "scope": "nix:profile:/nix/var/nix/profiles/system",
  "root_id": "root:system-generation:42",
  "root_kind": "system-profile",
  "selection": "base",
  "selector": {
    "profile": "/nix/var/nix/profiles/system",
    "generation": 42,
    "store_path": "/nix/store/...-nixos-system-host-26.05..."
  },
  "source": {
    "kind": "declarative-system-configuration"
  }
}

Artifact Record

An artifact record describes something currently active in the scope.

{
  "record": "artifact",
  "snapshot_id": "01JVR6K2ZCFAT3RZ3Z2W0V6S1G",
  "scope": "apt:/",
  "artifact": {
    "kind": "deb",
    "name": "vim",
    "version": "2:9.1.001-1",
    "id": "vim:amd64",
    "architecture": "amd64",
    "repository": "debian-stable"
  },
  "status": "installed",
  "selection": "manual",
  "root_ids": ["root:manual:vim"],
  "held": false
}

A dependency is still current-state data, not a replayed install event:

{
  "record": "artifact",
  "snapshot_id": "01JVR6K2ZCFAT3RZ3Z2W0V6S1G",
  "scope": "apt:/",
  "artifact": {
    "kind": "deb",
    "name": "vim-runtime",
    "version": "2:9.1.001-1",
    "id": "vim-runtime:all"
  },
  "status": "installed",
  "selection": "auto",
  "root_ids": ["root:manual:vim"]
}

If the manager cannot explain why an installed artifact exists, it should say so:

{
  "record": "artifact",
  "snapshot_id": "01JVR6K2ZCFAT3RZ3Z2W0V6S1G",
  "scope": "rpm:/",
  "artifact": {
    "kind": "rpm",
    "name": "example",
    "version": "1.0-1",
    "id": "example-1.0-1.x86_64"
  },
  "status": "installed",
  "selection": "unknown",
  "source": {
    "kind": "low-level-database-entry"
  }
}

Edge Record

An edge record is optional. It explains current reachability. It is not a transaction edge.

{
  "record": "edge",
  "snapshot_id": "01JVR6K2ZCFAT3RZ3Z2W0V6S1G",
  "scope": "flatpak:system",
  "from": "root:app:org.gimp.GIMP",
  "to": "artifact:runtime:org.gnome.Platform/x86_64/46",
  "edge_kind": "runtime"
}

Useful edge kinds include dependency, weak-dependency, runtime, content, build-dependency, profile-member, group-member, module-profile-member, and closure.

Snapshot End Record

{
  "record": "snapshot-end",
  "snapshot_id": "01JVR6K2ZCFAT3RZ3Z2W0V6S1G",
  "scope": "apt:/",
  "artifact_count": 1432,
  "root_count": 37,
  "complete": true
}

Consumer Rules

Consumers select one complete snapshot per scope.

Consumers MUST NOT replay snapshots as operations.

Consumers SHOULD show manual roots by default.

Consumers SHOULD suppress base roots by default unless the user requests base system contents.

Consumers SHOULD suppress auto artifacts by default unless the user requests dependency closure or support packages.

Consumers SHOULD report unknown artifacts separately, because they indicate database state that the package manager cannot classify.

Consumers MAY merge snapshots from multiple scopes into one inventory report, but MUST preserve scope boundaries.

Package-Manager Mapping

Package-manager adapters SHOULD export current roots and current artifacts from the authoritative package database, profile, lockfile, manifest, or installation state.

Adapters SHOULD prefer native current-state data over historical logs.

Adapters MUST mark state as unknown rather than inventing intent.

For immutable profile systems, adapters SHOULD report the current active profile or generation as a root and SHOULD report profile elements or closure paths as artifacts according to the user’s requested verbosity.

For package managers split into high-level and low-level layers, the exported selection state MUST come from the layer that owns the durable current-state classification. If the lower layer can be modified independently and does not carry selection metadata, the exporter MUST be able to surface those entries as unknown.