Peipkg

A package's name identifies it within a repository and across all repositories that may serve it. Two packages with the same name installed simultaneously is a conflict (§4.1).

§2.1.1 Character set

Package names MUST consist of ASCII characters from the following set:

• Lowercase letters a through z
• Digits 0 through 9
• Hyphen -
• Period .
• Plus sign +

Package names MUST NOT contain uppercase letters, whitespace, underscores, or any character outside the set above.

§2.1.2 Structural constraints

Package names MUST start with a lowercase letter or digit.

Package names MUST end with a lowercase letter or digit.

Package names MUST NOT contain two consecutive separator characters (--, .., ++, -., .+, etc.).

Package names MUST be at least 2 characters long.

Package names MUST NOT exceed 64 characters.

§2.1.3 Case sensitivity

Package names are case-sensitive. Because uppercase letters are forbidden, this is equivalent to byte-for-byte equality.

§2.1.4 Filename convention

A package file's name on disk and in URLs MUST follow the format:

<name>_<version>_<architecture>.peipkg

Where:

• <name> is the package name.
• <version> is the full version string (§2.2).
• <architecture> is the architecture identifier (§2.3).
• The separator between fields is the underscore (_).
• The file extension is .peipkg.

Examples:

nginx_1.26.2-3_x86_64.peipkg
jq_1.7.1-2_x86_64.peipkg
peios-docs_0.22-1_noarch.peipkg
libstdc++_13.2.1-4_x86_64.peipkg

The underscore separator is REQUIRED and MUST NOT appear within any field. This makes filenames unambiguously parseable: the first underscore separates name from version, the last underscore separates version from architecture.

§2.1.5 Sub-package conventions

Packages that ship related but separable content SHOULD be named using a hyphen-suffix convention:

These conventions are advisory. The package format does not enforce them, and other suffixes MAY be used for other purposes.

Each package has a version string that uniquely identifies a build of that package. Version strings have a defined structure and a defined comparison order so that "newer" and "older" are unambiguous.

§2.2.1 Structure

A version string has the form:

[<epoch>:]<upstream>-<peios_revision>

The components are:

• Epoch: An OPTIONAL non-negative integer, separated from the rest of the version by a colon. If absent, the epoch is treated as 0.
• Upstream: The version string assigned by the upstream project, or for Peios-native software, the version assigned by Peios as the vendor.
• Peios revision: A REQUIRED positive integer identifying the build of this upstream version produced by the Peios project.

Examples:

1.26.2-3            upstream 1.26.2, peios revision 3
1.26.2-rc.1-1       upstream 1.26.2-rc.1, peios revision 1
2:0.5.0-1           epoch 2, upstream 0.5.0, peios revision 1
0.22-1              upstream 0.22, peios revision 1 (peios-native)

§2.2.2 Epoch

The epoch is a non-negative integer. It MUST be encoded as ASCII decimal digits with no leading zeros, except that the value zero is encoded as the single digit 0.

The epoch separator is a single colon (:).

Epoch is used solely to override the natural ordering of upstream version strings when an upstream version regression makes a later release compare as "older" than an earlier one.

Bumping the epoch SHOULD be a deliberate, documented decision. Routine version updates MUST NOT bump the epoch.

§2.2.3 Upstream version

The upstream version is the portion of the version string between the optional epoch separator and the final hyphen that precedes the peios revision.

The upstream version MUST consist of ASCII characters from the following set:

• Lowercase and uppercase letters a through z, A through Z
• Digits 0 through 9
• Period .
• Plus sign +
• Hyphen -
• Tilde ~

The upstream version MUST start with a digit or a letter.

The upstream version MUST NOT contain whitespace or any character outside the set above.

§2.2.4 Peios revision

The peios revision is a positive integer. It MUST be encoded as ASCII decimal digits with no leading zeros.

The revision is incremented when the Peios project produces a new build of the same upstream version. Reasons include security-patch backporting, build configuration changes, dependency updates, and packaging fixes.

The first revision of any upstream version MUST be 1. Revision 0 is reserved and MUST NOT appear in published packages.

§2.2.5 Parsing

A version string is parsed as follows:

1. If the string contains a colon, split at the first colon. The portion before the colon is the epoch; the portion after is the remainder.
2. Otherwise, the epoch is 0 and the remainder is the entire string.
3. Split the remainder at the last hyphen. The portion after the last hyphen is the peios revision; the portion before is the upstream version.
4. The peios revision MUST parse as a positive integer.
5. The upstream version MUST conform to the character set and structural constraints above.

A version string that does not parse is INVALID. An implementation MUST reject invalid version strings.

§2.2.6 Comparison

Two version strings A and B are compared as follows:

1. Compare epochs as integers. If they differ, the version with the higher epoch is greater.
2. If equal, compare upstream versions using the upstream comparison algorithm (§2.2.7).
3. If equal, compare peios revisions as integers. The version with the higher revision is greater.
4. If all three are equal, the versions are equal.

§2.2.7 Upstream comparison

Upstream version strings are compared by tokenisation and segment-wise comparison.

§2.2.7.1 Tokenisation

A tokeniser walks the upstream string left to right and emits a sequence of segments. Segments are emitted as follows:

1. Non-alphanumeric characters (., +, -, ~) are separators and are not part of any segment.
2. A maximal run of digits forms a numeric segment.
3. A maximal run of letters forms an alphabetic segment.
4. A transition between a digit and a letter ends the current segment and begins a new one.

The tilde character (~) is a special separator: the segment immediately following a tilde, and every segment after it, are pre-release segments regardless of their content (the precise rule is §2.2.7.3).

§2.2.7.2 Segment comparison

Two segments are compared as follows:

1. If both segments are numeric: compare as integers. Leading zeros are insignificant.
2. If both segments are alphabetic: compare by pre-release rank (defined below). When both ranks are equal:
   • If the rank is 0–4 (a recognised pre-release rank), the segments are equivalent. The rank table assigns multiple tokens to a single rank as aliases (alpha and a both at rank 1, beta and b both at rank 2); two segments at the same recognised rank sort equal regardless of which alias appears in the version string.
   • If the rank is 5 (no recognised pre-release token), the segments tiebreak by ASCII byte order amongst other rank-5 tokens.
3. If one segment is numeric and the other is alphabetic:
   • If the alphabetic segment is a pre-release segment, the alphabetic segment is less than the numeric segment.
   • If the alphabetic segment is not a pre-release segment, the numeric segment is less than the alphabetic segment.

The pre-release rank assigns the following well-known tokens explicit ordinal values (lowest to highest):

Any other alphabetic token has rank 5 and is compared lexically against other rank-5 tokens.

Comparison is case-insensitive for pre-release rank lookup (Alpha and ALPHA both rank 1).

1.0~alpha-1 == 1.0~a-1       # both rank 1
1.0~beta-1  == 1.0~b-1       # both rank 2
1.0~Alpha-1 == 1.0~ALPHA-1   # case-insensitive recognition (both rank 1)
1.0-foo-1   <  1.0-zzz-1     # rank-5 lex tiebreak

§2.2.7.3 Pre-release segments

A segment of the upstream version is a pre-release segment if it falls at or after the earlier of:

• the first ~ separator — the tilde and every segment following it; or
• the first recognised pre-release token: a segment whose token has a rank of 0–4 (§2.2.7.2) — that segment and every segment following it.

Once the pre-release tail begins it extends to the end of the upstream version: every later segment is a pre-release segment, whatever the separators between them. A - separator is an ordinary separator (§2.2.7.1); it is not itself a pre-release marker.

§2.2.7.4 End-of-string handling

When one segment sequence is shorter than the other:

1. If the next segment in the longer sequence is numeric, the shorter sequence is less than the longer sequence.
2. If the next segment in the longer sequence is alphabetic and a pre-release segment, the shorter sequence is greater than the longer sequence.
3. If the next segment in the longer sequence is alphabetic and not a pre-release segment, the shorter sequence is less than the longer sequence.

[!INFORMATIVE] Examples:

A	B	Result	Rule
1.0	1.0.1	A < B	numeric extension
1.0	1.0-rc.1	A > B	pre-release suffix
1.0	1.0.alpha	A > B	pre-release alphabetic
1.0	1.0a	A > B	pre-release token

§2.2.8 Constraints

Version constraints (used by dependencies, see §4.1) use standard relational operators:

Multiple constraints on the same dependency are combined with logical AND. Comma is the AND separator.

Examples:

libssl >= 3.0
libssl >= 3.0, < 4.0
nginx = 1.26.2-3

A constraint without an operator (a bare version) is equivalent to =.

A constraint's version operand MAY omit the -revision that a complete version string otherwise requires (§2.2.5). An operand written without a revision — such as >= 3.0 — constrains the epoch and upstream version only: a candidate satisfies it whenever its epoch and upstream version satisfy the operator, whatever the candidate's revision. An operand written in full constrains the revision as well.

§2.2.9 Stability across versions

A final version of this specification freezes the version comparison algorithm. An implementation conforming to this specification version MUST produce identical comparison results to any other conforming implementation for any pair of valid version strings.

A package's architecture identifies the target hardware instruction-set architecture for which the package's binaries were built. Architecture is a separate identifier from the package name and the version string.

§2.3.1 Identifier format

An architecture identifier MUST consist of ASCII characters from the following set:

• Lowercase letters a through z
• Digits 0 through 9
• Underscore _

The identifier MUST start with a lowercase letter.

The identifier MUST NOT exceed 16 characters.

§2.3.2 Canonical architectures

The following architecture identifiers are defined by this specification:

Implementations MUST recognise these identifiers.

x86_64 is the primary target architecture for Peios. All other architectures are SECONDARY targets in this version of the specification.

§2.3.3 Architecture triplets

Each architecture identifier has a corresponding triplet form used in install paths where libraries and other arch-specific resources are namespaced by architecture (see §3.4 for payload paths).

The triplet form is constructed as:

<identifier>-linux-peios

The noarch identifier has no triplet form. Architecture- independent payload MUST NOT be installed under arch-namespaced paths.

§2.3.4 Architecture-independent packages

The noarch identifier denotes packages whose payload contains no architecture-dependent binaries. Typical contents include documentation, configuration templates, scripts written in interpreted languages, and packages whose payload is metadata-only.

A noarch package MAY be installed on any system regardless of that system's hardware architecture.

A package MUST NOT use the noarch identifier if its payload contains compiled binaries, shared libraries, or any other content whose semantics depend on the target architecture.

§2.3.5 Resolution

Each Peios system has a single primary architecture, identified at install time and recorded in the system's package database state.

A package whose architecture matches the system's primary architecture MAY be installed.

A package whose architecture is noarch MAY be installed on any system.

A package whose architecture differs from the system's primary architecture and is not noarch MUST NOT be installed.

§2.3.6 Future architectures

Additional architecture identifiers MAY be defined in future versions of this specification. New identifiers MUST follow the format constraints above (§2.3.1) and SHOULD use the canonical Linux machine name (the value reported by uname -m) when one exists.

§2.3.7 Filename position

The architecture identifier appears in the package filename as the third field, separated from the version by a single underscore (§2.1.4):

<name>_<version>_<architecture>.peipkg

The architecture identifier appears in the package URL as part of the package filename (§6.4):

/p/<name>/<version>/<name>_<version>_<architecture>.peipkg

A package is a single file containing the package's payload and metadata. The on-wire form of a package is a Zstandard- compressed tar archive.

§3.1.1 File extension

The package file extension MUST be .peipkg. The full file is a tar archive compressed with Zstandard.

§3.1.2 Tar format

The tar archive MUST conform to the POSIX pax interchange format (IEEE Std 1003.1-2017, Chapter 14).

§3.1.3 Compression

The tar archive MUST be compressed using the Zstandard format (RFC 8478).

The compression level is at the producer's discretion. zstd is deterministic at all levels per RFC 8478; producers MAY choose any level based on their build-time versus decompression-time tradeoff. Higher levels (19 and above, including --ultra) increase build time substantially in exchange for smaller on-wire size; level 3 is a common default.

The compressed result is a single file with the .peipkg extension. There is no intermediate .tar form on disk; the producer's tooling produces the compressed form directly.

§3.1.4 Determinism

A package MUST be reproducible: given identical source inputs, identical build environment, and identical metadata (including the build timestamp recorded in the manifest), two independent producers MUST produce byte-identical package files.

To achieve this, the tar archive MUST follow these rules:

1. Tar entries MUST be ordered lexicographically by path. Comparison is byte-for-byte over the UTF-8 path string.
2. Every tar entry's modification time MUST equal the value of build.timestamp in the manifest (§3.3).
3. Every tar entry's owner numeric ID and group numeric ID MUST be 0 (root).
4. Every tar entry's owner name and group name MUST be the string root.
5. Tar entries MUST NOT carry extended attributes (xattrs). File security descriptors (PSD-004 §3.12) are applied at file-creation time via the kernel's file-creation interface (PSD-004 §11.2), supplied either by inheritance from the parent directory or from a manifest-declared override. See §3.4 for the SD application procedure. Other install-time attributes are applied via side-effect declarations (§4.3) or by higher-level integration mechanisms outside this specification.
6. Tar entry permission bits MUST be 0777 for every entry, with the setuid and setgid bits cleared (§3.4.6).
7. PAX extended header records, when present, MUST be in a fixed canonical order: path first, then linkpath if present, then any other records sorted by record name lexicographically.
8. Tar header magic MUST be ustar\0 and version MUST be 00.
9. Tar header devmajor and devminor fields MUST be 0 for all entry types defined by this specification (none of which are device entries).
10. Tar header padding bytes MUST be NUL (0x00).
11. PAX global header records (typeflag g) MUST NOT appear in the archive.
12. PAX extended header records (typeflag x) MUST appear only when an entry's path exceeds the ustar 100-byte limit (in which case a path record is emitted) or its linkname exceeds the ustar 100-byte limit (in which case a linkpath record is emitted). Records with any other key MUST NOT be emitted.

§3.1.5 Streaming

A consumer MAY process the archive as a stream. The internal layout (§3.2) is designed so that metadata appears before payload, allowing a consumer to read the manifest and decide whether to continue without buffering the entire payload.

§3.1.6 Top-level structure

The compressed tar archive contains entries laid out according to the internal layout in §3.2. There is no additional outer wrapping (no enclosing directory, no multi-archive concatenation, no container metadata outside the tar entries themselves).

The contents of a package's tar archive are divided into metadata entries (under a reserved prefix) and payload entries (the files that will be installed on the target system).

§3.2.1 Reserved metadata prefix

All metadata entries MUST appear under the path prefix .peipkg/ at the archive root. This prefix is RESERVED: payload entries MUST NOT use any path beginning with .peipkg/.

§3.2.2 Required metadata entries

Every package MUST contain the following entries:

§3.2.3 Entry ordering

Tar entries MUST appear in the archive in the following order:

1. .peipkg/manifest.json
2. .peipkg/files.json
3. All payload entries, sorted lexicographically by path (per §3.1.4)
4. .peipkg/signature

The manifest appears first so that streaming consumers can read the package's identity and reject mismatched packages (wrong name, wrong version, wrong architecture) before reading the payload.

The signature appears last and signs the archive content preceding it (§5.1 specifies what is signed and how).

§3.2.4 Optional metadata entries

A package MAY include additional entries under .peipkg/ for forward-compatible extensions. The set of entries recognised by this specification is fixed (the three above); unrecognised entries under .peipkg/ MUST be ignored on parse but MUST NOT prevent installation.

When present, optional metadata entries MUST appear between .peipkg/files.json and the first payload entry, sorted lexicographically by path.

§3.2.5 Payload entries

Payload entries are tar entries with paths that do not begin with .peipkg/. These are the files, directories, and symlinks that the package installs on the target system.

§3.2.6 Permitted entry types

Tar payload entries MUST be of one of the following types:

• Regular file (typeflag 0 or \0)
• Directory (typeflag 5)
• Symbolic link (typeflag 2)

Tar entries of any other type MUST cause the package to be rejected. This explicitly excludes:

• Hardlinks (typeflag 1)
• Character devices (typeflag 3)
• Block devices (typeflag 4)
• FIFOs (typeflag 6)
• Contiguous files (typeflag 7)
• Vendor-specific types

§3.2.7 Payload path constraints

Payload paths MUST be relative (MUST NOT begin with /).

Payload paths MUST NOT contain any segment equal to . or .. or any encoding thereof.

Payload paths MUST be valid UTF-8 (RFC 3629).

Payload paths MUST NOT contain NUL bytes (0x00) or any ASCII control character (0x01-0x1F, 0x7F).

Payload paths MUST NOT contain backslash (\) characters.

Payload paths MUST be in Unicode Normalization Form C (NFC) per Unicode 16.0.

Each path component MUST be at most 255 bytes long when encoded as UTF-8.

A complete payload path MUST be at most 4096 bytes long when encoded as UTF-8.

A payload path MUST NOT begin with the prefix .peipkg/, or with .peipkg followed by end-of-path (i.e., no payload entry may be literally named .peipkg).

A consumer MUST validate every payload path against these constraints before any further processing of the entry. A package containing a non-conforming payload path MUST be rejected.

The on-disk install location is the payload path resolved against the filesystem root. Path resolution MUST NOT canonicalise away .. or . segments by interpretation; such segments are forbidden in the input (above) and any appearance is a format error, not a path-canonicalisation question.

§3.2.8 Empty package payloads

A package MAY have zero payload entries. A package with no payload contains only metadata; its install operation is limited to recording the package in the system database and running any side-effect declarations (§4.3).

§3.2.9 Resource limits

To bound consumer-side resource usage during package parsing, the format establishes minimum-conformance limits. A consumer MUST process packages whose characteristics fall within these limits and MUST reject packages that exceed them.

A consumer MAY raise these limits via operator configuration but MUST NOT raise them silently; operator-tuned values SHOULD be logged and surfaced in diagnostic output.

A producer SHOULD stay well below these limits in practice. The limits exist to bound consumer resource usage when processing maliciously-crafted packages, not to define the typical scale of a well-formed package.

The manifest is the authoritative metadata for a package. It declares the package's identity, dependencies, side-effect requirements, and build provenance.

The manifest is a JSON document stored at .peipkg/manifest.json inside the package archive. It MUST conform to RFC 8259 and to the schema defined in this section.

§3.3.1 Top-level schema

{
  "schema_version": 1,
  "name": "<string>",
  "version": "<string>",
  "architecture": "<string>",
  "description": "<string>",
  "license": "<string>",
  "homepage": "<string>",
  "dependencies": [<dependency>...],
  "optional_dependencies": [<dependency>...],
  "conflicts": [<dependency>...],
  "provides": [<provides>...],
  "replaces": [<replaces>...],
  "side_effects": [<string>...],
  "size_installed": <integer>,
  "sd_overrides": [<sd_override>...],
  "build": {<build>}
}

§3.3.2 Required fields

A manifest missing any required field MUST be rejected as invalid.

§3.3.3 Optional fields

A manifest containing an unknown field MUST NOT be rejected; the unknown field MUST be ignored. This permits forward- compatible extension.

§3.3.4 Build object

{
  "timestamp": "<RFC 3339 timestamp>",
  "farm_id": "<string>",
  "source_ref": "<string>"
}

The timestamp is also the value used for every tar entry's modification time (§3.1.4). Producers MUST set both identically.

The source_ref form is producer-defined but SHOULD be a machine-resolvable reference. The conventional form is a git URL with explicit ref:

git+https://git.peios.org/sources/nginx#refs/tags/v1.26.2-3

§3.3.5 SD override object

A single entry in sd_overrides has the form:

{
  "path": "<payload-relative path>",
  "sd": "<base64-encoded SD>"
}

The path value MUST refer to a regular-file entry or a directory entry in the tar archive. SD overrides MUST NOT target symlink entries.

An override referring to a non-existent payload entry, or to a symlink entry, is INVALID and MUST cause the package to be rejected.

The sd value MUST decode to a syntactically valid binary self-relative SD per PSD-004 §3.12. An override whose decoded SD bytes do not parse is INVALID and MUST cause the package to be rejected.

The sd_overrides array MUST be sorted lexicographically by path.

§3.3.6 Field constraints

The description field, when present, SHOULD be a single line under 80 characters. Longer descriptions belong in upstream documentation, not the manifest.

The license field, when present, SHOULD be a valid SPDX license expression. The producer MAY use other forms; the specification does not validate license strings.

The homepage field, when present, MUST be a syntactically valid URL per RFC 3986.

The size_installed field MUST be a non-negative integer expressing bytes. It is the total size of the installed payload (the sum of all regular-file size fields in files.json), used by consumers for disk-space planning (§7.1.2.2) and decompression-bound enforcement (§3.5.4).

The description field MUST consist only of printable ASCII characters in the range 0x20-0x7E. ASCII control characters and non-ASCII bytes MUST NOT appear in the description. This prevents terminal escape-sequence injection when the description is shown to operators.

The homepage field, when present, MUST use the https or http URL scheme. Other schemes (javascript:, file:, data:, etc.) MUST cause the package to be rejected.

§3.3.7 Authoritative status

The manifest is authoritative for the package's metadata. If the manifest disagrees with any other source (the repository index, the package filename, secondary documentation), the manifest MUST be treated as correct.

§3.3.8 Encoding

The manifest MUST be UTF-8 encoded JSON. The file MUST end with a single newline character.

The manifest MAY be pretty-printed (with whitespace and indentation) or compact. Whitespace differences do not affect semantics. For reproducibility, a producer SHOULD choose one canonical form and use it consistently.

The payload is the set of files, directories, and symlinks that a package installs on the target system. This section specifies the install paths, permissions, and structural conventions that payload entries MUST follow.

§3.4.1 Filesystem layout

Peios uses a usrmerged filesystem layout: the historical distinction between /bin and /usr/bin, between /lib and /usr/lib, and between /sbin and /usr/sbin does not exist. Packages MUST install only under /usr/, with exceptions for conventional system paths listed below.

Permitted top-level install destinations:

Payload entries MUST NOT install under any other top-level path.

Entries installed under /boot/ SHOULD be symlinks whose targets resolve to a regular file under one of the other permitted top-level destinations — typically /usr/lib/<triplet>/ for the canonical arch-specific kernel image, initramfs, or device tree. The intent is that /boot/ is a discovery directory the bootloader reads, not a storage directory where real package content lives. This is a SHOULD rather than a MUST because edge cases exist (recovery images, embedded bootloader integrations that cannot follow symlinks) where shipping a real file under /boot/ is the right call; the format-level validator does not enforce the symlink rule.

§3.4.2 Architecture triplet for libraries

Packages whose architecture is not noarch MUST install all of the following under /usr/lib/<triplet>/ where <triplet> is the architecture triplet defined in §2.3.3:

• Shared libraries (.so, .so.*)
• Static libraries (.a)
• Loadable modules (plugin shared objects, kernel modules outside of /usr/lib/modules/)
• Helper binaries not on user PATH (libexec-style content)
• Any other arch-dependent files that are not user-facing binaries

Packages whose architecture is noarch MUST NOT install any files under /usr/lib/<triplet>/. A noarch package whose contents includes any of the above categories is INVALID.

§3.4.3 Architecture-independent data

The /usr/share/ tree holds architecture-independent files shared across all architectures of a system. Typical content:

• Documentation (/usr/share/doc/<package>/)
• Man pages (/usr/share/man/<section>/)
• Locales (/usr/share/locale/)
• Default configuration templates (/usr/share/<package>/)
• Static data (icons, images, fonts)

Both noarch packages and arch-specific packages MAY install under /usr/share/. Files installed by an arch- specific package under /usr/share/ MUST be byte-identical across architecture builds of the same upstream version.

§3.4.4 Configuration files

Default configuration files MAY be installed under /etc/. Configuration files installed by a package are referred to as seed configuration: they represent the package's defaults, not the running system's effective configuration.

The package format does not distinguish "config files" from other files at the format level. Reconcillers and higher- level integration mechanisms determine which /etc/ files are managed and how.

§3.4.4.1 Drop-in directories

Several /etc/ subdirectories are drop-in directories: their contents are interpreted as code or configuration by other tools (notably side-effect tools per §4.3 and system daemons that read configuration drop-ins). A package writing to a drop-in directory has indirect influence on the behaviour of other components that read those drop-ins.

Packages from non-official repositories MUST NOT install files at the top level of any of the following drop-in directories. The list MAY be extended by operator configuration:

• /etc/ld.so.conf.d/
• /etc/profile.d/
• /etc/sudoers.d/
• /etc/cron.d/, /etc/cron.daily/, /etc/cron.hourly/, /etc/cron.weekly/, /etc/cron.monthly/
• /etc/sysctl.d/
• /etc/modules-load.d/
• /etc/modprobe.d/
• /etc/binfmt.d/
• Any directory the system declares as a drop-in directory via a registry-managed list

The drop-in directory list MUST be stored in a registry key (or equivalent file) under a security descriptor that grants write access only to a recovery-class operator principal, not to the package manager principal itself. Operator configuration MAY add entries to the list but MUST NOT remove entries required by this specification; the list is purely additive.

A non-official-repo package whose payload installs to one of these paths MUST be rejected at install time.

A non-official-repo package MAY install drop-in files under its own subdirectory of the drop-in path (e.g., /etc/ld.so.conf.d/peios-<repo-name>/<package>.conf) provided that:

• The subdirectory is namespaced by the repository's name and the package's name to prevent collision.
• The package's sd_overrides (§3.3.5) reflect the intent that the subdirectory's contents are attributable to a specific non-official-repo package.
• Side-effect tools that consume the drop-in directory are configured to require the operator's explicit acknowledgement of non-official drop-ins (operational policy outside this specification).

§3.4.5 Variable state directories

A package MAY install empty directories under /var/ to establish locations its runtime will write to (e.g., /var/log/<service>/, /var/lib/<service>/).

A package MUST NOT install populated content under /var/. Variable state is owned by the runtime, not the package.

§3.4.6 Permissions

Tar entry permission bits in a peipkg are distribution-format metadata only. They do not establish access control on the installed file. Access control is the consumer's responsibility: on Peios, via KACS (PSD-004) applied at file-creation time per §3.4.7; on other systems extracting a package for inspection or migration, via that system's native mechanism applied after extraction.

Tar entry permission bits MUST be 0777 (octal) for every payload entry. Any other value MUST cause the package to be rejected.

The setuid and setgid bits MUST NOT be set on payload entries. Privilege escalation on Peios is mediated by KACS, not by filesystem-level setuid; setuid bits are meaningless to the access-check path and MUST NOT appear in installed content.

§3.4.7 Security descriptors

Each installed file or directory has a security descriptor as defined in PSD-004 §3.12. The package manager applies SDs at file-creation time via the kernel's file-creation interface (PSD-004 §11.2), not via tar attributes (§3.1.4).

§3.4.7.1 Default: inheritance

When a payload entry has no manifest-declared SD override (§3.3.5), the package manager MUST create the entry without supplying an explicit SD. The kernel computes the new entry's SD by inheritance from the parent directory's inheritable ACEs at creation time (PSD-004 §3.6).

Inheritance is the default for the overwhelming majority of installed entries. Most packages declare no SD overrides at all.

§3.4.7.2 Manifest-declared overrides

When a payload entry has a corresponding entry in the manifest's sd_overrides array (§3.3.5), the package manager MUST create the entry with the explicit SD supplied via the kernel's file-creation interface.

Overrides are appropriate when:

• A file or directory requires more restrictive permissions than its inherited SD provides
• A file requires explicit access for a service principal that does not appear in the parent directory's inheritable ACEs
• A directory's inheritable ACEs need to differ from those of its own parent (creating a new inheritance scope)

§3.4.7.3 SD override policy

KACS (PSD-004) validates the syntactic well-formedness of a declared SD but does NOT validate that the producer of the package had authority to declare that SD on behalf of the SIDs it grants access to. A package can therefore declare an SD that grants access to any service principal known to the system. The package format treats the SD bytes as opaque; the policy of "should this package be allowed to declare this SD?" is enforced at install time by the package manager, not by the kernel.

The policy applies both to explicitly declared SDs (via sd_overrides) AND to SDs that result from inheritance from a directory whose own SD was declared via any package's sd_overrides. Specifically: when a package extraction creates a file under a directory whose SD was overridden by any sd_overrides declaration (the declaring package may be from any repository), the resulting inherited SD MUST pass the policy hook below as if it were declared by the inheriting package. This prevents "cross-package SD inheritance" from bypassing the operator-confirmation gate, and explicitly closes the edge case where a carefully-mimicked "looks-like- default" override would have evaded a non-system-default test.

A package manager MUST enforce a per-repository SD-override policy:

1. Before applying any sd_overrides entry, the package manager MUST surface the override to the operator in human-readable form. The display MUST include the payload path, the SIDs and rights granted by the override, and a diff against what the inherited SD would have produced.

2. For packages from the official Peios repository, SD overrides MAY be applied without per-operation confirmation, but the operator-visible install report MUST list every override applied.

3. For packages from custom repositories, the package manager MUST require explicit operator confirmation before applying any sd_overrides entry that grants rights to SIDs outside a configured allowlist. The default allowlist contains:

   • The well-known SIDs defined by PSD-004 (SYSTEM, Administrators, etc.).
   • SIDs explicitly added to the per-repository allowlist by operator configuration.

   The default allowlist MUST NOT include any SID derived from the package itself (manifest fields, build metadata, or payload content). A package cannot self-elect SIDs into the allowlist; doing so would defeat the policy hook by letting any package declare its own privileged principal.

4. A package whose sd_overrides are rejected by the policy MUST be refused at install time. The package manager MUST NOT silently drop overrides and proceed with inheritance defaults.

§3.4.7.4 Symlinks

Symlinks do not carry independent SDs. Access to a symlink is governed by access to its target. SD overrides MUST NOT target symlink payload entries (§3.3.5).

§3.4.7.5 Failure handling

If file creation fails because the explicit SD is rejected by the kernel (for example, because it references a SID that does not exist in the system's KACS state), the package manager MUST treat the install as failed and roll back any partial state. The handling of failed installs is specified in §7.

A package MUST NOT install to a parent directory whose SD denies the package manager the access required to create the entry. This condition is detected at install time and treated as an install failure.

§3.4.8 Symlinks

Symlinks are first-class payload entries. The tar entry's linkname is the symlink target.

§3.4.8.1 Symlink target constraints

Symlink targets MUST be relative paths.

Symlink targets MUST resolve, when joined with the symlink's parent directory, to a path that is either within the package's own payload tree or under one of the permitted top-level install destinations listed in §3.4.1. Absolute targets, and targets whose resolution escapes §3.4.1's permitted destinations entirely (e.g., landing under /tmp/, /home/, /srv/, or /), are FORBIDDEN.

Symlink targets are subject to the same path-validity constraints as payload paths (§3.2.7): valid UTF-8, no NUL bytes, no ASCII control characters, no backslashes, NFC normalisation, length limits.

A consumer MUST validate symlink targets against these constraints before extracting the entry. A package containing a non-conforming symlink target MUST be rejected.

Producers MAY emit symlinks whose target resolves into a different package's payload tree, provided the resolved path is under §3.4.1's permitted destinations. The canonical use case is the conventional Linux library split, where a -dev package contains a developer-link symlink (e.g. libfoo.so) whose target (e.g. libfoo.so.1) lives in the corresponding runtime package. Producers SHOULD declare the target's owning package as a dependency so that the target is guaranteed present at extraction time. The format does not require producers to record this dependency relationship at the symlink level; it is captured at the package level via the dependencies field (§3.3.2).

§3.4.8.2 Symlink integrity

Symlink targets are integrity-checked via the tar entry's linkname directly during extraction. The linkname stored in the tar header is the bytes the consumer compares; it is not separately hashed in files.json because symlinks have no content body.

§3.4.9 Empty directories

A package MAY install empty directories. Empty directories are tar entries of type directory with no content. They are useful for establishing required paths for runtime state.

§3.4.10 Conflict prevention

Two packages MUST NOT install files at the same install path. Such a conflict is detected at install time (§7.1) and rejected.

A package MAY install content into a directory created by another package; directory creation is idempotent. Conflict applies to non-directory entries only.

§3.4.11 Forward compatibility with multi-architecture systems

The architecture triplet path convention (§3.4.2) is designed so that a future multi-architecture system MAY install packages of foreign architectures alongside native ones without filesystem-level collisions.

In v0.22 of this specification, only one architecture's packages may be installed on a given system at a time (§2.3.5). The triplet path convention applies regardless, to ensure that a v0.22-conformant package is forward- compatible with a future multi-architecture extension.

A package's integrity is verified at two levels:

• The package level: the entire .peipkg file has a hash and a signature that prove the file as a whole has not been altered since it was signed.
• The per-file level: each payload file has an individual hash that proves the file's content has not been altered between archive creation and installation.

§3.5.1 Per-file integrity manifest

Each package's tar archive contains a per-file integrity manifest at .peipkg/files.json. The integrity manifest is a JSON document conforming to the schema in this section.

§3.5.1.1 Schema

{
  "schema_version": 1,
  "algorithm": "sha256",
  "entries": [
    {
      "path": "<string>",
      "size": <integer>,
      "hash": "<hex string>"
    }
  ]
}

§3.5.1.2 Entry schema

The entries array MUST be sorted lexicographically by path.

§3.5.1.3 Coverage

The integrity manifest MUST contain exactly one entry per regular-file payload entry in the tar archive. It MUST NOT contain entries for:

• Metadata entries under .peipkg/
• Directory entries
• Symlink entries

A regular-file payload entry without a corresponding entry in the integrity manifest, or an entry in the integrity manifest without a corresponding tar entry, is INVALID and MUST cause the package to be rejected on parse.

§3.5.2 Package hash

The package hash is the hash of the entire .peipkg file (the compressed tar archive) computed with the algorithm declared in the repository index (§6.2). The default and required-supported algorithm is SHA-256.

The package hash is recorded in:

• The repository index (§6.2), to verify the downloaded file matches what the repo advertises.
• The signature payload (§5.1), to bind the signature to this exact file.

The package hash is NOT recorded inside the package itself. A package cannot contain its own hash.

§3.5.3 Verification flow

A consumer verifying a package MUST perform the following steps in order:

1. Compute the SHA-256 of the downloaded .peipkg file.
2. Compare against the hash recorded in the repository index (§6.2). If they differ, the package is corrupted or substituted; abort.
3. Verify the inline signature (§5.3). If verification fails, the package's authenticity is unproven; abort.
4. Decompress and parse the tar archive.
5. Read .peipkg/manifest.json and verify it parses against the schema in §3.3.
6. Read .peipkg/files.json and verify it parses against the schema in §3.5.1.
7. For each payload entry: compute its content hash and compare against the corresponding entry in .peipkg/files.json. If any file's hash does not match, abort.
8. The package is verified.

A consumer MUST NOT install any payload before all eight steps complete successfully. Partial installation in the event of verification failure leaves the system in an indeterminate state and is forbidden.

A consumer MUST NOT make any decompressed payload bytes visible to other processes (including via staging directories that are reachable from outside the package manager's own process tree) before signature verification (step 3) has succeeded. Streaming decompression and hashing is permitted; observable filesystem effects are not.

§3.5.4 Decompression bounds

A consumer MUST enforce upper bounds on package decompression to prevent resource-exhaustion attacks via maliciously-constructed packages with extreme compression ratios.

Two bounds apply:

1. The repository index entry's size_compressed and size_installed fields (§6.2.4) bound the legitimate sizes of the compressed and uncompressed forms. A consumer MUST verify, during streaming decompression, that:
   • the cumulative compressed bytes consumed do not exceed size_compressed by more than the lesser of 1% or 16 MiB;
   • the cumulative decompressed bytes produced do not exceed size_installed plus a fixed overhead allowance of 320 MiB. The allowance accommodates tar header and block-padding overhead and the metadata files; it is sized so that no package conforming to the §3.2.7 resource limits is ever rejected.
2. Independent of index-declared sizes, a consumer MUST abort decompression if the cumulative decompressed output exceeds an absolute cap. The default absolute cap is 4 GiB; the cap MAY be raised by operator configuration but MUST NOT be raised silently.

Exceeding either bound MUST cause the package to be rejected with no further processing and no payload committed to disk.

§3.5.5 Hash algorithm agility

This version of the specification supports SHA-256 only.

The algorithm field in .peipkg/files.json and the hash identifier in the repository index reserve syntactic space for future algorithms. A future version of this specification MAY introduce additional algorithms; consumers of v0.22 MUST reject any algorithm value other than sha256.

§3.5.6 Tampering and partial trust

The two-level integrity model defends against different threats:

• The package hash plus signature defends against malicious substitution of the package as a whole.
• The per-file integrity manifest defends against corruption or tampering during extraction, after the signature has been verified.

A consumer MUST verify both levels. Verifying only the package signature without checking per-file hashes leaves extraction errors and on-disk corruption undetectable; verifying only per-file hashes without checking the signature leaves the manifest itself untrusted.

A package's relationships to other packages are expressed in five fields of the manifest:

• dependencies: packages that MUST be installed for this package to function.
• optional_dependencies: packages that enhance functionality but are not required.
• conflicts: packages that MUST NOT be installed alongside this one.
• provides: virtual names this package satisfies on behalf of dependencies declared elsewhere.
• replaces: packages this one supersedes (typically used for renames).

This section defines the schema and syntax of entries in these fields.

§4.1.1 Dependency object

A single entry in dependencies or optional_dependencies has the form:

{
  "name": "<package or virtual name>",
  "constraint": "<version constraint>",
  "arch": "<arch qualifier>"
}

A dependency object MUST contain at least the name field. Other fields are optional.

§4.1.2 Conflict object

A single entry in conflicts has the form:

{
  "name": "<package name>",
  "constraint": "<version constraint>",
  "arch": "<arch qualifier>"
}

Field semantics are identical to the dependency object, except that the entry expresses incompatibility rather than requirement: a package with a conflicts entry MUST NOT be installed simultaneously with any package matching that entry.

A conflict whose constraint is absent expresses incompatibility with any version of the named package.

§4.1.3 Architecture qualifier

The arch field on a dependency or conflict entry restricts the qualified package's architecture.

In this version of the specification, the only valid value is any, which is the default. any means: the qualified package's architecture MUST equal the depending package's architecture or be noarch.

A dependency or conflict entry whose arch value is anything other than any MUST be rejected by a v0.22-conformant implementation.

§4.1.4 Provides

A single entry in provides has the form:

{
  "name": "<virtual name>",
  "version": "<version string>"
}

A virtual name in the namespace of real package names MAY be provided. When a real package name and a virtual name collide, both are valid satisfiers of dependencies on that name.

A provides.version SHOULD reflect the providing package's actual functional compatibility level. A provides.version greater than the providing package's own version SHOULD generate an operator warning at install time, since inflated provides-versions can be used to defeat constraint-based dependency resolution.

The provides relation does not transitively flow: providing smtp-server does not provide whatever smtp-server itself provides.

§4.1.5 Replaces

A single entry in replaces has the form:

{
  "name": "<package name>",
  "constraint": "<version constraint>"
}

A replaces entry expresses that this package supersedes the named package. During upgrade, the replaced package is removed and this package is installed in its place. Files owned by the replaced package that no longer exist in this package are removed; files that exist in both are updated.

A replaces entry does not imply a conflict. A package MAY replace and conflict with the same target, but typically a replaces entry is sufficient on its own to express the succession.

§4.1.6 Constraint syntax

Version constraints in constraint fields use the operators defined in §2.2.8:

=  >  >=  <  <=  !=

Multiple constraints on the same dependency are combined with logical AND, separated by commas:

">= 3.0, < 4.0"

Whitespace around operators and commas is OPTIONAL and is ignored.

A bare version string with no operator is equivalent to =:

"1.26.2-3"   ≡   "= 1.26.2-3"

A constraint string MUST parse as one or more operator-and- version expressions separated by commas. A constraint that does not parse is INVALID.

§4.1.7 Field constraints

Each of the five fields (dependencies, optional_dependencies, conflicts, provides, replaces) is an array of objects matching the appropriate schema above.

Fields MAY be empty arrays. Fields MAY be omitted from the manifest; an omitted field is equivalent to an empty array.

Within a single field, entries MUST be sorted lexicographically by name. Two entries in the same field MUST NOT have identical name values; if a package has multiple constraints on the same target, they MUST be combined into a single entry's constraint string.

Dependency resolution is the procedure by which a package manager, given a set of target packages to install or upgrade, computes the complete set of packages to install, upgrade, or remove on the target system.

This section defines the semantic requirements that a conformant resolver MUST satisfy. The exact algorithm is left to the implementation, provided the requirements are met.

§4.2.1 Inputs

A resolution operation takes the following inputs:

• The target set: zero or more requested operations (install package P, upgrade package P, remove package P).
• The installed set: the set of packages currently installed on the system, with their versions and architectures.
• The available set: the union of all packages listed in configured repository indexes (§6.2, §6.3), each annotated with the repository it came from.

§4.2.2 Output

A resolution operation produces either:

• A plan: an ordered list of operations (install, upgrade, remove) that, if applied to the installed set, satisfies the target set without violating any constraint.
• A rejection: an error explaining why no satisfying plan exists.

A plan MUST be partial-ordered such that for every install operation, all of that package's dependencies are present in the installed set or scheduled to be installed earlier in the plan.

§4.2.3 Satisfaction

A dependency is satisfied by a candidate package when ALL of the following hold:

1. The candidate's name equals the dependency's name, OR the candidate has an entry in its provides array whose name equals the dependency's name.
2. If the dependency has a constraint, the candidate's version (or, when matched via provides, the provides-entry's version) satisfies the constraint per §2.2.6.
3. The candidate's architecture matches the dependency's arch qualifier per §4.1.3.

A conflict is triggered by a candidate package when the same conditions hold with respect to a conflicts entry.

§4.2.4 Candidate selection

When multiple available packages satisfy a dependency, the resolver MUST select among them deterministically using the following rules in order:

1. Architecture match preferred over noarch: A candidate whose architecture exactly matches the system's primary architecture is preferred over a noarch candidate of the same name.
2. Same-repository provides preferred (bounded): When the dependency is being resolved for a depending package D, and a candidate from D's same repository satisfies the dependency (whether by name match or via provides), that candidate is preferred over a cross-repository candidate ONLY when D's repository has a priority equal to or higher than the cross-repository alternative. When D is from a lower-priority repository than the cross-repository candidate, this rule does NOT apply; rule 3 (higher repository priority) selects the cross-repository candidate. This prevents a low-trust depending package from pulling in low-trust transitive dependencies that shadow higher-trust alternatives.
3. Higher repository priority preferred: A candidate from a higher-priority repository is preferred over one from a lower-priority repository (repository priority is defined in §6.5).
4. Higher version preferred: A candidate with a higher version (per §2.2.6) is preferred.
5. Higher peios revision preferred (already implied by rule 4, but retained for clarity).

When the chosen candidate satisfies the dependency via provides from a lower-priority repository AND a higher-priority repository contains a name-matching package whose constraint check failed, the package manager MUST surface the substitution to the operator as a "low-trust-repo provides for high-trust-repo's role" event and require explicit operator confirmation (§7.6.6) before applying the resolution. This mirrors the explicit-confirmation requirement for non-official- repo replaces (§6.5.7).

Rule 1 ensures arch-specific builds are favoured when available. Rule 2 ensures user-controlled repo priority is respected. Rules 3 and 4 select the freshest version when multiple satisfy.

§4.2.5 Failure conditions

A resolution operation MUST fail and produce no plan if any of the following holds:

1. Unsatisfiable dependency: A package in the candidate plan has a dependency for which no available package satisfies all the satisfaction conditions (§4.2.3).
2. Active conflict: Two packages in the proposed resulting installed set (current installed minus removed plus added) trigger a conflict against each other.
3. Architecture mismatch: A package in the proposed plan has an architecture that is neither the system's primary architecture nor noarch.
4. Version regression rejected by user: An operation would result in a package's version going backward (decreasing per §2.2.6) without explicit user authorisation. Whether to reject this MAY be a per- transaction policy.
5. Cyclic dependency unbreakable by ordering: A cycle in the dependency graph that the resolver cannot resolve by plan ordering.

The resolver MUST report which condition failed and which packages or constraints were involved.

§4.2.6 Optional dependencies

Optional dependencies (§4.1) MUST NOT be included in the plan automatically. The resolver MAY surface them to the user as suggestions but MUST NOT install them without explicit instruction.

A package whose optional dependencies are not installed MUST function correctly with reduced capability. A package that does not function without an "optional" dependency has mis-categorised that dependency: it is a required dependency, not optional.

§4.2.7 Removal cascades

Removing a package whose other installed packages depend on it would leave the system in an inconsistent state. A removal operation MUST therefore either:

• Cascade: remove the dependent packages too (with explicit user authorisation), or
• Refuse: reject the removal and report the dependents that block it.

The choice between cascade and refuse MAY be a per- transaction policy.

§4.2.8 Determinism

A conformant resolver MUST produce identical plans for identical inputs. Given the same target set, installed set, and available set, the resulting plan (or rejection) MUST be deterministic.

This guarantees that "dry-run" output matches the actual plan that would be applied if the operation proceeded.

§4.2.9 Bounded resolver work

A resolver MUST bound its work to prevent denial-of- service via pathological dependency graphs. A consumer MUST either:

• Implement an algorithm whose worst-case complexity is polynomial in the size of the available set and the target set, OR
• Apply an explicit step / runtime cap that terminates resolution with a clear error when exceeded.

The default cap MUST be reachable: the resolver MUST NOT silently spin for unbounded time on a malicious input. The exact cap is implementation-defined; values producing tens-of-seconds latency on commodity hardware for typical transactions are reasonable defaults.

§4.2.10 Resolution and the index

The resolver SHOULD perform satisfaction checks and candidate selection using only data present in the repository index (§6.2). Fetching the actual .peipkg files SHOULD be deferred until after the plan is computed and the user (or calling tool) has confirmed the operation.

§4.2.11 Atomicity

The plan MUST be applied atomically: either all operations in the plan succeed, or none of them visibly take effect. If any operation fails, the package manager MUST roll back to the pre-resolution state.

The atomicity mechanism is specified in §7.4.

Some standard Linux maintenance operations need to run after files are installed or removed in order for the system to function correctly. Examples include rebuilding the shared library cache after a library is added, rebuilding the kernel module dependency cache after kernel modules change, and rebuilding the man page index after man pages are added.

These operations are not arbitrary install scripts. The package format does not permit packages to specify their own install scripts. Instead, packages declare the standard maintenance operations they require via the manifest's side_effects field, and the package manager invokes them from a fixed enumerated set.

§4.3.1 Schema

The side_effects field of the manifest is an array of strings:

"side_effects": ["ldconfig", "man-db"]

Each string MUST be drawn from the enumerated set defined in §4.3.4. Unknown values are INVALID and cause the package to be rejected.

The array MAY be empty (or the field omitted entirely) for packages that require no maintenance operations.

The array MUST NOT contain duplicate values.

§4.3.2 Semantics

The package manager invokes each declared side effect once per transaction, after the transaction's database commit (§7.4.5 step 4) — that is, after all of the transaction's file operations are in place.

Side effects are deduplicated across packages within a single transaction: if multiple packages in the same transaction declare ldconfig, the operation runs once for the transaction, not once per package.

A side effect MUST be idempotent: running it multiple times in succession MUST produce the same final system state as running it once. The fixed set of recognised side effects have this property by construction.

A side effect MUST be safe to invoke from a non-interactive context. The package manager runs side effects without user prompting.

The package manager MUST invoke side-effect tools with:

• A fixed absolute path to the tool. The recognised side effects are a closed set (§4.3.4); the package manager invokes each from its known absolute location and MUST NOT search PATH.
• A cleared environment containing only well-defined variables (e.g. LANG=C, LC_ALL=C, PATH=/usr/bin). Inherited environment from the invoking shell MUST NOT be passed through.
• Standard input closed.

§4.3.3 Failure handling

Side effects run after the transaction's database commit (§7.4.5 step 4), so a side-effect failure does not — and cannot — roll the transaction back: the transaction is already committed. If a side effect fails (the underlying tool exits non-zero or is unavailable), the package manager MUST report the failure to the operator, but the transaction stands.

Because side effects are idempotent, a failed side effect is self-correcting: re-invoking it — explicitly, or as part of the next transaction that declares it — reaches the correct state. The package manager SHOULD make a failed side effect straightforward to re-invoke.

§4.3.4 Recognised side effects

This version of the specification recognises the following side effect identifiers:

§4.3.4.1 ldconfig

Rebuilds the shared library cache (/etc/ld.so.cache) and updates symlinks for shared libraries.

A package MUST declare ldconfig in its side_effects if its payload contains any of:

• Shared library files (.so, .so.*)
• Files installed under any directory listed in /etc/ld.so.conf or its includes

A package MUST NOT declare ldconfig if its payload contains none of the above.

The package manager invokes the system's ldconfig tool with arguments equivalent to ldconfig (no flags), which scans the standard library directories and rebuilds the cache.

§4.3.4.2 depmod

Rebuilds the kernel module dependency cache (modules.dep and related files in /usr/lib/modules/<ver>/).

A package MUST declare depmod in its side_effects if its payload contains kernel module files (.ko, .ko.*) under /usr/lib/modules/.

A package MUST NOT declare depmod if its payload contains no kernel modules.

The package manager invokes depmod against the kernel version corresponding to the modules being installed. If the package contains modules for multiple kernel versions, depmod is invoked once per affected version.

§4.3.4.3 man-db

Rebuilds the man page index (/var/cache/man/index.db or equivalent), permitting fast lookup by apropos and whatis.

A package SHOULD declare man-db in its side_effects if its payload contains man pages under /usr/share/man/.

The package manager invokes the system's man-db tool with arguments equivalent to mandb -q (quiet mode).

§4.3.5 Reservation for future side effects

The set of recognised side effects in this version is deliberately small. Future versions of this specification MAY introduce additional side effects for other standard maintenance operations.

A v0.22-conformant implementation MUST reject manifests declaring side effect identifiers outside the set defined in §4.3.4.

§4.3.6 What side effects are not

Side effects are NOT:

• A general install-script mechanism. The fixed enumeration prevents arbitrary code execution at install time.
• A way to register services with peinit. Service integration is the concern of higher-level artifacts that compose packages, not of packages themselves (§1.1).
• A way to seed registry state. Registry seeds are managed by higher-level artifacts and applied by reconciller daemons, not by package install.
• A way to apply KACS xattrs or SDs. SDs are applied at file-creation time per §3.4.7.

A package whose required behavior cannot be expressed via the manifest schema (including side_effects) is incomplete and cannot be installed via the package format alone. Such behavior MUST be supplied by the higher-level artifact that composes the package.

A package signature binds a package's bytes to a signing key. Verifying the signature establishes that the package has not been altered since signing and that the signer had access to the trusted private key.

§5.1.1 Signature entry

The package signature is stored as the final entry in the tar archive at path .peipkg/signature (§3.2.3).

The entry's content is a UTF-8 JSON document conforming to the schema in §5.1.3. All tar entry attributes — permission bits, owner identity, mtime, magic, and the rest — follow the determinism rules in §3.1.4 unmodified. The signature entry is therefore mode 0777 like every other entry; the 0777 rule's "honest signalling" rationale (§3.4.6) applies identically to metadata entries.

§5.1.2 Signed payload

The signature signs a SHA-256 hash computed over the concatenation of all uncompressed tar bytes preceding the .peipkg/signature entry, in archive order.

Specifically, the signed bytes are the concatenation of:

• The complete tar entry blocks (header + content + content-block padding to the next 512-byte boundary) for every entry that precedes .peipkg/signature, in archive order.

The signed bytes do NOT include:

• The tar entry header or content of .peipkg/signature itself.
• The two trailing zero blocks that conventionally terminate a tar archive.
• Any compression artifacts (signing operates on the uncompressed tar bytes).

§5.1.3 Signature envelope

The content of .peipkg/signature is a JSON document with the following schema:

{
  "schema_version": 1,
  "algorithm": "ed25519",
  "key_fingerprint": "<hex string>",
  "signature": "<base64 string>"
}

A signature envelope MUST contain all four fields. Missing or unrecognised algorithm or schema_version values cause the package to be rejected.

The envelope MUST NOT contain extra fields. Future specification versions may extend the schema with additional fields; v0.22 implementations parsing a future envelope MUST reject the package with a clear error indicating the schema version mismatch rather than silently ignoring unknown fields. (This is a deliberate exception to the forward-compatibility rule for manifest fields (§3.3.3): for security-critical signing data, strict parsing is preferred over permissive ignoring.)

§5.1.4 Determinism

Given identical signed bytes and identical signing key, the Ed25519 signature value is deterministic per RFC 8032 §5.1.6.

A producer that builds the same tar archive (with all determinism rules per §3.1.4 satisfied) and signs with the same key MUST produce a byte-identical .peipkg/signature entry.

§5.1.5 Construction procedure

To sign a package, a producer MUST:

1. Construct all tar entries except .peipkg/signature per chapters 3 and 4.
2. Serialise these entries as an uncompressed tar byte stream in archive order.
3. Compute the SHA-256 hash of the resulting byte stream.
4. Sign the hash with the producer's Ed25519 private key per RFC 8032.
5. Construct the signature envelope JSON with the resulting signature value and key fingerprint.
6. Append the .peipkg/signature entry (header + JSON content + padding) to the tar byte stream.
7. Compress the complete tar byte stream with zstd to produce the .peipkg file.

§5.1.6 Unsigned packages

A package without a .peipkg/signature entry is unsigned.

The package format permits unsigned packages: a package manager MAY install one if the source repository's trust policy (§6.5) permits unsigned packages.

A package without a .peipkg/signature entry MUST otherwise conform to all other format requirements in chapter 3. The manifest, files manifest, payload, and integrity rules apply identically to signed and unsigned packages.

This section defines the public key encoding, fingerprint computation, and key publication conventions used by peipkg signing.

§5.2.1 Algorithm

Signatures use Ed25519 as defined in RFC 8032.

A v0.22-conformant implementation MUST support Ed25519 signing and verification. Other algorithms are reserved for future versions of this specification (§5.1.3).

§5.2.2 Public key encoding

A public key is the raw 32-byte Ed25519 public key value as defined in RFC 8032 §5.1.5.

When a public key is published as a file, it MUST be encoded as:

• The raw 32 bytes, OR
• A PEM-encoded PUBLIC KEY block per RFC 7468 (the SubjectPublicKeyInfo form).

A repository's published public key file (§6.1) MUST use one of these two encodings, identified by file extension or content sniffing. Tooling MUST accept both.

§5.2.3 Fingerprint

A public key's fingerprint is the lowercase hexadecimal SHA-256 of the raw 32-byte public key:

fingerprint = lowercase_hex(sha256(public_key_bytes))

The fingerprint is 64 hexadecimal characters (256 bits).

The fingerprint is the canonical identifier of a public key in this specification. The signature envelope's key_fingerprint field (§5.1.3) and the repository descriptor's signing key declaration (§6.1) both use this form.

§5.2.4 Key roles

This specification distinguishes two key roles by usage, not by structure:

• Signing keys are used by a producer (a build farm, the official Peios project, or a custom-repo operator) to sign packages.
• Trusted keys are configured into a consumer (a package manager) as keys whose signatures the consumer accepts.

A single key MAY play both roles. The structure of the key is identical regardless of role; the role is determined by how the key is used.

§5.2.5 Trust set

A package manager maintains a trust set: the collection of public keys whose signatures the manager accepts.

The trust set is partitioned per repository: each configured repository contributes its declared signing keys to the trust set, scoped to that repository's packages.

A signature is accepted only if its key_fingerprint matches a public key in the trust set scoped to the repository the package was fetched from.

§5.2.6 Key rotation

A repository MAY rotate its signing key by:

1. Generating a new key pair.
2. Adding the new public key to the repository's signing key list (§6.1) alongside the existing key.
3. Beginning to sign new packages with the new key.
4. After a transition period during which both keys are advertised, removing the old key from the signing key list.

During the transition, packages signed with either key are acceptable to consumers. After the old key is removed, only packages signed with the new key remain acceptable.

§5.2.6.1 Offline emergency rotation key

A repository SHOULD maintain at least one offline active signing key in addition to its routine signing key(s). The offline key's private material is stored separately from build-farm infrastructure and is used only for descriptor updates and emergency rotations.

The offline key defends against the chicken-and-egg problem in compromise response: revoking a compromised routine signing key requires publishing a new descriptor, which itself must be signed. If the only trusted key is the compromised one, the operator must sign the revocation with the compromised key — giving an attacker who holds the same key the ability to substitute their own revocation that adds an attacker-controlled key.

With an offline key, the operator can sign the descriptor update revoking the compromised key without relying on the compromised key itself. Consumers who have the offline key in their trust set accept the update; consumers who do not must perform out-of-band trust-anchor refresh per §6.5.2.

§5.2.7 Compromised keys

A key SHOULD be considered compromised if its private material may have been obtained by an unauthorised party.

A compromised key MUST be marked revoked in the repository's signing key list immediately upon discovery per the descriptor schema in §6.1.4. Consumers that have fetched the updated descriptor MUST reject signatures from the revoked key regardless of cryptographic validity. Packages signed with the compromised key SHOULD be re-signed with a fresh key, and the affected package versions SHOULD be re-published with new revisions.

The revoked status is the in-band revocation channel this specification defines. It defends against compromise at the descriptor-update granularity: a consumer that successfully refreshes the descriptor learns of revocation immediately. Consumers caching older descriptors retain trust in the revoked key until they re-sync, which is bounded by the maximum trusted age (§6.5.4) and the descriptor signature, which is itself produced by a still-active key.

§5.2.8 Private key handling

Private key material is not the concern of this specification. Best practices for private key generation, storage, custody, and rotation are operational concerns of the repository operator.

This section defines the procedure a consumer MUST follow to verify a signed package and the meaning of a successful verification.

§5.3.1 When verification happens

A consumer MUST verify a package's signature before extracting any payload to disk. Verification is part of the overall verification flow defined in §3.5.3:

1. Compute SHA-256 of the downloaded .peipkg file.
2. Compare against the index-recorded hash.
3. Verify the signature (this section).
4. Decompress and parse the archive.
5. Validate the manifest, files manifest, and integrity manifest.
6. Verify per-file hashes during extraction.

A consumer MUST NOT extract a package's payload if any of these steps fails. A consumer MUST NOT mark a package as installed in its database if signature verification fails.

§5.3.2 Verification procedure

To verify a package's signature, a consumer MUST:

1. Decompress the .peipkg file (zstd → uncompressed tar bytes).
2. Walk the tar archive in order, accumulating the byte stream of each entry's complete blocks (header + content + content-block padding) in a buffer until reaching the entry at path .peipkg/signature.
3. Stop at the .peipkg/signature entry. The buffer now contains the signed bytes (§5.1.2).
4. Parse the content of the .peipkg/signature entry as the signature envelope JSON (§5.1.3).
5. Validate the envelope's schema_version and algorithm fields. Reject if either is unrecognised.
6. Look up the public key by key_fingerprint in the trust set scoped to the originating repository (§5.2.5). If no matching key is in the trust set, reject.
7. Compute the SHA-256 of the buffered signed bytes.
8. Verify the signature against the SHA-256 hash using the looked-up public key per RFC 8032.
9. If verification succeeds, the signature is valid. If it fails, reject the package.

§5.3.3 Failure conditions

The following conditions MUST cause a consumer to reject a package as unverified:

1. The package contains no .peipkg/signature entry, AND the consumer's trust policy for the originating repository requires signed packages.
2. The .peipkg/signature entry is not the last named entry in the tar archive.
3. The signature envelope JSON does not parse.
4. The signature envelope's schema_version is not 1.
5. The signature envelope's algorithm is not recognised by the consumer.
6. The signature envelope's key_fingerprint does not match any public key in the trust set scoped to the originating repository.
7. The cryptographic verification of the signature against the signed bytes fails.

A rejected package MUST NOT be installed. The consumer MUST report which condition triggered the rejection.

§5.3.4 What verification proves

A successfully verified package signature establishes:

• Integrity: the bytes of the tar archive (preceding the signature entry) have not been altered since signing.
• Authenticity: the signer had access to the private key corresponding to the trusted public key at the time of signing.

Verification does NOT establish:

• That the signed bytes encode meaningful content. The consumer MUST still parse and validate the manifest, files manifest, and per-file integrity (§3.5).
• That the signing party intended the package's contents to be installed in any particular system. Trust in the signing party is the operator's responsibility, expressed by including the key in the trust set.
• That the package's content is free of bugs, malicious behavior, or compatibility issues with the target system. Signing certifies provenance, not safety.

§5.3.5 Verification and integrity

Successful signature verification implies that the entire signed payload is intact. This includes the manifest, the files manifest, and the payload entries.

Subsequent per-file integrity checks (§3.5.3) defend against errors during extraction, on-disk tampering, or storage corruption between extraction and use. Without per-file verification, signature verification alone cannot detect post-extraction corruption.

The two verification levels (signature + per-file hashes) together provide end-to-end integrity from signing to installed state.

§5.3.6 Replay and substitution

Signature verification by itself does not prevent replay attacks (an attacker substituting an older, validly-signed package for a newer one). Defence against substitution is provided by:

• The repository index (§6.2), which is itself signed and declares the current authoritative version of each package.
• The hash of each package recorded in the index, which binds a specific signed package file to that index entry.

A consumer MUST consult the repository index and verify the package's hash against the index before accepting the package, even if its signature verifies (§3.5.3).

A repository descriptor is a small JSON document at a well-known URL that describes the repository's identity, signing keys, and the locations of its indexes. It is the entry point a consumer fetches when adding or refreshing a repository.

§6.1.1 URL convention

A repository's descriptor MUST be reachable at the URL <repo-base>/repo.json, where <repo-base> is the base URL declared when the repository was added.

The descriptor MUST be served as static content.

§6.1.2 Schema

{
  "schema_version": 1,
  "repo": {
    "name": "<string>",
    "description": "<string>",
    "signing": {
      "algorithm": "<string>",
      "keys": [<key>...]
    }
  },
  "indexes": {
    "active": {
      "url": "<string>",
      "signature_url": "<string>"
    },
    "archive": {
      "url": "<string>",
      "signature_url": "<string>"
    }
  }
}

The archive index pointer is required even if the archive is empty (a newly-established repository). A repository without an archive index is non-conformant.

§6.1.3 Signing object

{
  "algorithm": "ed25519",
  "keys": [
    {
      "fingerprint": "<hex string>",
      "url": "<string>",
      "status": "active"
    }
  ]
}

Each key entry has the following schema:

A keys array MUST be sorted lexicographically by fingerprint. Two entries with the same fingerprint within the same descriptor are INVALID.

§6.1.4 Key statuses

A key's status describes its role in the repository's current operation:

• active: the key is currently used to sign new packages and indexes. Consumers MUST accept signatures from active keys.
• transitioning: the key was previously active and remains acceptable for verification until its valid_until timestamp, but is no longer used to produce new signatures. Consumers MUST accept signatures from transitioning keys when the current time is at or before valid_until. Consumers MUST reject signatures from transitioning keys whose valid_until has passed. See §5.2.6 for the rotation flow.
• revoked: the key is no longer trusted under any circumstance. Consumers MUST reject signatures from revoked keys regardless of when they were produced or whether they verify cryptographically. The revoked status is the explicit signal of a compromise event (§5.2.7); transitioning is for routine rotation only.

A repository MAY have multiple active keys (allowing parallel signing), any number of transitioning keys each with its own valid_until, and any number of revoked keys.

A transitioning key entry MUST include a valid_until timestamp.

A key whose status is something other than active, transitioning, or revoked is INVALID.

A revoked entry MUST be retained in the descriptor for at least one year after the revocation event. Premature removal of a revoked entry would mask the public acknowledgement of compromise from consumers with stale caches.

§6.1.5 Index pointers

Each index pointer object has the following schema:

The conventional URLs are:

<repo-base>/index/active.json
<repo-base>/index/active.json.sig
<repo-base>/index/archive.json
<repo-base>/index/archive.json.sig

A repository MAY use other URLs by specifying them explicitly. The descriptor's URLs are authoritative; the conventional paths are fallbacks for tools that need a sensible default.

§6.1.6 Descriptor signing

The descriptor itself MUST be accompanied by a detached signature published at <repo-base>/repo.json.sig. The signature is over the descriptor file's exact bytes, encoded as Ed25519 base64 (RFC 4648 §4) without padding.

The signing key MUST be one of the keys listed in the descriptor's repo.signing.keys array (any key with status active or transitioning).

A repository configured to permit unsigned packages (§6.5.3) MAY publish an unsigned descriptor and indexes. This is a security weakening explicitly opted into per- repository.

§6.1.7 Determinism

The descriptor JSON SHOULD be canonically formatted to permit reproducible signing: keys ordered as specified in the schema, key arrays sorted as specified, no trailing whitespace, single trailing newline.

§6.1.8 Example

{
  "schema_version": 1,
  "repo": {
    "name": "peios-official",
    "description": "Official Peios package repository",
    "signing": {
      "algorithm": "ed25519",
      "keys": [
        {
          "fingerprint": "1a2b3c...64chars",
          "url": "/keys/1a2b3c.pub",
          "status": "active"
        }
      ]
    }
  },
  "indexes": {
    "active": {
      "url": "/index/active.json",
      "signature_url": "/index/active.json.sig"
    },
    "archive": {
      "url": "/index/archive.json",
      "signature_url": "/index/archive.json.sig"
    }
  }
}

The active index lists the current version of every package the repository currently advertises. It is the default index a consumer fetches on routine sync operations.

§6.2.1 URL and signing

The active index URL is declared by the repository descriptor's indexes.active.url field (§6.1.5). The detached signature URL is declared by indexes.active.signature_url.

The active index MUST be accompanied by a detached signature published at the indexes.active.signature_url declared in the descriptor. The signature is over the index file's exact bytes, encoded as Ed25519 base64 (RFC 4648 §4) without padding — the same detached- signature convention as the repository descriptor (§6.1.6). The signing key MUST be one of the keys listed in the descriptor with status active or transitioning.

A repository configured to permit unsigned content (§6.5.3) MAY publish the active index unsigned.

§6.2.2 Top-level schema

{
  "schema_version": 1,
  "repo": "<string>",
  "kind": "active",
  "index_version": <integer>,
  "generated_at": "<RFC 3339 timestamp>",
  "packages": [<package_entry>...]
}

§6.2.3 Freshness and rollback protection

Each new publication of an index MUST set index_version to a value strictly greater than any previously-published value for the same repository.

A consumer MUST record the highest index_version it has ever observed for each configured repository. On each refresh, the consumer MUST reject any fetched index whose index_version is less than the recorded value, even if the index is correctly signed and the signature key is still trusted.

The consumer MUST also reject any fetched index whose generated_at is older than the recorded generated_at for the previously-trusted index from the same repository.

The first-add of a repository (§6.5.2) is the bootstrap of the consumer's recorded index_version floor. To defend against an attacker serving a stale-but-signed index at first-add, a repository SHOULD distribute a minimum acceptable index_version alongside its trust-anchor fingerprints (the same out-of-band distribution mechanism). Consumers SHOULD use this minimum as the initial recorded floor; if the first- fetched index has an index_version less than the distributed minimum, the consumer MUST refuse the repo-add operation.

A refresh that fetches an index whose index_version equals the recorded value AND whose generated_at equals the recorded value is treated as a failed refresh (no progress). The consumer MUST NOT advance the "last successful refresh" timestamp on such a fetch. This prevents an attacker from holding a consumer at the same index indefinitely while the clock burns past the maximum trusted age.

These checks defend against rollback / freeze attacks: an attacker who controls a CDN edge or substitutes the served index cannot replay an older signed index to hide newer (security-fix) packages from the consumer, nor can they hold the consumer at a current-but-frozen state by repeatedly serving the same index.

A consumer MUST also enforce a maximum freshness window: an index whose generated_at is older than 90 days MUST trigger a refresh attempt before any install operation proceeds. The 90-day default MAY be tuned by operator configuration; values greater than 365 days SHOULD generate a warning each time they are exercised.

§6.2.4 Package entry schema

Each entry in packages has the following schema:

{
  "name": "<string>",
  "version": "<string>",
  "architecture": "<string>",
  "description": "<string>",
  "license": "<string>",
  "homepage": "<string>",
  "dependencies": [<dependency>...],
  "optional_dependencies": [<dependency>...],
  "conflicts": [<dependency>...],
  "provides": [<provides>...],
  "replaces": [<replaces>...],
  "side_effects": [<string>...],
  "size_compressed": <integer>,
  "size_installed": <integer>,
  "hash": {
    "algorithm": "<string>",
    "value": "<hex string>"
  },
  "url": "<string>",
  "build": {
    "timestamp": "<RFC 3339 timestamp>",
    "farm_id": "<string>"
  }
}

A package entry MUST contain name, version, architecture, dependencies, conflicts, size_compressed, size_installed, hash, and url. Other fields are RECOMMENDED but MAY be omitted.

size_compressed and size_installed are required to enable consumer-side enforcement of decompression bounds (§3.5.4).

§6.2.5 Derivation rule

The active index is a derived view of the packages it advertises. Every field in a package entry MUST exactly match the corresponding field in the package's manifest (§3.3) where one exists, and MUST exactly match the properties of the actual .peipkg file (hash, size_compressed, url).

If a package's manifest contradicts the index entry, the manifest is authoritative (§3.3.7). Tooling that generates the active index MUST extract values directly from package manifests; manual editing of the index is forbidden.

§6.2.6 Field omissions

The active index intentionally omits the following manifest fields:

• sd_overrides: not relevant to client-side resolution.
• build.source_ref: long, low-information-density; consult the package directly when needed.
• schema_version (manifest): redundant; the index has its own schema_version.

These fields remain in the package's manifest and are available to consumers that fetch the package.

§6.2.7 URL field

The url field declares where the package file is fetched from. The URL MAY be relative or absolute:

• A relative URL (starting with / or with no scheme) is resolved against the repository's <repo-base>.
• An absolute URL is used as-is.

The conventional form is a relative URL following the structure defined in §6.4:

"url": "/p/nginx/1.26.2-3/nginx_1.26.2-3_x86_64.peipkg"

This form keeps the index portable: the same index file is valid at any <repo-base> that hosts the same package files.

§6.2.8 Hash object

{
  "algorithm": "sha256",
  "value": "<lowercase hex>"
}

The algorithm MUST be sha256 in this specification. The value is the lowercase hexadecimal SHA-256 of the .peipkg file in its compressed on-wire form.

§6.2.9 Ordering

The packages array MUST be sorted lexicographically by name. Two entries with the same name within the active index are INVALID. Each name appears exactly once.

§6.2.10 Forward-compatible fields

Consumers MUST ignore unknown fields in the index entry (top-level or per-package) per the manifest forward- compatibility rule (§3.3.3). Producers MAY emit additional fields in future schema versions.

The exception is fields whose meaning is critical to correctness (such as a hash algorithm field): these are expected to be addressed via schema_version bumps, not silent additions.

§6.2.11 Size

For a repository of approximately 300 packages, the active index is on the order of 100 KB compressed and 600 KB uncompressed. Consumers SHOULD fetch with HTTP-level compression (Accept-Encoding: zstd or gzip) when available.

§6.2.12 Caching

Consumers SHOULD cache the parsed active index between package manager invocations. The index changes only when the producer publishes new content; re-parsing on every operation is wasteful given that the change cadence is much slower than the read cadence.

A cached parsed index remains valid until the consumer performs a refresh operation (§6.5.4) that supersedes it. The freshness policy is implementation-defined; typical policies are time-based (TTL), explicit-refresh- only, or check-on-network-state-change.

The cached index file MUST be stored under a security descriptor that grants write access only to the package manager principal. The package manager MUST re-verify the cached index's signature on each install operation rather than trusting the cache state across operations. Caching avoids re-parsing JSON; it does not avoid re-verifying signatures.

The archive index lists every version of every package the repository has ever advertised, including versions superseded by newer releases. It is the source of historical package data for downgrade, version pinning, and forensic queries.

§6.3.1 Retention model

A repository MUST retain every package version it has ever advertised. Once a package has been published with version V, the repository MUST continue to make package V fetchable indefinitely. The archive index MUST continue to list V.

A repository MAY retire pre-release or development versions under operator-defined retention policy. Retirement MUST NOT silently remove packages a consumer might be using; it SHOULD be coordinated with consumer notice.

§6.3.2 URL and signing

The archive index URL is declared by the repository descriptor's indexes.archive.url field (§6.1.5). The detached signature URL is declared by indexes.archive.signature_url.

The archive index MUST be signed under the same rules as the active index (§6.2.1).

§6.3.3 Top-level schema

{
  "schema_version": 1,
  "repo": "<string>",
  "kind": "archive",
  "index_version": <integer>,
  "generated_at": "<RFC 3339 timestamp>",
  "packages": [<package_entry>...]
}

The schema is identical to the active index (§6.2.2) except:

• kind MUST be archive.
• The packages array MAY contain multiple entries with the same name (different version).
• index_version semantics are identical: monotonically increasing per publication, consumer enforces non- decreasing on refresh.

§6.3.4 Package entry schema

The per-package entry schema is identical to the active index (§6.2.3). Each historical version contributes one entry.

§6.3.5 Ordering

The packages array MUST be sorted lexicographically, first by name and then within name by version descending (per §2.2.6). The first entry for any given name is the highest version; subsequent entries for that name are progressively older.

§6.3.6 Relationship to the active index

For every entry in the active index, there MUST be at least one entry in the archive index with the same name, version, architecture, and hash.

The archive index is a superset of the active index.

§6.3.7 Fetch frequency

The archive index is large compared to the active index (potentially many megabytes for a long-running repository). Consumers SHOULD fetch the archive index only when needed:

• When a user explicitly queries historical versions
• When a user pins to or downgrades to a non-current version
• When the consumer's caching policy expires the cached copy

Routine pkg sync operations SHOULD fetch only the active index, not the archive index.

§6.3.8 Pruning of pre-releases

A repository MAY prune pre-release versions older than a declared age threshold from the archive index, provided that pruning is documented and consumers are advised. This specification does not mandate or forbid such pruning; operators choose retention policy based on their use case.

A pruned package MUST also be removed from the repository's package storage; the archive index MUST NOT reference packages whose .peipkg files are no longer fetchable.

§6.3.9 Size

For a repository of approximately 300 packages with approximately 20 versions retained per package, the archive index is on the order of 2-3 MB compressed and 12-18 MB uncompressed. Consumers SHOULD fetch with HTTP-level compression when available, and SHOULD cache the archive index aggressively (it changes only when new versions are published or old versions are pruned).

This section defines the URL structure repositories use to serve their content. The conventions are designed for static HTTP hosting: every URL maps to a static file or a static-file-equivalent resource.

§6.4.1 Repository base

A repository is identified by a base URL, referred to as <repo-base> throughout this specification.

The base URL MUST be a syntactically valid HTTP or HTTPS URL per RFC 3986. HTTPS MUST be used unless the consumer is configured with an explicit allow_insecure_transport flag for the repository in question. The flag is per- repository, not global, and its use MUST generate a per-operation warning. HTTP repositories are intended only for trusted local-network development scenarios; relying on package signing alone for transport integrity exposes the consumer to traffic-analysis and metadata-substitution attacks even when content verification succeeds.

Toggling allow_insecure_transport to true after the repository has been added MUST require explicit operator authorisation (§7.6.6) AND MUST emit an audit event to eventd (§7.6.3). Setting the flag during the initial repo-add operation is treated as part of the operator's trust decision and does not require a separate audit event beyond the standard repo-add audit.

The base URL MUST NOT have a trailing slash. The well-known relative paths defined below are appended directly.

§6.4.2 Conventional paths

The following paths are conventional. A repository SHOULD use these paths unless it has a compelling reason to use others. When a repository uses non-conventional paths, the descriptor's URL fields (§6.1) declare them.

A consumer that knows only <repo-base> MUST be able to locate repo.json at the conventional path. The descriptor contains the URLs for everything else.

§6.4.3 Package URLs

Each package's URL has the form:

<repo-base>/p/<name>/<version>/<filename>

Where:

• <name> is the package name conforming to §2.1.
• <version> is the full version string conforming to §2.2.
• <filename> is <name>_<version>_<architecture>.peipkg per §2.1.4.

https://pkgs.peios.org/p/nginx/1.26.2-3/nginx_1.26.2-3_x86_64.peipkg

<repo-base>/p/<name>/<version>/<filename>.debug.peipkg
<repo-base>/p/<name>/<version>/<filename>.sbom.json
<repo-base>/p/<name>/<version>/<filename>.attestation.json

§6.4.7 Static hosting requirements

The protocol requires only static HTTP serving. A conformant repository MAY be hosted on:

• A simple HTTP server (nginx, Apache, Caddy)
• An object store with HTTP frontend (S3, R2, GCS)
• A static site host (GitHub Pages, Cloudflare Pages, Netlify)
• A CDN proxying any of the above
• A local filesystem accessed via file:// URLs (for development)
• A combination (descriptor and indexes on a static host, package binaries on object storage with redirects)

There is no requirement for server-side computation, dynamic responses, or content negotiation beyond optional HTTP-level compression.

§6.4.8 Network failure handling

A consumer that fails to fetch a URL MUST NOT silently fall back to outdated cached data without explicit user authorisation. Stale cache use without explicit consent is a security risk: it can mask substituted-content or revoked-key updates.

A consumer SHOULD provide a mechanism for users to configure cache-staleness tolerance per repository.

This section defines how a consumer establishes trust in a repository, how that trust is enforced when verifying content, and how multiple repositories interact.

§6.5.1 Per-repository trust

Trust is configured per repository, not globally. Each repository a consumer is configured with has its own:

• Set of trusted signing keys (§5.2.5).
• Signature policy (§6.5.3).
• Priority for resolution (§6.5.5).

A signature from a key trusted only for repository R is NOT accepted on a package fetched from repository S, even if both keys are present in the consumer's overall configuration. This per-repository scoping is essential for the security of multi-repository systems.

§6.5.2 Adding a repository

When a consumer adds a repository, the user MUST supply:

• The repository's <repo-base> URL.
• One or more expected key fingerprints (the trust anchors).
• A signature policy (§6.5.3) for this repository.

The consumer THEN performs the following:

1. Fetches <repo-base>/repo.json (or whatever URL the user supplied for the descriptor).
2. Fetches <repo-base>/repo.json.sig.
3. For each trust anchor fingerprint supplied by the user, attempts to fetch the corresponding public key from the conventional URL or from the URL declared in the descriptor's repo.signing.keys array.
4. Verifies repo.json's signature against the trust anchor public keys.
5. If verification succeeds, the descriptor is trusted. The consumer records the descriptor's contents (including all signing keys) as the repository's initial trust state.
6. If verification fails, the consumer rejects the repo- add operation and reports the failure.

Trust anchors are obtained out-of-band. The official Peios repository's trust anchors are published through the project's website, documentation, and OS image. Custom repositories distribute their own.

§6.5.2.1 Transcription-error defence

When the consumer presents a fetched key for the user to confirm against the supplied trust anchor, the consumer MUST display the fingerprint in a form designed to make mismatches visually obvious:

• The 64-character hex fingerprint MUST be split into groups separated by spaces or colons (e.g., groups of 4 characters: 1a2b 3c4d 5e6f ...).
• The consumer MUST display the fingerprint of the fetched key alongside the user-supplied fingerprint for visual comparison before committing the trust state.
• The consumer MUST require explicit confirmation (e.g., a yes/no prompt or equivalent affirmation) before recording the new trust state. Auto-confirmation on the basis of "fingerprints matched bit-for-bit" is permitted only in non-interactive contexts where the user has pre-supplied the fingerprint via a configured channel.

When a repository declares multiple active keys in its descriptor, the user is RECOMMENDED to supply trust anchors for at least two of them. This provides defence-in-depth against single-anchor transcription errors.

§6.5.3 Signature policy

When adding a repository, the user supplies a signature policy specifying how strict to be:

The official Peios repository SHOULD be configured with policy required. The consumer's default policy when adding a new repository SHOULD be required unless the user explicitly chooses otherwise.

There is no none (silently-accept-unsigned) policy. A consumer that intentionally permits unsigned content MUST do so via the optional policy, which always emits a per-operation warning. This warning MUST surface to the operator on every install, upgrade, and refresh — not merely once per session — so a misconfigured trust state is continuously visible.

§6.5.4 Refresh

A consumer SHOULD refresh its cached repository state periodically. A refresh MUST:

1. Fetch the current repo.json and its signature.
2. Verify the signature against any signing key whose status was active or transitioning in the previously-trusted descriptor.
3. If verification succeeds, record the new descriptor as the current trust state. The new descriptor's signing keys (with their statuses) replace the previous set.
4. Fetch the active index and verify its signature against the new descriptor's signing keys.
5. Optionally fetch and verify the archive index.

Failure to verify a refresh MUST cause the consumer to retain its previous trust state and report the failure. The previous trust state remains valid until the next successful refresh.

§6.5.4.1 Maximum trusted age

A consumer MUST track the time of the last successful refresh per repository. When the time since the last successful refresh exceeds the maximum trusted age, the consumer MUST attempt a refresh before any install, upgrade, or downgrade operation against that repository. If the refresh attempt fails, the consumer MUST surface the failure and refuse the operation unless the operator explicitly authorises proceeding with stale trust state.

The default maximum trusted age is 30 days. The default MAY be tuned by operator configuration; values exceeding 180 days SHOULD generate a per-operation warning so a configuration that effectively disables the freshness check remains visible.

§6.5.5 Multiple repositories and priority

A consumer MAY configure multiple repositories. Each configured repository has a numeric priority (a positive integer; lower numbers are higher priority).

When a package is available from multiple repositories, resolution selects from the highest-priority repository that contains a satisfying candidate (§4.2.4).

A consumer's default priority assignment SHOULD give the official Peios repository the lowest numeric priority (highest priority). User-added custom repositories receive priorities at the user's discretion.

§6.5.6 Repository removal

A consumer MAY remove a configured repository at any time. Removal:

• Deletes the consumer's cached repository state for that repository.
• Removes that repository's signing keys from the trust set scoped to it.
• Does NOT uninstall packages already installed from that repository. Installed packages remain installed; their origin information is retained for future operations (upgrade, removal).

If the user reinstalls a removed repository, the trust-add procedure (§6.5.2) is performed afresh; previous state is not implicitly restored.

§6.5.6.1 Orphaned-trust packages

A package whose originating repository has been removed or revoked is orphaned: its trust chain is no longer verifiable by the current trust state. The package manager MUST flag orphaned packages distinctly:

• peipkg query operations MUST display orphaned packages with a clear indicator (e.g., a warning marker next to the package name).
• Any operation involving an orphaned package (uninstall, upgrade, integrity check) MUST surface the orphan state to the operator and recommend audit before proceeding.
• Upgrades to an orphaned package MUST be refused unless a currently-trusted repository now claims the package (e.g., the operator has added a replacement repo and the new repo's package matches the orphan's name).

Operators encountering orphaned packages SHOULD audit them: verify the installed files' hashes against trustworthy out-of-band records, and consider reinstalling or removing the package via a currently-trusted repository.

§6.5.7 Cross-repository conflicts

When two configured repositories both publish packages with the same name, no conflict exists at the format level. The consumer resolves which version to install per the priority rule (§6.5.5).

When two configured repositories publish packages with overlapping provides namespaces or replaces relations, the priority rule applies similarly: the higher-priority repository's claim wins.

A repository operator who publishes a provides for a name that conflicts with the official repository's package SHOULD document this clearly. Consumers SHOULD warn when a custom repository's provides shadow an official-repo package.

A consumer MUST require explicit operator confirmation before applying a replaces (§4.1.5) relation declared by a non-official repository against a package originally installed from a higher-priority repository. A custom repository silently replacing an official-repo package is a real escalation path; the explicit confirmation prevents this from happening as a side effect of a routine peipkg upgrade operation.

The same explicit-confirmation requirement applies when a conflicts (§4.1.2) declaration from a non-official repository would cause cascade-removal of a package originally installed from a higher-priority repository. A low-trust repository's conflicts against a high-trust package is a denial-of-availability vector; the explicit confirmation prevents installation of a low-trust package from silently uninstalling a high-trust one as a cascade side effect.

§6.5.8 Compromise response

If a repository's signing key is suspected of being compromised, the consumer SHOULD:

1. Disable the repository immediately (do not fetch from it until the situation is resolved).
2. Audit installed packages from that repository for tampering.
3. After the repository operator publishes a new descriptor with the compromised key removed, perform a fresh trust- add operation with new trust anchors.

This specification does not define an automated revocation mechanism in v0.22. Compromise response is operational.

This section defines the install operation: the procedure for adding a new package to the system.

Install is one of three primitive package operations defined in this chapter; upgrade (§7.2) and uninstall (§7.3) are the others. All three execute within a transaction (§7.4) and can be rolled back on failure (§7.5).

§7.1.1 Preconditions

An install operation begins with the following inputs:

• A .peipkg file (already fetched).
• The repository the package was fetched from, with its trust state.
• The current installed-package database state.
• The current resolution plan (§4.2) that called for this install.

The following preconditions MUST hold before install proceeds:

1. The package's hash matches the value recorded in the repository index (§3.5.3 step 2).
2. The package's signature, if present, verifies against the trust set scoped to its origin repository (§5.3.2).
3. The package is not already installed at the same version and architecture.
4. The package's architecture matches the system's primary architecture or is noarch (§2.3.5).
5. The package's dependencies (§4.1) are satisfied by the current installed set, the in-flight resolution plan, or both combined.
6. No installed package conflicts (§4.1.2) with this package.

A precondition failure aborts the install. The transaction that contains it (if any) MUST be rolled back per §7.5.

§7.1.2 Procedure

The install procedure consists of the following ordered steps. Each step MUST complete successfully before the next begins.

§7.1.2.1 Step 1: parse and validate

1. Decompress the .peipkg file.
2. Parse .peipkg/manifest.json per §3.3.
3. Parse .peipkg/files.json per §3.5.1.
4. Validate that every payload tar entry has a corresponding entry in files.json per §3.5.1.3.
5. Validate that the manifest's name, version, and architecture match what the resolution plan selected.
6. Validate every payload entry's path against the constraints in §3.2.7 and the entry-type restrictions in §3.2.6.
7. Validate every symlink entry's linkname against the target constraints in §3.4.8.

§7.1.2.2 Step 2: prepare

1. Compute the install plan: which files will be created, which directories will be created, which side effects will be invoked.
2. Verify disk space. A transaction's additional space requirement is the staged new and changed content — size(ADDED) + size(REPLACED), aggregated across all operations in the transaction. Backups of replaced or removed files cost no additional space: a backup is made by renaming the old file aside within its own directory (§7.5.1.3), retaining the old content in place rather than copying it. Because a transaction may span multiple filesystems, the check MUST be performed per target filesystem, not against a single global figure. For a pure install (no replacements) the requirement reduces to size_installed (§3.3.3).
3. Verify no payload path collides with a path already owned by another installed package (§3.4.10).

§7.1.2.3 Step 3: extract

For each payload entry in tar order:

1. Determine the install path on disk by joining the payload-relative path with the filesystem root. Path resolution MUST use TOCTOU-safe interfaces: the package manager MUST resolve each path component relative to a verified parent-directory file descriptor, and MUST NOT traverse any symbolic link while doing so — including a symlink the package manager itself created earlier in the same operation. On Linux this is achieved with openat2(..., RESOLVE_NO_SYMLINKS) anchored at the relevant permitted top-level destination (§3.4.1), or equivalent semantics with O_NOFOLLOW on every component. A conformant consumer SHOULD additionally apply RESOLVE_BENEATH, RESOLVE_NO_XDEV, and RESOLVE_NO_MAGICLINKS as defence in depth.

   A well-formed package never contains a payload entry whose ancestor path component is a symlink, so this resolution never fails for a conformant package; a resolution failure indicates a malformed or hostile package, or hostile filesystem state, and MUST abort the install.

2. If a non-directory entry already exists at the install path (whether owned by another package or unowned), handle per the file-ownership rule (§7.1.5). Pre- existing symlinks at the install path MUST be removed atomically before write; they MUST NOT be followed.

3. For directory entries: create the directory if it does not exist. Set the directory's permissions per the tar entry's mode.

4. For symlink entries: create the symlink with the tar entry's linkname as target. The linkname MUST satisfy the symlink-target constraints in §3.4.8 — these are validated at parse time (§7.1.2.1), so by the time extraction reaches a symlink entry the target is known-safe.

5. For regular-file entries: create the file with the tar entry's mode and content. Apply security descriptor per §3.4.7 (inheritance by default; manifest-declared override if present).

6. After creating the file, compute its content hash and verify it matches the corresponding entry in .peipkg/files.json (§3.5.3 step 7).

7. If hash verification fails, roll back the install per §7.5.

Each file extraction SHOULD be performed atomically (write to a temporary path within the same parent directory, then renameat2 to the final path). The exact atomicity mechanism is implementation-defined; the requirement is that no consumer of the filesystem observes a partially-written file and that the rename does not follow a symlink at the destination.

§7.1.2.4 Step 4: side effects

For each side effect declared in the manifest's side_effects (§4.3) field, schedule it for invocation at transaction commit. Side effects are deduplicated and batched across all operations in the transaction (§7.4.6).

§7.1.2.5 Step 5: register

Update the package database to record the package as installed:

• Package identity (name, version, architecture).
• Originating repository.
• Install timestamp.
• The list of payload paths owned by this package.
• The package's manifest contents (or a reference to them, sufficient to reconstruct).

The database update MUST be part of the transaction and MUST be visible only on transaction commit (§7.4.5).

§7.1.3 Side-effect timing

Side effects (§4.3) are NOT invoked during step 3 extraction. They are invoked at transaction commit, after all packages in the transaction have completed extraction and registration.

This permits the system to remain in a consistent state during multi-package installs: ldconfig is invoked once after every package's libraries are extracted, not after each package individually. Same for depmod and mandb.

§7.1.4 Failure handling

A failure during any step of install MUST cause the install to be considered aborted. The containing transaction (§7.4) is responsible for rolling back any partial state per §7.5.

Failures include but are not limited to:

• Hash mismatch on any payload file (§3.5.3 step 7)
• Disk space exhaustion during extraction
• Permission denied (parent directory not writable, SD inheritance forbids creation)
• I/O errors
• Database write failure

The package manager MUST report which step failed and why.

§7.1.5 File ownership

A file is owned by the package whose install procedure created it. Ownership is recorded in the package database (step 5 above).

A path that already exists on the filesystem and is not owned by any installed package is handled as follows:

• If the existing file's content is byte-identical to the payload entry that would be installed at that path, the package manager MAY adopt it: record the path as owned by the installing package without rewriting it. Adoption is safe because the on-disk content is already exactly what would be installed.
• Otherwise, the package manager MUST fail with an explicit error rather than overwriting the unowned file, unless the operator explicitly authorises the overwrite. When authorised, the existing file MUST be displaced (renamed aside as a backup) rather than destroyed, so that it remains recoverable.

This section defines the upgrade operation: the procedure for replacing an installed version of a package with a different version.

Upgrade is conceptually a single atomic operation combining an install of the new version and an uninstall of the old version, with the property that no point in time leaves the system without the package's content available.

The same procedure handles upgrades (newer version replacing older) and downgrades (older version replacing newer). The two cases differ only in which version comparison applies; the format treats both identically.

§7.2.1 Preconditions

An upgrade operation begins with the following inputs:

• The new version's .peipkg file (already fetched).
• The currently-installed version of the same package.
• The repository the new version was fetched from.
• The current resolution plan.

The following preconditions MUST hold:

1. All preconditions of install (§7.1.1) hold for the new version, except the "not already installed" check which is replaced by "the currently-installed version has the same name and architecture but a different version".
2. The new version's dependencies are satisfied (or will be satisfied by the in-flight transaction's other operations).
3. No package depends on the currently-installed version in a way that the new version cannot satisfy.
4. If the new version is older than the currently- installed version (downgrade), the user has explicitly authorised the downgrade.

§7.2.2 File diff

An upgrade is computed as a diff between the old version's file set and the new version's file set:

• Files in old but not in new: REMOVED at upgrade commit.
• Files in both old and new with identical content hash: untouched.
• Files in both old and new with different content hash: REPLACED.
• Files in new but not in old: ADDED at upgrade commit.

Files in /etc/ are handled by modified-detection. For a REPLACED /etc/ file, the package manager compares the file's current on-disk content hash against the hash recorded for that file at install:

• Unmodified — the on-disk content matches the recorded hash: the file is replaced with the new version's content, like any other REPLACED file.
• Modified — the on-disk content differs: the operator's file MUST be left in place; the new version's default is written alongside it as <name>.peipkg-new, and the divergence MUST be surfaced in the operation report.

§7.2.3 Procedure

The upgrade procedure consists of the following ordered steps:

§7.2.3.1 Step 1: parse and validate

Identical to install step 1 (§7.1.2.1) for the new version's package.

§7.2.3.2 Step 2: prepare diff

1. Read the currently-installed version's file list from the package database.
2. Read the new version's file list from the new .peipkg's files.json.
3. Compute the diff (§7.2.2).
4. Verify disk space per §7.1.2.2 step 2 — the staged ADDED and REPLACED content. Backups of REPLACED and REMOVED files are made by renaming the old files aside (§7.5.1.3) and cost no additional space.
5. Verify no ADDED path collides with a path owned by a different package than the one being upgraded.

§7.2.3.3 Step 3: stage replacement

For each REPLACED or ADDED file:

1. Extract from the new .peipkg to a temporary file within the destination's own directory, so the commit-time rename is intra-directory and cannot fail with EXDEV (§7.1.2.3).
2. Verify content hash against files.json.

Staged files are named so as not to collide with payload entries, and are not visible as installed content until commit, when an atomic rename moves each into place.

§7.2.3.4 Step 4: apply diff

At transaction commit (§7.4):

1. For each ADDED file: rename the staged file into place at the install path (§7.1.2.3) and apply its SD per §3.4.7.
2. For each REPLACED file: rename the existing file aside as a backup (§7.5.1.3), then rename the staged file into place; apply the new file's SD per §3.4.7.
3. For each REMOVED file: rename the file aside as a backup (§7.5.1.3). The backup is discarded once the transaction commits and any retention window expires.
4. Remove empty directories that are no longer owned by any installed package.

§7.2.3.5 Step 5: side effects

Side effects declared by the new version are scheduled for invocation at transaction commit. Side effects are also scheduled if files were REMOVED whose absence affects the side-effect target (e.g., removing a shared library requires ldconfig, removing a kernel module requires depmod).

A package manager MAY infer additional side-effect invocations from REMOVED files even if the new package does not explicitly declare them.

§7.2.3.6 Step 6: update registration

Replace the package database's record for this package with the new version's identity, file list, and manifest contents. The database update is part of the transaction.

§7.2.4 Replaces relations

An upgrade triggered by a replaces relation (§4.1.5) follows the same procedure with the replaced package treated as the "currently installed version", even though its name differs from the new package's name.

The package database's record for the replaced package is removed; a new record for the replacing package is created. From the system's perspective, the replaced package is uninstalled and the replacing package is installed; the diff procedure ensures no payload files are spuriously removed during the transition.

§7.2.5 Downgrade

A downgrade is an upgrade where the new version is older than the installed version per §2.2.6. The procedure is identical to upgrade, with one additional precondition: the user MUST have explicitly authorised the downgrade.

§7.2.6 Concurrent dependent updates

If an upgrade in progress would temporarily violate a dependent package's dependencies (because the new version is incompatible with the dependent), the resolution plan MUST include the dependent's upgrade in the same transaction.

The upgrade procedure MUST NOT be invoked on a single package without ensuring that any dependents whose constraints are not satisfied by the new version are also upgraded (or removed) in the same transaction.

This section defines the uninstall operation: the procedure for removing a package from the system.

§7.3.1 Preconditions

An uninstall operation begins with the following inputs:

• The name of the package to uninstall.
• The current installed-package database state.
• The current resolution plan.

The following preconditions MUST hold:

1. The named package is currently installed.
2. No other installed package depends on this package (per §4.1) unless the resolution plan includes their uninstall as well.
3. No other installed package's replaces (§4.1.5) target is this package.

If installed dependents block the uninstall, the package manager MUST either:

• Cascade: include the dependents in the same uninstall transaction (per §4.2.7), with explicit user authorisation, or
• Refuse: report which dependents block the uninstall and abort.

The choice between cascade and refuse is per-transaction policy.

§7.3.2 Procedure

§7.3.2.1 Step 1: enumerate

1. Read the package's file list from the package database.
2. Compute the set of paths to remove.
3. Compute the set of side effects to invoke (typically ldconfig if the package owned shared libraries, depmod if it owned kernel modules, mandb if it owned man pages).

§7.3.2.2 Step 2: prepare

1. For each path to remove, check that the path on disk has not been modified by an unowned process. The check is content-hash comparison against the hash recorded in the package database (extracted from the package's files.json at install).
2. Files whose on-disk content differs from the recorded hash are modified files. The package manager MUST surface these to the user before removal.
3. The user MAY authorise removal of modified files, skip-removal, or abort the uninstall.

§7.3.2.3 Step 3: remove

For each path to remove:

1. Rename the path aside as a backup (§7.5.1.3) rather than deleting it outright, so the uninstall can be rolled back and remains undoable (§7.5.2). The backup is discarded once the transaction commits and any retention window expires.
2. If the path's parent directory is now empty AND the parent directory is not owned by another installed package, schedule the parent for removal.

After all package-owned paths are processed, remove the scheduled empty directories in deepest-first order.

§7.3.2.4 Step 4: side effects

Schedule the side effects identified in step 1 for invocation at transaction commit. Side effects are deduplicated and batched per §7.4.6.

§7.3.2.5 Step 5: deregister

Remove the package's record from the package database.

§7.3.3 File ownership and overlap

A path that is part of multiple installed packages is not permitted (§3.4.10). However, in degraded scenarios (database corruption, manual intervention), the package manager MAY encounter such a state.

If a path scheduled for removal is owned by another installed package per the database, the package manager MUST NOT remove the file. The package manager SHOULD surface the overlap as a database-integrity warning.

§7.3.4 Removal of system-critical packages

Some packages are system-critical: their files are required for the package manager itself, or for core system function, to work (the package manager binary and its trust anchors, core system packages). The set is operationally defined and not specified normatively here.

A package manager MUST refuse to uninstall a system-critical package unless the operator supplies an explicit, operation-specific override (for example an --allow-critical flag). This is a foot-gun guard, not a security boundary: under Peios's access model the operator already holds whatever authority the underlying file deletions require (§7.6), so the guard exists to prevent an accidental uninstall from disabling the system — not to deny an authorised operator who genuinely intends the removal.

§7.3.5 Side-effect timing on uninstall

Side effects are invoked at transaction commit, after all packages in the transaction have been removed. The same deduplication and batching rules as for install (§7.1.3) apply.

A transaction is the atomic unit of package operations. All install, upgrade, and uninstall procedures (§7.1, §7.2, §7.3) execute within a transaction, even when the transaction contains a single operation.

This section defines the transaction model and its properties.

§7.4.1 Atomicity

A transaction is atomic: either all of its operations succeed and become visible to consumers of the system, or none of them visibly take effect.

This property MUST hold under both:

• Logical failure (a step fails, an error is reported, a rollback is requested).
• System failure (power loss, kernel panic, hardware fault) at any point during the transaction.

A transaction in progress is uncommitted. An uncommitted transaction is not visible to other consumers of the system: the package database does not yet show its operations as applied; files staged for replacement have not yet replaced their targets; side effects have not yet been invoked.

A transaction that completes its commit step (§7.4.5) is committed. A committed transaction's operations are visible to all subsequent operations.

§7.4.2 Transaction scope

A transaction MAY contain any combination of install, upgrade, and uninstall operations on different packages. Operations within a single transaction MUST be ordered such that, at commit time, no operation depends on a package whose install has not been committed first.

A transaction MUST NOT contain two operations that affect the same package (e.g., install and uninstall the same package within the same transaction). Use upgrade for version transitions; use removal-then-install (in two separate transactions) for hard reinstalls.

§7.4.3 Verification before extraction

For a transaction containing multiple install or upgrade operations, the package manager MUST complete signature verification (§5.3.2) and index-hash verification (§3.5.3 step 2) for every package in the transaction before extracting (§7.1.2.3) any package's payload.

A package whose verification fails MUST cause the entire transaction to be aborted before any payload extraction begins.

§7.4.4 Single-writer concurrency

At most one transaction MAY be in progress at any time on a given system.

The package manager MUST acquire an exclusive lock before beginning a transaction. Other concurrent invocations of the package manager MUST detect the lock and either:

• Wait for the in-progress transaction to complete.
• Fail with an explicit "transaction in progress" error.

The lock mechanism is implementation-defined but MUST provide:

• Mutual exclusion across processes on the same system.
• Detection of stale locks (held by terminated processes).
• A user-visible error message when blocking.

Stale-lock detection MUST be conservative: the package manager MUST NOT declare a lock stale based on a timeout alone. Stale-detection MUST verify that the holder is provably gone (e.g., kill(pid, 0) == ESRCH plus a PID-reuse safeguard such as comparing the process start time recorded in the lock against the current process's start time).

§7.4.5 Commit procedure

The commit procedure transitions a transaction from uncommitted to committed. Atomicity rests on a single fact: the package database is a transactional store (SQLite in WAL mode, or equivalent — §7.4.8), and the package database's own commit is the transaction's durability boundary. No separate commit protocol is layered on top of it.

1. Record intent. Before any file is moved, write the transaction's intent to the journal — the set of file operations, and for each the staged-file path and the path its displaced original will be backed up to (the backup map). The journal is part of the package database (§7.4.5.1); recording intent is an ordinary database write.
2. Apply file operations. For each operation, rename any displaced original aside as a backup (§7.5.1.3) and rename the staged file into place (§7.2 step 4, §7.3 step 3). Throughout this phase every change is individually reversible from the backup map.
3. Commit. In a single package-database transaction, write the new installed-package state and mark the journal's pending transaction committed. This database commit is the durability boundary: it is atomic, so the transaction is either fully committed or not committed at all.
4. Invoke deduplicated side effects (§7.4.6). Side effects run after the durability boundary; a side-effect failure therefore does not roll the transaction back — side effects are idempotent (§4.3), the transaction is already committed, and a failed side effect is reported and corrected by re-invocation.
5. Clean up. Discard staged files; backups become eligible for the retention window (§7.5.1.3).

A crash before step 3's database commit leaves the journal's transaction pending; recovery rolls it back (§7.4.7). A crash after it leaves the transaction committed; recovery has only clean-up to finish. The transaction is never found partly committed, so recovery never completes a half-finished commit.

§7.4.5.1 The journal

The transaction journal is part of the package database: the pending transaction is recorded as rows in the package-database store, not as a separate file with a separate format. Recording intent (§7.4.5 step 1) and committing (step 3) are therefore ordinary database writes, and the journal inherits the database's transactional guarantees (§7.4.8).

The package database — and therefore the journal — is stored under a security descriptor that grants write access only to the install-authority tier (the principals permitted to install packages on the system). That security descriptor is the journal's integrity protection: a principal outside the tier cannot forge a journal entry, and a principal inside the tier already holds installation authority, so a within-tier write is not an escalation.

The staging area is stored under the same security descriptor.

§7.4.6 Side-effect deduplication

A transaction MAY contain multiple operations that each declare the same side effect (e.g., installing several packages that all declare ldconfig). Side effects MUST be deduplicated and invoked once per transaction, after all file-level operations are complete.

Side effects are invoked in implementation-defined order. The fixed enumerated set of recognised side effects (§4.3) is designed such that order between distinct side effects is not significant. An implementation MAY invoke distinct side effects concurrently.

Future versions of this specification that add new side-effect identifiers MUST explicitly state whether the new effect is order-independent with respect to the existing set. Order-dependent side effects (if ever added) MUST be specified with a normative ordering relative to all other recognised side effects.

§7.4.7 Crash recovery

On startup, before permitting any new transaction, the package manager MUST check the journal for a pending transaction:

1. No pending transaction — the package database shows no transaction in the pending state: no recovery is needed.
2. A pending transaction exists: roll it back. Restore every displaced original from the backup map, discard the transaction's staged files, and clear the pending transaction from the journal.

There is no roll-forward. Because the database commit (§7.4.5 step 3) is the single durability boundary and is itself atomic, a recovered transaction is only ever in one of two states: committed (the database records it committed — nothing to recover) or pending (roll back). A transaction is never found partly committed, so recovery never has to complete a half-finished commit.

Recovery is itself crash-safe: every action it takes is a rename from the backup map, and re-running it after an interruption produces the same result.

§7.4.8 Visibility

The package database state visible to queries (peipkg query installed, etc.) MUST reflect only committed transactions.

The package database MUST provide snapshot-isolation reads: a query that begins reading the database at time T MUST see a consistent snapshot of committed state as of T, regardless of write transactions that commit during the query. A flat-file database read with naive read(2) does NOT satisfy this requirement; SQLite in WAL mode, or an equivalent transactional store with snapshot isolation, does.

In-progress transaction state SHOULD NOT be visible to non-package-manager processes. Staged files MUST NOT appear at their final install paths until commit.

The package manager MAY internally inspect uncommitted state for purposes of the transaction itself (e.g., verifying staged files); this is not a visibility leak.

Rollback is the procedure that restores the system to its state before a transaction or before a previous package version. This section covers two distinct rollback scenarios:

• Transaction rollback (§7.5.1): undoing an in-flight (uncommitted) transaction in response to a failure or cancellation.
• Version rollback (§7.5.2): user-initiated reversion of an installed package to a previously-installed or archived version, performed via the upgrade procedure.

§7.5.1 Transaction rollback

A transaction can be rolled back at any point before the database commit (§7.4.5 step 3). Once that commit succeeds the transaction is committed and rollback no longer applies; recovery from that point is clean-up only (§7.4.7).

§7.5.1.1 When transaction rollback occurs

A transaction is rolled back when any of the following happens before the database commit:

1. Any step in any operation within the transaction fails (e.g., a file's hash does not verify, disk space is exhausted, an SD is rejected by the kernel).
2. The user cancels the operation.
3. The package manager process terminates abnormally before commit (in which case rollback runs on the next package manager invocation per §7.4.7).

§7.5.1.2 Rollback procedure

To roll back an uncommitted transaction:

1. Discard staged content: remove the transaction's staged files.
2. Discard pending database changes: the journal's pending transaction is left uncommitted (the database commit, §7.4.5 step 3, never ran) and is cleared from the journal.
3. Restore originals: for every file the transaction displaced, rename its backup back into place (§7.5.1.3).
4. Release the transaction lock.

Side effects are not involved in rollback. Side effects run only after the database commit (§7.4.5 step 4); a rolled-back transaction never reached that commit, so no side effect of it ever ran and there is nothing to undo.

§7.5.1.3 Backups

A backup is made by renaming the displaced original aside within its own directory (§7.2 step 4, §7.3 step 3) — not by copying it. The old file's content is retained in place under a different name, so a backup costs no additional disk space and is produced by a single atomic rename. The journal's backup map records, for each displaced file, the path its backup was renamed to.

A backup is restored — on rollback — by renaming it back into place, and discarded — on successful commit — by deleting it.

A package manager MAY retain backups beyond commit, for a configured retention window, to support post-commit operator-initiated rollback (§7.5.2). The window — for example a number of recent transactions, or an age — is operationally configured and not specified normatively.

§7.5.1.4 Rollback completeness

A successful rollback MUST leave the system in a state indistinguishable from the state immediately before the transaction began.

This MUST include:

• File contents and existence as before.
• File security descriptors as before.
• Package database contents as before.
• The transaction journal in a no-pending-transaction state.

A rollback that cannot achieve this state due to underlying I/O errors or filesystem corruption MUST be reported as a failed rollback and the system MUST be considered to be in an indeterminate state. The package manager SHOULD prevent further transactions until the indeterminate state is resolved.

§7.5.1.5 Recovery from indeterminate state

When the package manager detects an indeterminate state (failed rollback, corrupt journal, unrecoverable backup mismatch), it MUST enter a recovery mode with the following properties:

1. All write operations (install, upgrade, uninstall) MUST be refused until recovery completes.
2. Read operations (query, integrity check) MAY proceed but MUST surface the indeterminate-state warning in their output.
3. The package manager MUST produce a forensic report on demand, identifying:
   • The journal's pending transaction (which operations were in flight)
   • Files whose on-disk content does not match the hash recorded in the package database
   • Package database records inconsistent with the journal
   • Any orphaned staged files or backups
4. The package manager MUST provide an explicit resolution command (e.g. peipkg recover) that accepts an operator decision: roll the pending transaction back, or accept the current on-disk state and discard the journal and backups.
5. Resolution MUST be a deliberate operator action and MUST NOT be performed automatically — automatic resolution of an indeterminate state is forbidden.

After resolution, the package manager exits recovery mode and resumes normal operation. The forensic report SHOULD be retained for operator audit.

§7.5.1.6 Recovery and package-manager self-upgrade

Upgrading the package manager is not a special case for recovery. The package-manager binary is one file among a transaction's payload, backed up by rename like any other (§7.5.1.3); "recovery" reconciles a transaction that crashed between its atomic steps, not a half-written binary — the binary swap is itself a single atomic rename.

The only wrinkle is that, after a self-upgrade, the binary running the next recovery may be a different version from the one that started the transaction. This is handled by versioning the journal format: any package-manager version that can read a pending transaction's journal schema recovers it directly; a version that cannot defers to manual recovery mode (§7.5.1.5). No dedicated "immutable previous-binary copy" is required — if recovery needs the prior binary, it is already present as that binary's ordinary backup (§7.5.1.3).

§7.5.2 Version rollback

Version rollback is a user-initiated operation that reverts an installed package to a different (typically earlier) version. It is implemented via the upgrade procedure (§7.2) with the target version being the desired older version.

§7.5.2.1 Procedure

A version rollback is performed by:

1. Querying the archive index (§6.3) for the available versions of the target package.
2. Selecting the desired older version.
3. Invoking upgrade (§7.2) with the older version as the "new" version. This requires explicit user authorisation per §7.2.5 since the operation is a downgrade.

The transaction is performed in the standard way (§7.4) with the standard atomicity and crash-safety guarantees.

§7.5.2.2 Constraints

A version rollback target MUST be available from a configured repository's archive index. Local-only rollback (without re-fetching) is permitted only if the archive package was previously cached.

A version rollback MAY require dependent package adjustments if the dependent package's constraints are not satisfied by the older version. The resolution procedure (§4.2) determines this; the resulting plan may include additional downgrades or removals.

§7.5.2.3 Limitations

Version rollback can only roll back to versions that the repository archive retains (§6.3.1). Versions pruned from the archive cannot be rolled back to without external package files (e.g., a manually-saved .peipkg from a previous backup).

Version rollback does NOT roll back changes outside the package's payload: registry state, system configuration materialised by reconcillers, runtime data under /var/, and any user data are unaffected by package version changes.

This section describes the privilege model the package manager operates under and the audit obligations it carries. Both are Peios-specific concerns that build on KACS (PSD-004) and KMES (PSD-008).

§7.6.1 Privilege model

The package manager holds no principal, identity, or access rights of its own. It runs as the calling operator: every file operation it performs — creating, replacing, or deleting a payload file — is checked by KACS (PSD-004) against the caller's token and the target's security descriptor. If the caller is authorised the operation succeeds; if not, it fails. The package manager contributes no authority.

The authority to install a package is therefore exactly the authority to write the directories the package installs into — an ordinary matter of security descriptors on /usr/, /etc/, /var/, and /opt/. A deployment grants installation authority by granting those write rights to whichever principals it intends to be able to install software (typically a system administrators group).

A consequence: a package's manifest-declared SD overrides (§3.4.7) can only assign security descriptors the calling operator already has the authority to assign. A package cannot, through the package manager, obtain authority the operator running it does not hold. Where §3.4.7 and PSD-004 require a particular right to apply a given SD — for example WRITE_DAC for a DACL, or WRITE_OWNER and SeRestorePrivilege for an owner-SID assignment — that right MUST be held by the operator, not by the package manager.

§7.6.2 Blast radius

Because the package manager holds no principal of its own (§7.6, "Privilege model"), there is no standing privileged identity to confine and no privileged process to compromise. The authority exercised during an install is the calling operator's, and only for the duration of that invocation.

The blast radius of installing a malicious or defective package is therefore bounded, precisely, by the authority of the operator who installed it: a malicious package can do nothing the operator could not already do directly. This makes the trust decision — which repositories an operator configures, and which packages an operator with broad authority chooses to install — the operative security boundary. Signature verification (chapter 5) and the repository trust model (§6.5) exist to inform that decision; they do not substitute for it.

The package manager does not require, and SHOULD NOT be run with, authority beyond what installation needs: write access to the payload destinations of §3.4.1, and network access to fetch from configured repositories. It performs no kexec, loads no kernel modules except via the depmod side effect (§4.3), loads no BPF programs, and writes no registry state — its own bookkeeping is a private store (§7.4.5.1), not the registry.

§7.6.3 Audit

Every install, upgrade, uninstall, refresh, and recovery operation MUST emit an audit event. The package manager emits events through the kmes_emit system call into KMES, the kernel event subsystem (PSD-008). Because emission is a local kernel call and not a message to a userspace daemon, it has no "destination unreachable" failure mode: there is no reachability probe, no fail-closed-on-unavailable rule, and no audit-retention journal. Whether and when KMES events are drained and persisted is the concern of eventd, not of the package manager.

An emitted event MUST include at minimum:

• Operation type (install, upgrade, uninstall, refresh, recovery)
• The calling operator's KACS identity
• Target package(s): name, version, architecture
• Source repository (for install and upgrade)
• Outcome (success, rejection, rollback), with a rejection reason where applicable
• Transaction identifier
• An RFC 3339 UTC timestamp

The package manager MUST emit a success event for a committed operation and a separate failure event for one that is rejected or rolled back.

§7.6.3.1 Canonical event types

Audit events emitted by the package manager MUST use event-type strings drawn from the following set so that KMES per-event-type access control (PSD-008) can target peipkg events precisely:

The origin_class for all peipkg events is peipkg. Future versions of this specification MAY add additional event-type strings to this set; consumers of the audit stream MUST treat unknown event types as informational (not as errors).

§7.6.4 Trust anchor distribution

Trust anchors for the official Peios repository (the fingerprints used at repo-add per §6.5.2) MUST be available to the package manager from the OS image — a file installed by the base system, outside any package. The exact path is operationally defined; a future PSD covering OS-image construction is expected to standardise it.

Custom-repository trust anchors are supplied by the operator at repo-add time per §6.5.2.

§7.6.5 Clock dependence

Several normative checks depend on the local system clock: signing-key valid_until timestamps (§6.1.4), maximum trusted age (§6.5.4), maximum index staleness (§6.2), and build provenance timestamps (§3.3.4). An attacker able to manipulate the local clock can extend a transitioning key's validity, evade staleness checks, or hide compromise-detection windows.

§7.6.6 Operator authorisation

Several points in this specification call for "operator authorisation": signature-policy optional operations (§6.5.3), downgrade (§7.2.5), recovery resolution (§7.5.1), a maximum-trusted-age override (§6.5.4), the allow_insecure_transport toggle (§6.4), a clock-state override (§7.6.5), and trust-anchor disagreement resolution (§7.6.4).

In v0.22, operator authorisation means a deliberate, explicit act by the operator: at minimum an affirmative confirmation, specific to the elevated action in question and distinct from the routine prompt to proceed with an operation. It MUST NOT be inferred, defaulted, or auto-supplied by the package manager. The authorising act and what it authorised MUST be recorded in the audit stream (§7.6.3, event type peipkg.authorisation).

§7.6.7 Build-farm trust

The farm_id field in the manifest's build object (§3.3.4) and in index entries (§6.2.4) identifies the build farm that produced a package. This specification does not normatively constrain farm_id values, but consumers MAY enforce farm_id constraints per repository as defence-in-depth: e.g., for the official Peios repository, the consumer MAY refuse to install packages whose farm_id is not in a configured allowlist of legitimate farms.

This is operational defence-in-depth, not a format-level guarantee. A compromised build farm whose private signing key is intact can sign packages with any farm_id value; farm_id-based filtering protects only against configuration mistakes (e.g., a stale farm whose key was rotated but whose farm_id is still recognised) and against an attacker who has obtained a key but not the operational identity of the legitimate farm.

§7.6.8 Cross-spec coordination requirements

Several defences this chapter describes as intended end states depend on mechanisms not yet specified in peer Peios PSDs as of v0.22. These are coordination points for future specification work, not gaps in a conformant v0.22 implementation — which uses the lighter v0.22 model described in each case.

These coordination points should be addressed in future revisions of PSD-004, PSD-005, and PSD-008, alongside the future reconciller-framework and OS-image PSDs.

§7.6.9 Threats out of scope

The following threats are explicitly out of scope for this specification, and are addressed by other Peios subsystems or by the operator:

• Compromise of an installing operator's KACS identity. The package manager runs with the operator's authority (§7.6, "Privilege model"); if that operator's KACS state is compromised, no format-level defence helps. KACS's own audit and recovery mechanisms apply.
• Side-channel attacks on installed binaries. Spectre-class, cache-timing, and similar attacks against installed software are not the package format's concern; they are addressed by the kernel and by software-specific mitigations.
• Physical attacks on storage media. A physically compromised disk can have its package database or installed files altered offline. Hash verification at use time (out of this spec's scope) is the appropriate defence.
• Compromise of the build farm itself. A compromised build farm can sign malicious packages with trusted keys. Detection requires reproducible-builds verification by independent parties (appendix A).
• Network-level censorship or denial-of-service preventing package fetching. Operational concern.

These exclusions are honest acknowledgements, not weaknesses to dismiss. Each is a real concern; each is addressed elsewhere.

§8.1.1 Reproducibility

A reproducible build farm produces byte-identical packages from the same inputs across runs and operators. Achieving this requires controlling everything the build process can observe: timestamps, file ordering, locale, environment variables, ambient filesystem state, build paths.

The format's determinism rules (§3.1.4) are necessary but not sufficient: they specify what the package must look like, not how to produce it. Operators are expected to use established techniques:

• SOURCE_DATE_EPOCH: a single epoch timestamp that every build tool reads to set timestamps in outputs. The Reproducible Builds project's conventions apply.
• Sealed build environments: container or VM-based builds where the full build dependency closure is pinned (specific versions of compilers, libraries, build scripts). The dependency closure is itself a build input that determines the output.
• Locale and time zone normalisation: builds run in LC_ALL=C and TZ=UTC to suppress locale-dependent output ordering and time formatting.
• Build path normalisation: tools like BUILD_PATH manipulation or RECORDED_BUILD_DIR keep absolute paths from leaking into compiled binaries (debug info, embedded paths).

The build.farm_id and build.source_ref fields in the manifest (§3.3.4) record the producer and inputs. A recipient who has access to the same inputs and the same farm's tooling can re-run the build and verify output matches.

§8.1.2 Farm identifiers

The build.farm_id value is producer-defined. Conventions that work well in practice:

• A short organisational identifier plus a generation number: peios-build-1, peios-build-2. The generation number bumps when the farm's tooling or hosting changes substantively.
• A combination of organisation and farm-specific role: peios-build-amd64, peios-build-arm64.

Farm identifiers should not encode information that changes per-build (such as a build sequence number); they identify the farm, not the build.

A farm identifier should be stable across many builds. Changing the farm identifier without an underlying operational change defeats reproducibility verification: the same package built on the same farm should report the same farm_id.

§8.1.3 Source references

The build.source_ref field is producer-defined. The recommended form is a machine-resolvable reference that fully identifies the build inputs:

git+https://git.peios.org/sources/nginx#refs/tags/v1.26.2-3

The form's components:

• A scheme identifying the source-control system (git+, hg+, etc.).
• An HTTPS URL for the repository.
• A fragment identifier specifying an exact ref (a tag, commit hash, or annotated reference).

Tags are preferred over commit hashes for human-readable provenance. Annotated tags are preferred over lightweight tags for cryptographic stability.

A source reference SHOULD be sufficient by itself to recover the inputs. References that depend on transient or mutable state ("the latest from main", a relative date) are not reproducible and SHOULD be avoided.

§8.1.4 Signing key custody

Signing keys grant the holder the ability to publish packages indistinguishable from official packages. Their protection is the most security-critical operational concern of a build farm.

Recommended practices:

• Hardware security modules: signing operations occur inside an HSM, where the private key never leaves the device. Hardware keys (YubiKey, Nitrokey) suffice for smaller operations; HSMs (CloudHSM, Nitro Enclaves) for larger.
• Threshold signing: split the signing key across multiple parties such that no single party can produce a signature alone. Schemes like FROST, GG20, or simpler Shamir-based custody.
• Air-gapped signing: the signing operation runs on a network-isolated machine. Packages are physically or cryptographically transferred for signing.
• Key rotation schedule: rotate signing keys periodically (annually or after major operational changes), even without suspicion of compromise. Use the rotation flow in §5.2.6.
• Key fingerprint publication: publish trust anchor fingerprints through multiple independent channels (project website, OS image, documentation, package manager preconfiguration) so users can cross-check.

These practices apply equally to the official Peios project's keys and to operators of custom repositories.

§8.1.5 Build attestations

Future versions of this specification may introduce formal build attestation as a sibling artifact published alongside packages (see §6.4.4 sibling artifacts).

Attestations describe how a package was built: the build environment, the inputs (resolved to specific versions and hashes), the timestamp, and the attestation producer's signature. Attestations enable consumers (or auditors) to verify reproducibility independently of the producer.

The SLSA (Supply-chain Levels for Software Artifacts) framework defines a graduated set of attestation practices. SLSA Level 3 corresponds approximately to:

• Signed build provenance describing the inputs.
• Hermetic, sealed build environments.
• Build platform integrity (the platform that ran the build is itself trustworthy and tamper-resistant).

Operators of significant repositories (especially the official Peios project) SHOULD aim for SLSA Level 3 or equivalent practices, even though attestations themselves are not yet a normative artifact in this specification.

§8.1.6 Pre-publication checks

Before publishing a built package, the build farm SHOULD verify:

• The package's hash matches the recorded hash.
• The signature verifies against the publishing key.
• The package can be installed cleanly in a fresh test environment.
• The dependency declarations are consistent (no references to non-existent packages, no impossible version constraints).
• Re-running the build from the same inputs produces a byte-identical package.

These checks catch errors before they propagate to consumers. The cost of catching an error pre-publication is low; the cost of an incorrect published package is high (re-publication, possible user-facing rollback).

§8.1.7 Repository operations

A repository operator is responsible for:

• Maintaining the repository descriptor (§6.1) with current signing key state.
• Generating the active and archive indexes (§6.2, §6.3) whenever a new package is published.
• Signing the descriptor and indexes.
• Hosting the static files.
• Retaining archived package versions per §6.3.1.
• Communicating with consumers about key rotations, package retirements, and other operational events.

These responsibilities scale with repository size and trust level. The official Peios project carries them all fully; a homelab custom repository may operate with much lighter ceremony.

§8.2.1 Purpose and scope

A recipe is the input to a producer toolchain: a small TOML file plus a build script that together describe how to turn an upstream source tree into one or more .peipkg files.

Recipes are conventionally laid out as:

recipes/
  <package>/
    peipkg.toml      # the recipe document
    build.sh         # the build script (or whatever build_script names)

A recipe is consumed by multiple producer-side tools, each of which interprets the parts of the recipe relevant to its responsibilities. The format is therefore designed for partial parsing: each tool decodes the sections it owns and tolerates sections owned by other tools.

§8.2.2 Top-level sections

The recipe file's top-level sections are partitioned by which tool owns them:

Tools MUST tolerate top-level sections they do not own. A peipkg-build implementation that encounters [upstream] or [watch] while parsing a recipe MUST NOT reject the recipe; it ignores those sections and processes the ones it owns. The same applies in reverse for peipkg-manager.

Tools MUST reject unknown keys within sections they do own as typo errors. peipkg-build's parser, for instance, rejects [meta].homepag (typo of homepage) but accepts an entire [upstream] section because [upstream] is not under its authority.

§8.2.3 peipkg-build sections

§8.2.3.1 [meta]

[meta]
license = "Zlib"                          # SPDX identifier or expression
homepage = "https://zlib.net"             # upstream URL
source = "github:madler/zlib"             # informational only
build_script = "build.sh"                 # path to the build script (relative to the recipe dir)

§8.2.3.2 [[package]]

One stanza per output .peipkg. A recipe with three stanzas emits three packages (e.g. runtime, -dev, -doc) per architecture.

[[package]]
name = "libfoo"
architecture = "x86_64"
description = "Brief one-line description."
dependencies = [{ name = "libc" }]
optional_dependencies = []
conflicts = []
provides = []
replaces = []
side_effects = ["ldconfig"]
files = [
  "usr/lib/x86_64-linux-peios/libfoo.so.1",
  "usr/lib/x86_64-linux-peios/libfoo.so.1.*",
]

The schemas of dependencies, optional_dependencies, conflicts, provides, and replaces mirror the manifest schemas (§4.1). side_effects is the §4.3.4 enumerated list. The files field is the producer-side glob list that partitions a built tree across multiple stanzas.

A recipe-level convenience: dependency entries MAY carry a same_build = true shorthand, which the producer rewrites at build time into a strict version-equality constraint pinned to the build's own version. This handles the "-dev depends on runtime at exactly this build's version" case without forcing the recipe to know its own version.

[[package]]
name = "libfoo-dev"
architecture = "x86_64"
dependencies = [
  { name = "libfoo", same_build = true },
  { name = "libc-dev" },
]
files = ["usr/include/**", "usr/lib/x86_64-linux-peios/libfoo.so", ...]

§8.2.4 peipkg-manager sections

§8.2.4.1 [upstream]

Describes where to fetch source for new versions and how to recognise version tags.

[upstream]
git = "https://github.com/madler/zlib"
tag_pattern = "^v(\\d+\\.\\d+\\.\\d+)$"
peios_revision = 1

§8.2.4.2 [watch]

Describes how the build farm becomes aware of new upstream versions.

[watch]
github_webhook = true       # accept GitHub push/tag webhooks for this repository
poll_interval = "1h"        # belt-and-braces: also poll git tags at this interval

A recipe that omits [watch] is built only on explicit operator request. A recipe that omits [upstream] is not auto-built at all; the package exists for manual builds only.

§8.2.5 Versioning and stability

The recipe format described in this appendix is the format implemented at PSD-009 v0.22's release. Subsequent versions of this specification may extend it (new sections, new fields within existing sections). The "tools tolerate unknown top-level sections" rule preserves forward compatibility: older tools encountering newer sections ignore them safely.

Within owned sections, new fields are additive: tools SHOULD ignore unknown keys within their own sections when reading recipes that may have been authored against newer specifications, while still rejecting unknown keys when the recipe is authored against the same or older specification. The mechanism for distinguishing these cases is left to implementations; a schema_version field within [meta] is a reasonable extension point.

§9.1.1 Manifest

Defined normatively in §3.3.

{
  "schema_version": 1,
  "name": "<string>",
  "version": "<string>",
  "architecture": "<string>",
  "description": "<string>",
  "license": "<string>",
  "homepage": "<string>",
  "dependencies": [<dependency>...],
  "optional_dependencies": [<dependency>...],
  "conflicts": [<dependency>...],
  "provides": [<provides>...],
  "replaces": [<replaces>...],
  "side_effects": [<string>...],
  "size_installed": <integer>,
  "sd_overrides": [<sd_override>...],
  "build": {
    "timestamp": "<RFC 3339>",
    "farm_id": "<string>",
    "source_ref": "<string>"
  }
}

§9.1.2 Dependency

Defined normatively in §4.1.1.

{
  "name": "<string>",
  "constraint": "<string>",
  "arch": "<string>"
}

name required; constraint and arch optional. arch defaults to any.

§9.1.3 Conflict

Defined normatively in §4.1.2. Schema identical to dependency.

§9.1.4 Provides

Defined normatively in §4.1.4.

{
  "name": "<string>",
  "version": "<string>"
}

name required; version optional.

§9.1.5 Replaces

Defined normatively in §4.1.5.

{
  "name": "<string>",
  "constraint": "<string>"
}

name required; constraint optional.

§9.1.6 SD override

Defined normatively in §3.3.5.

{
  "path": "<payload-relative path>",
  "sd": "<base64-encoded SD>"
}

Both fields required. Path MUST refer to a regular-file or directory tar entry, never a symlink.

§9.1.7 Files manifest

Defined normatively in §3.5.1.

{
  "schema_version": 1,
  "algorithm": "sha256",
  "entries": [
    {
      "path": "<string>",
      "size": <integer>,
      "hash": "<lowercase hex>"
    }
  ]
}

Stored at .peipkg/files.json. Contains exactly one entry per regular-file payload entry in the tar archive.

§9.1.8 Signature envelope

Defined normatively in §5.1.3.

{
  "schema_version": 1,
  "algorithm": "ed25519",
  "key_fingerprint": "<lowercase hex SHA-256, 64 chars>",
  "signature": "<base64 without padding>"
}

Stored at .peipkg/signature as the last named tar entry.

Strict parsing: unknown fields cause rejection (deliberate exception to the manifest's permissive forward-compat rule).

§9.1.9 Repository descriptor

Defined normatively in §6.1.

{
  "schema_version": 1,
  "repo": {
    "name": "<string>",
    "description": "<string>",
    "signing": {
      "algorithm": "ed25519",
      "keys": [
        {
          "fingerprint": "<lowercase hex>",
          "url": "<string>",
          "status": "active|transitioning"
        }
      ]
    }
  },
  "indexes": {
    "active": {
      "url": "<string>",
      "signature_url": "<string>"
    },
    "archive": {
      "url": "<string>",
      "signature_url": "<string>"
    }
  }
}

Each keys entry has the form:

{
  "fingerprint": "<string>",
  "url": "<string>",
  "status": "active|transitioning|revoked",
  "valid_until": "<RFC 3339>"
}

valid_until is REQUIRED for transitioning keys and ignored for other statuses.

Hosted at <repo-base>/repo.json. Detached signature at <repo-base>/repo.json.sig.

§9.1.10 Active index

Defined normatively in §6.2.

{
  "schema_version": 1,
  "repo": "<string>",
  "kind": "active",
  "index_version": <integer>,
  "generated_at": "<RFC 3339>",
  "packages": [<package_entry>...]
}

One entry per package; entries sorted lexicographically by name; one version per name.

index_version is monotonically increasing across publications; consumers enforce non-decreasing refresh to defend against rollback attacks.

§9.1.11 Archive index

Defined normatively in §6.3.

Top-level schema identical to active index (§6.2.2) except kind is archive and entries MAY repeat by name (one entry per historical version).

Sorted lexicographically by name, then by version descending within name.

§9.1.12 Index package entry

Defined normatively in §6.2.4.

{
  "name": "<string>",
  "version": "<string>",
  "architecture": "<string>",
  "description": "<string>",
  "license": "<string>",
  "homepage": "<string>",
  "dependencies": [<dependency>...],
  "optional_dependencies": [<dependency>...],
  "conflicts": [<dependency>...],
  "provides": [<provides>...],
  "replaces": [<replaces>...],
  "side_effects": [<string>...],
  "size_compressed": <integer>,
  "size_installed": <integer>,
  "hash": {
    "algorithm": "sha256",
    "value": "<lowercase hex>"
  },
  "url": "<string>",
  "build": {
    "timestamp": "<RFC 3339>",
    "farm_id": "<string>"
  }
}

Required: name, version, architecture, dependencies, conflicts, size_compressed, size_installed, hash, url. Other fields recommended but optional. size_compressed and size_installed are required to enable consumer-side decompression-bounds enforcement (§3.5.4).

The index package entry omits the manifest's sd_overrides field, the build.source_ref field, and the manifest's own schema_version field. These remain in the package's own manifest.

§9.2.1 Architecture identifiers

Defined normatively in §2.3.2.

x86_64 is the primary target. aarch64 is secondary. noarch is for architecture-independent packages.

§9.2.2 Side-effect identifiers

Defined normatively in §4.3.4.

The set is closed in this version. A v0.22-conformant implementation MUST reject manifests declaring side-effect identifiers outside this set.

§9.2.3 Pre-release rank tokens

Defined normatively in §2.2.7.2.

Rank 0 is lowest (sorts first). Rank 5 tokens are compared lexically against each other.

Token matching is case-insensitive (Alpha, ALPHA, and alpha all rank 1).

§9.2.4 Hash algorithms

Defined normatively in §3.5.5.

A v0.22-conformant implementation MUST reject any algorithm identifier other than sha256.

§9.2.5 Signature algorithms

Defined normatively in §5.2.1.

A v0.22-conformant implementation MUST reject any algorithm identifier other than ed25519.

§9.2.6 Signing key statuses

Defined normatively in §6.1.4.

A status value other than active, transitioning, or revoked is INVALID.

transitioning keys MUST carry a valid_until RFC 3339 timestamp; consumers MUST reject signatures from a transitioning key after that timestamp.

revoked keys MAY remain in the descriptor for at least one year after revocation as a public compromise acknowledgement; signatures from revoked keys MUST be rejected regardless.

§9.2.7 Signature policy

Defined normatively in §6.5.3.

The default for newly-added repositories SHOULD be required.

There is no silently-accept-unsigned policy. Consumers intentionally permitting unsigned content use optional, which always emits a per-operation warning to the operator.

§9.2.8 Index kind values

Defined normatively in §6.2.2 and §6.3.3.

§9.2.9 Constraint operators

Defined normatively in §2.2.8.

A bare version string with no operator is equivalent to =. Multiple constraints are combined with comma-AND.

§9.2.10 Reserved metadata paths

Defined normatively in §3.2.1, §3.2.2.

The .peipkg/ prefix is reserved; payload entries MUST NOT use it.

§9.2.11 Permitted top-level install paths

Defined normatively in §3.4.1.

Payload entries MUST NOT install under any other top-level path. Entries under /boot/ SHOULD be symlinks (§3.4.1).

§9.3.1 Top-level comparison

To compare two version strings A and B per §2.2.6:

1. Compare epochs (§2.2.2). If they differ, the higher epoch is greater.
2. If equal, compare upstream versions per the upstream comparison algorithm below.
3. If equal, compare peios revisions (§2.2.4) as integers. Higher revision is greater.
4. If all three are equal, the versions are equal.

§9.3.2 Upstream comparison algorithm

Defined normatively in §2.2.7.

§9.3.2.1 Tokenisation

A tokeniser walks the upstream string left to right and emits a sequence of segments:

1. Non-alphanumeric characters (., +, -, ~) are separators and are not part of any segment.
2. A maximal run of digits forms a numeric segment.
3. A maximal run of letters forms an alphabetic segment.
4. A transition between digit and letter ends the current segment and begins a new one.

The tilde ~ begins a pre-release tail: it and every later segment are pre-release segments.

§9.3.2.2 Segment-pair comparison