# Build and release artifact specification

[`PRODUCT.md`](PRODUCT.md) incorporates this document as normative version 1 behavior.
This document defines artifacts produced by this repository. Official Termux package artifacts
remain owned by [`TERMUX_PACKAGES.md`](TERMUX_PACKAGES.md).

## Artifact classes

Version 1 has three artifact classes:

1. **Build artifact:** an executable and manual page produced from one source tree for testing or
   packaging.
2. **Release input:** an immutable source archive and checksum manifest supplied to downstream
   packagers.
3. **Evidence artifact:** bounded test, benchmark, or publication output retained to support a
   specific release decision.

A local build, release input, evidence artifact, Termux recipe, and official Termux package are
non-equivalent. UI labels, logs, release notes, and publication records use these exact terms.

## Identity

One canonical version value supplies:

- `termux-janitor --version`;
- the manual page version;
- the source tag and release-input name;
- downstream package versions, subject to downstream syntax and revision rules.

The canonical source tag is immutable after publication. Rebuilding changed source requires a new
version; rebuilding unchanged source may create new evidence but never replaces an existing release
input. A checksum identifies bytes, not authenticity or semantic equivalence.

Release-input filenames use `termux-janitor-{version}.tar.gz` and `SHA256SUMS`. `{version}` is the
canonical version without a downstream package epoch or revision. Filenames contain only ASCII
letters, digits, `.`, `-`, `_`, and `+`.

## Build artifact

The normal repository build places the executable at `zig-out/bin/termux-janitor` and stages the
manual page according to [`MAN_PAGE.md`](MAN_PAGE.md#artifact). A release build uses Zig
`ReleaseSafe`; disabling runtime safety for release size or speed is forbidden.

The executable:

- targets the selected Termux Android architecture and API contract;
- uses no undeclared runtime library or interpreter;
- contains no secret, source-control credential, publisher home path, or temporary build path;
- obtains runtime paths from the Termux environment rather than a build-host prefix;
- reports the canonical version without invoking Git or accessing the network at runtime;
- remains functionally unchanged by symbol stripping.

Debug information may be retained as a separate evidence artifact. Stripping never changes the
canonical source identity or hides the unstripped binary used to diagnose a release failure.

## Release input

The source archive contains everything required to build and verify the release without repository
history. It includes source, `build.zig`, the pinned Zig version, license material, manual-page
source, and the complete `spec/` directory.

It excludes:

- `.git/`, `.zig-cache/`, `zig-out/`, editor state, and operating-system metadata;
- built executables, object files, local packages, profiling output, and test output;
- configuration, run logs, scan data, home-directory content, credentials, and secrets;
- untracked files not explicitly registered as release input.

Archive entries have deterministic lexical order, normalized owner and group identifiers, normalized
permissions, and one timestamp derived from `SOURCE_DATE_EPOCH`. They use relative paths below one
top-level `termux-janitor-{version}/` directory. Symlinks, hard links, device nodes, sockets, FIFOs,
absolute paths, `..` components, duplicate paths, and case-colliding paths are forbidden.

`SHA256SUMS` contains exactly one SHA-256 entry for each published release input, sorted by
filename. It contains no absolute path. Hash verification precedes extraction or downstream
packaging.

## Evidence artifacts

Evidence is identified by release version, source commit, Zig version, target tuple, build mode,
command, relevant capability probe, and result. Platform evidence also records the operating system,
Termux application source and version, Android version, architecture, filesystem, and observation
time when applicable.

Captured stdout, stderr, traces, diffs, and logs obey the bounds and redaction rules in
[`LIMITS.md`](LIMITS.md) and [`TESTING.md`](TESTING.md). Evidence never contains credentials,
unrestricted environment dumps, unrelated home content, or private path payloads.

A failed check retains enough bounded evidence to reproduce the failure. Evidence does not become a
product input, resume authority, telemetry record, or claim about an untested platform.

## Reproducibility

Two release-input builds from clean checkouts of the same commit, using the same version and
`SOURCE_DATE_EPOCH`, must produce byte-identical source archives and checksum manifests.

Two executable builds with identical declared toolchain, target, build mode, source archive, and
environment contract are expected to be byte-identical. A difference blocks release until explained
and recorded. An accepted explanation must identify the differing bytes, their producer, why runtime
behavior and provenance remain unchanged, and the corrective or containment action.

Reproducibility never substitutes for functional, safety, platform, or package acceptance tests.

## Verification

The artifact gate runs from a clean source archive and must:

1. verify the checksum manifest before extraction;
2. reject every forbidden archive entry type or path;
3. compare archive contents with the registered release-input manifest;
4. build with the pinned Zig version without network access after declared source acquisition;
5. run `zig build check` and every release gate required by [`TESTING.md`](TESTING.md#gates);
6. verify executable target, build mode, version, runtime libraries, and path hygiene;
7. parse, render, install, and resolve the manual page;
8. rebuild the source archive and compare it byte for byte;
9. rebuild the executable under the same declared environment and investigate any difference;
10. leave the extracted source tree unchanged except for ignored build outputs.

Every command failure, missing tool, skipped check, undeclared input, checksum mismatch, unexpected
output, or source-tree change fails the artifact gate. Deleting evidence or rerunning until a result
happens to pass does not resolve a failure.

## Retention and publication

Published release inputs are immutable. Corrections use a new version and preserve the old artifact
and checksum for audit unless removal is required for a confirmed security or legal issue. Such a
removal is recorded explicitly and never reuses the old filename or tag for changed bytes.

Evidence retention follows the release and testing policy. Local build artifacts may be deleted at
any time because they carry no publication authority. Official package retention, replacement, and
mirror deployment remain controlled by Termux maintainers.