Developer Installation Package Guide

Test Datastore Deployment Kit contract

The ordinary ahri-tre-<version>-<target> archives described below are release inputs; they are not the complete AHRI TRE Test Datastore Deployment Kit. The 0.2.0 contract and its v0.10.3-based server remain superseded historical artifacts in contract-v0.2.0.json.

The current MinisForum installed-conformance successor is the closed v3 0.3.23 composition contract in minisforum-contract-v0.3.23.json. It binds the published v0.10.12 server, client, and validator artifacts containing the numeric OAuth Dataset Variable-order correction. Earlier candidate archives and published kits through 0.3.22 remain immutable.

The original fixed-site contract remains frozen at deployment/test-datastore-kit/contract-v0.1.0.json. The current repository deployment/test-datastore-kit/contract.json records v3; P2.11c already isolates v1, v2, and v3 parsing and rendering.

The complete required artifact surface is versioned in deployment/test-datastore-kit/contract.json. It covers the Linux server, specialized site bundle, WSL2 and Apple Silicon macOS clients, conformance harness, clean-host evidence, SBOMs, dependency reports, licences, recovery tools, and artifact-bound runbooks. Its base-release record pins each selected archive, its .sha256 publication asset, and the expected archive digest:

Maintainers validate the source contract with:

cargo run -p xtask -- test-datastore-kit check-contract

Once every declared artifact has been produced under one staging root, assembly is explicit and requires the clean checkout’s full 40-character kit source revision:

KIT_SOURCE_REVISION="$(git rev-parse --verify HEAD)"
cargo run -p xtask -- test-datastore-kit assemble \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.0 \
  --source-revision "$KIT_SOURCE_REVISION"

Assembly writes manifest.json and SHA256SUMS only after every required file exists and the Linux server, clean WSL2 client, and clean Apple Silicon macOS client evidence all report go. The supplied kit source revision must equal the current clean committed checkout; source-generated and site-generated artifacts bind to it. Release-origin artifacts separately retain the v0.10.4 base-release revision pinned by the contract. Assembly rejects absolute or parent paths, symlinks, missing artifacts, unmanifested executables, build-time Restricted local references, private-key and credential markers in textual public artifacts, inconsistent kit versions, unsupported targets, and no-go qualification evidence. Pinned binaries, libraries, and archives are opaque checksum-bound inputs because runtime libraries can legitimately embed parser marker strings. CI validates this contract on every change, but it deliberately has no kit publication step until the later installed-package and clean-host issues supply all required evidence.

Test Datastore Linux server package

Ticket 02 supplies the deterministic server-deliverable command:

cargo run --locked -p xtask -- test-datastore-kit package-server \
  --contract "$RELEASE_CONTRACT" \
  --release-archive downloads/ahri-tre-0.10.4-x86_64-unknown-linux-gnu.tar \
  --release-checksum downloads/ahri-tre-0.10.4-x86_64-unknown-linux-gnu.tar.sha256 \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.0 \
  --source-revision "$RELEASE_SOURCE_REVISION"

The packaging command verifies the pinned archive name and SHA-256, its published checksum file, exact release source revision, and x86-64 ELF identity. It extracts the release-origin CLI, local daemon, Trusted runtime, Web control plane, C ABI, header, and DuckDB without rebuilding them, then generates the public Application and protocol schemas through the staged release CLI, audits every executable and shared-library dependency, and launches every staged executable without a Cargo target-directory path. Publication of server/ is atomic; a bad digest, source revision, architecture, dependency, launch check, or schema response leaves no partial deliverable.

The server deliverable contains systemd, sysusers, and tmpfiles definitions plus install, upgrade, rollback, diagnostic, and uninstall commands. To stage a filesystem image without activating identities or services, use:

DESTDIR=/path/to/image ./server/install.sh

On a new supported host, run sudo ./server/install.sh; on the MinisForum with the superseded server package already present, run sudo ./server/upgrade.sh. It creates or preserves the dedicated ahri-tre-runtime and ahri-tre-web identities and the declared configuration, runtime, Managed-secret, Injected-secret, log, scratch, and backup boundaries. It installs only ahri-tre in /usr/bin; ahri-tred remains a local Managed runtime component under /usr/libexec/ahri-tre and is never exposed as the multi-user Trusted runtime.

The installer does not invent Application configuration or Secret values and does not start either service. After the site bundle has installed /etc/ahri-tre/config.toml and its declared prerequisites, validate and start the Trusted runtime with:

sudo /usr/libexec/ahri-tre/diagnose.sh preflight-runtime
sudo /usr/libexec/ahri-tre/diagnose.sh dependencies
sudo systemctl enable --now ahri-tre-runtime.service
sudo /usr/libexec/ahri-tre/diagnose.sh readiness

Diagnostics return JSON and classify artifact, configuration, permission, library, Deployment-identity, TLS, Secret, and readiness failures. The Web unit is installed separately but deliberately remains disabled until ticket 04 binds and qualifies its site ingress and OIDC inputs.

The v0.10.4 runtime owns /run/ahri-tre/admin.sock and /run/ahri-tre-login/login.sock, validates their ownership and modes, and recovers only safe stale sockets. It does not implement systemd socket activation, so the kit ships no competing .socket unit. The runtime service creates its private runtime directories and waits for the process-owned sockets as its readiness boundary. systemd applies restart-on-failure, a bounded start and stop interval, SIGTERM, restrictive service permissions, and explicit configuration and writable paths.

Superseded 0.2.0 Test Datastore site bundle

The first Ticket 12 pass generated a non-secret site bundle from one closed v2 input document plus public TLS material. The confirmed MinisForum profile is recorded in deployment/test-datastore-kit/site-package/site-inputs.minisforum.json. It identifies Deployment UUID f2ef37c5-7430-468a-a439-b3ba1b0527c1, Runtime origin https://runtime.svrltreapcc02.home.arpa, the reserved address 192.168.31.75, and the /data/ahri-tre storage boundary.

The following command is retained only to reproduce historical evidence; do not use its output to provision the MinisForum. It supplied a public Runtime certificate chain whose SAN contains runtime.svrltreapcc02.home.arpa and its public issuing CA chain:

cargo run --locked -p xtask -- test-datastore-kit package-site \
  --inputs deployment/test-datastore-kit/site-package/site-inputs.minisforum.json \
  --runtime-certificate-chain pki/runtime-certificate-chain.pem \
  --public-ca-chain pki/deployment-ca-chain.pem \
  --server-component-manifest \
    dist/ahri-tre-test-datastore-deployment-kit-0.1.0/server/component-versions.json \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.2.0

Do not pass --web-certificate-chain for this CLI-only profile. A Web-enabled profile must instead declare its separate authority and supply a matching public Web chain. Private keys, database passwords, OAuth secrets, encryption keys, tokens, and Runtime credentials are never packager inputs and must not be placed in the repository or generated bundle.

Generation rejects a profile with an unsupported Ubuntu release or artifact, non-private or ambiguous listener, mismatched address or client CIDR, invalid TLS authority, direct workstation database exposure, unsafe or insufficient storage, incomplete Web authority, private-key input, or partial contract. It validates the Application graph through ahri_tre_config, derives the public Client projection, validates the exact server component manifest, and publishes all 21 site/ artifacts atomically. Generated provisioning compares the installed manifest against the digest of that structured, package-selected input; it does not search JSON text or require an ambient JSON parser.

Review these generated files before copying the bundle:

• site/site-inputs.json — the exact confirmed profile and Deployment UUID;
• site/name-resolution.md — one matching hosts-file entry for the MinisForum, Windows, WSL2, and macOS;
• site/firewall-plan.json — Runtime ingress from 192.168.31.0/24, Web disabled, and non-loopback PostgreSQL denied;
• site/filesystem-plan.json — Lake and scratch beneath the /data mount;
• site/client-publication/wsl2.json and macos.json — the same Runtime origin and public CA publication; and
• site/injected-secrets.json and site/secret-reference-inventory.json — descriptors and ownership only, never values.

After the Ticket 02 server package is installed, provision the private values through the external authorities and paths named by those two Secret inventories. Apply the bundle only after the generated name-resolution instructions work on every client and after confirming both live host identifiers:

sudo ./site/provision.sh \
  --confirm-host svrltreapcc02 \
  --confirm-address 192.168.31.75

The provisioner verifies Ubuntu 26.04, x86-64, the installed v0.1.0 server package provenance, live hostname and reserved address, canonical Runtime DNS, PostgreSQL 18 TLS, the /data mounts and capacity, required Runtime Secret projections, Application validity, and Datastore-create preflight before live mutation. It refuses an existing configuration or active AHRI TRE service and has no reset, force, or adoption option. It installs configuration and public Client trust atomically, starts only the Trusted runtime, and submits only ahri-tre-test through the protected administration socket. verify-readiness.sh then checks the persisted ready binding, schema, PostgreSQL database, DuckDB/DuckLake, Lake location, and trusted scratch.

Identity admission remains a server-side PostgreSQL operation and distributes no database credential. The supplied commands are idempotent and accept only the canonical ORCID iD; the operator derives the PostgreSQL role by adding the orcid_ prefix while preserving the canonical iD’s hyphens:

sudo ./site/admit-user.sh 0000-0000-0000-0001
sudo ./site/remove-user.sh 0000-0000-0000-0001

When upgrading a site whose earlier operator replaced the iD’s hyphens with underscores, repeat admit-user.sh with the canonical iD. The corrected operator recognizes only that exact legacy mapping, renames the existing role so its grants are preserved, rewrites the identity map, and reloads it. It refuses an ambiguous or unrelated existing role instead of creating another admission.

Admission grants membership in tre_oauth_users plus schema usage, connect, read, insert, update, and sequence authority needed by the bounded gate. It does not grant superuser, database creation, role creation, DDL ownership, function-wide execution, delete, or an inherited database password. Web Secret projection and service activation are absent from the CLI-only Application configuration and the Web service remains disabled.

For regression or recovery work against the original Ticket 03 profile, use contract-v0.1.0.json together with the v1 example input and both Runtime and Web public certificate chains. Do not edit a generated v1 bundle into a MinisForum bundle.

0.3.23 MinisForum site and client bundles

minisforum-contract-v0.3.23.json advances the complete v0.3.22 composition to patch release v0.10.12. That release qualifies the integer source column in the OAuth Dataset metadata query, preserving numeric Variable order even though the wire fields remain text. The server, site, WSL2, and controlled macOS packages otherwise retain the accepted recovery and diagnostic contracts from v0.3.22.

The release assets are bound to source revision 1ae413547dae23b7fcbb659d064c704cce34cfa7. Compose the server and site with minisforum-contract-v0.3.23.json, then package both clients with minisforum-client-contract-v0.3.23.json. Exact commands, including the Linux/AMD64 controlled macOS generation path, are in deployment/test-datastore-kit/client-packaging.md.

The published archive and its adjacent checksum are release assets of v0.10.12. Two isolated Linux compositions from candidate source revision 1eee63105446396bf53c13c89e22239bda1408b4 were byte-for-byte identical at SHA-256 8c4664cd7fb48c040869c09172cf15cba2bb324c2958b0d97407c424ce20fcea.

0.3.22 MinisForum site and client bundles

minisforum-contract-v0.3.22.json diagnoses the v0.3.21 native macOS dataset.verify no-go without changing the accepted 0.3.12 lifecycle predecessor. It binds release v0.10.11, whose administration client permits bounded clean-host Datastore creation to complete and whose PostgreSQL-validator publication passed both portable adapter qualifications. Two independent Linux-container compositions from source revision 85167cb99a5780e37537de50a67204838d540f28 produced the identical archive SHA-256 8193c540887c2bb39782befc5eab742f84fa816bf6f4fb2cc664cf92073d69b1.

After checksum-verifying the v0.10.11 Linux, macOS, and validator release assets, compose the server in the persistent development container:

cargo run --locked -p xtask -- test-datastore-kit package-server \
  --contract deployment/test-datastore-kit/minisforum-contract-v0.3.22.json \
  --release-archive dist/release-v0.10.11/ahri-tre-0.10.11-x86_64-unknown-linux-gnu.tar \
  --release-checksum dist/release-v0.10.11/ahri-tre-0.10.11-x86_64-unknown-linux-gnu.tar.sha256 \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.22 \
  --source-revision 032a37c60e3fc2d3d03cc7dfcd5f680527aebc2f

Create dist/private-kit-inputs-0.3.22/site-inputs.minisforum.v3.json with mode 0600 from the current v3 template, filling only its REPLACE_... values. Package the site in the same container:

cargo run --locked -p xtask -- test-datastore-kit package-site \
  --contract deployment/test-datastore-kit/minisforum-contract-v0.3.22.json \
  --inputs dist/private-kit-inputs-0.3.22/site-inputs.minisforum.v3.json \
  --runtime-certificate-chain pki/runtime-certificate-chain.pem \
  --public-ca-chain pki/deployment-ca-chain.pem \
  --postgresql-ca-chain dist/private-kit-inputs-0.3.22/postgresql-ca-chain.pem \
  --server-component-manifest dist/ahri-tre-test-datastore-deployment-kit-0.3.22/server/component-versions.json \
  --validator-release-root dist/release-v0.10.11/validator \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.22

Hash the generated site/client.toml, site/public-ca-chain.pem, and both client-publication documents into minisforum-client-contract-v0.3.22.json before packaging either client. Exact client commands and the controlled cross-platform generation path are in deployment/test-datastore-kit/client-packaging.md.

0.3.14 MinisForum site and client bundles

minisforum-contract-v0.3.14.json advances the live 0.3.13 site from the v0.10.6 application and validator to v0.10.8. Release v0.10.8 classifies the raw libpq OAuth rejection before diagnostic sanitization, discards the raw diagnostic at the adapter boundary, and carries only the stable unadmitted-user variant into the Application and Runtime protocol layers.

The site upgrader admits only the exact healthy v0.10.6 validator, retains it as the rollback container, and loads the checksummed v0.10.8 OCI archive. The server package is newly composed from the v0.10.8 Linux release archive. The lifecycle activator accepts only the installed 0.3.13 projection plan and the new server and validator before advancing it to 0.3.14. The reboot-qualified projector, readiness waiter, and systemd ordering remain unchanged.

After downloading and checksum-verifying the published v0.10.8 Linux archive and validator release assets, compose the server in the persistent development container:

cargo run --locked -p xtask -- test-datastore-kit package-server \
  --contract deployment/test-datastore-kit/minisforum-contract-v0.3.14.json \
  --release-archive dist/release-v0.10.8/ahri-tre-0.10.8-x86_64-unknown-linux-gnu.tar \
  --release-checksum dist/release-v0.10.8/ahri-tre-0.10.8-x86_64-unknown-linux-gnu.tar.sha256 \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.14 \
  --source-revision a292eab3d21a02060b115927da3266f62ad982a0

Create dist/private-kit-inputs-0.3.14/site-inputs.minisforum.v3.json with mode 0600 from the current v3 template, filling only its REPLACE_... values. Package the site in the same container:

cargo run --locked -p xtask -- test-datastore-kit package-site \
  --contract deployment/test-datastore-kit/minisforum-contract-v0.3.14.json \
  --inputs dist/private-kit-inputs-0.3.14/site-inputs.minisforum.v3.json \
  --runtime-certificate-chain pki/runtime-certificate-chain.pem \
  --public-ca-chain pki/deployment-ca-chain.pem \
  --postgresql-ca-chain dist/private-kit-inputs-0.3.14/postgresql-ca-chain.pem \
  --server-component-manifest dist/ahri-tre-test-datastore-deployment-kit-0.3.14/server/component-versions.json \
  --validator-release-root dist/release-v0.10.8/validator \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.14

Package companion clients with minisforum-client-contract-v0.3.14.json. The WSL2 client packager runs in the development container; the macOS client packager runs on native Apple Silicon because both launch their staged binaries. Exact commands are in deployment/test-datastore-kit/client-packaging.md. Server update and live qualification steps are in the generated site/HITL.md.

0.3.13 MinisForum site and client bundles

minisforum-contract-v0.3.13.json corrects the generated lifecycle activator from the unpublished live 0.3.12 activation attempt. The 0.3.12 packager silently replaced a required server-manifest digest marker with an empty string. The corrected packager injects the exact digest and its package test requires that digest in the final script. Missing digest wiring now leaves an unresolved marker and fails package validation.

Kit 0.3.13 deliberately reuses the exact v0.10.6 server package from 0.3.12. Its site input therefore declares site kit 0.3.13 and installed server kit 0.3.12. The guarded activator accepts only the installed 0.3.11 projection plan, the exact 0.3.12 server manifest, the healthy v0.10.6 validator, and the active boot-ordered services before advancing lifecycle metadata to 0.3.13.

Start a clean artifact root by copying the already packaged, checksummed 0.3.12 server directory byte-for-byte; do not rebuild or edit it:

artifact_root=dist/ahri-tre-test-datastore-deployment-kit-0.3.13
test ! -e "$artifact_root"
mkdir -p "$artifact_root"
cp -a dist/ahri-tre-test-datastore-deployment-kit-0.3.12/server "$artifact_root/server"
test "$(sha256sum "$artifact_root/server/component-versions.json" | cut -d ' ' -f 1)" = f6686e8d3d5199a4cb280755d57df334de9e3f52d73dc52ba035c5d912a3f363

Create dist/private-kit-inputs-0.3.13/site-inputs.minisforum.v3.json with mode 0600 from the current v3 template, filling only its two REPLACE_... values. Package the site in the persistent development container:

cargo run --locked -p xtask -- test-datastore-kit package-site \
  --contract deployment/test-datastore-kit/minisforum-contract-v0.3.13.json \
  --inputs dist/private-kit-inputs-0.3.13/site-inputs.minisforum.v3.json \
  --runtime-certificate-chain pki/runtime-certificate-chain.pem \
  --public-ca-chain pki/deployment-ca-chain.pem \
  --postgresql-ca-chain dist/private-kit-inputs-0.3.13/postgresql-ca-chain.pem \
  --server-component-manifest "$artifact_root/server/component-versions.json" \
  --validator-release-root dist/release-v0.10.6/validator \
  --artifact-root "$artifact_root"

Then package companion clients with minisforum-client-contract-v0.3.13.json. Exact commands are in deployment/test-datastore-kit/client-packaging.md; update and qualification steps are in the generated site/HITL.md and each client’s WORKSTATION.md.

0.3.12 MinisForum site and client bundles

minisforum-contract-v0.3.12.json advances the live 0.3.11 site to the published v0.10.6 source revision. Its guarded upgrade replaces the exact healthy v0.10.5 validator container while retaining a rollback container, installs the v0.10.6 server package, and finally advances only the persistent projection plan. The reboot-qualified projector, readiness waiter, systemd ordering, Datastore, PostgreSQL data, Lake, configuration, and Secret authority remain unchanged.

Compose the site with minisforum-contract-v0.3.12.json, then package clients with minisforum-client-contract-v0.3.12.json. Exact commands are in deployment/test-datastore-kit/client-packaging.md; update and qualification steps are in the generated site/HITL.md and each client’s WORKSTATION.md.

After downloading and checksum-verifying the published v0.10.6 Linux archive and validator release files, run the Cargo commands in the persistent development container from /workspaces/ahri-tre-rs:

cargo run --locked -p xtask -- test-datastore-kit package-server \
  --contract deployment/test-datastore-kit/minisforum-contract-v0.3.12.json \
  --release-archive dist/release-v0.10.6/ahri-tre-0.10.6-x86_64-unknown-linux-gnu.tar \
  --release-checksum dist/release-v0.10.6/ahri-tre-0.10.6-x86_64-unknown-linux-gnu.tar.sha256 \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.12 \
  --source-revision 915dd9cb89940d20588b0c9f1a1fe11069255ca0

Create dist/private-kit-inputs-0.3.12/site-inputs.minisforum.v3.json with mode 0600 as a private copy of the current v3 template, filling only its two REPLACE_... values. The ignored dist/ path is visible in both WSL2 and the development container. Then package the site; the PostgreSQL CA input is public certificate material, not its signing key:

cargo run --locked -p xtask -- test-datastore-kit package-site \
  --contract deployment/test-datastore-kit/minisforum-contract-v0.3.12.json \
  --inputs dist/private-kit-inputs-0.3.12/site-inputs.minisforum.v3.json \
  --runtime-certificate-chain pki/runtime-certificate-chain.pem \
  --public-ca-chain pki/deployment-ca-chain.pem \
  --postgresql-ca-chain /home/kobus/ahri-tre-pki/public/postgresql-ca-chain.pem \
  --server-component-manifest dist/ahri-tre-test-datastore-deployment-kit-0.3.12/server/component-versions.json \
  --validator-release-root dist/release-v0.10.6/validator \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.12

The validator directory must contain the OCI archive and adjacent checksum, release metadata and checksum, both schemas, and qualification result from the same v0.10.6 release. Do not copy a private key or Secret into either input directory.

0.3.11 MinisForum site and client bundles

minisforum-contract-v0.3.11.json retains the 0.3.10 server behavior and the reboot-qualified service bytes. Its guarded updater accepts only the installed 0.3.10 plan and advances lifecycle metadata without restarting services or replacing binaries. The shared WSL2/macOS qualification gate reads the packaged CSV header and data-row count: derive verification checks its dimensions, while metadata verification checks the exact variable count, names, and order.

Compose the site with minisforum-contract-v0.3.11.json, then package clients with minisforum-client-contract-v0.3.11.json. Exact commands are in deployment/test-datastore-kit/client-packaging.md; update and qualification steps are in the generated site/HITL.md and each client’s WORKSTATION.md.

0.3.10 MinisForum site and client bundles

minisforum-contract-v0.3.10.json retains the 0.3.9 site behavior and the reboot-qualified 0.3.6 service bytes. Its guarded updater accepts only the installed 0.3.9 plan and advances lifecycle metadata without restarting services or replacing binaries. The companion WSL2 and macOS packages retain the separately validated logical Datastore ID and physical PostgreSQL database name from 0.3.9. Their shared qualification gate now expects the canonical CSV fixture’s three data rows and four columns. The package-contract test derives those dimensions from the fixture, preventing the assertion from drifting again.

Compose the site with minisforum-contract-v0.3.10.json, then package clients with minisforum-client-contract-v0.3.10.json. Exact commands are in deployment/test-datastore-kit/client-packaging.md; update and qualification steps are in the generated site/HITL.md and each client’s WORKSTATION.md.

0.3.8 MinisForum site and client bundles

minisforum-contract-v0.3.8.json composes the current site from the unchanged v0.10.5 server and validator release assets. Its generated operator preserves canonical hyphenated ORCID subjects, creates the bounded tre_oauth_users authority, and repairs membership and grants on repeat admission. The guarded updater accepts the exact installed 0.3.7 plan with the reboot-qualified 0.3.6 projector and waiter bytes, then updates plan metadata without restarting services or replacing binaries.

Use site-inputs.minisforum.v3.template.json to create the private input, then compose the v0.10.5 server and package the site with the 0.3.8 contract and artifact-root names. Package WSL2 and macOS clients with minisforum-client-contract-v0.3.8.json; the exact commands are in deployment/test-datastore-kit/client-packaging.md. The published 0.3.8 site archive must exist before either companion client is composed.

The archive and adjacent checksum are published with v0.10.5. Their kit source revision is 33e005dff84abff3c58f2d912ec7f0ba582902ed and the archive SHA-256 is 6c88258f84e17e047bb76eefc72becf399faba64483689fbefdf0c69d686670f.

Review the generated site/HITL.md. An existing 0.3.7 MinisForum runs the guarded metadata update, reruns site/admit-user.sh for the admitted canonical ORCID iD, and then completes both the admitted and valid-but-unadmitted client gates. A fresh installation follows server-installation.md with the 0.3.8 archive.

0.3.6 MinisForum site bundle

minisforum-contract-v0.3.6.json is the reboot-qualified composition. It pins the v0.10.5 Linux server archive and production validator OCI archive, qualification matrix, schemas, image digest, and full release source revision. The default contract.json preserves the published 0.3.0 record.

The checked-in site-inputs.minisforum.v3.template.json is deliberately not a deployable profile: replace only REPLACE_ORCID_SANDBOX_CLIENT_ID and REPLACE_POSTGRESQL_CA_SHA256 in a private working copy after completing the first two actions in the generated HITL guide. The packager rejects either placeholder and publishes no partial site.

Compose the v0.10.5 server package first. Then generate the final site with:

cargo run --locked -p xtask -- test-datastore-kit package-site \
  --contract deployment/test-datastore-kit/minisforum-contract-v0.3.6.json \
  --inputs /tmp/site-inputs.minisforum.v0.3.6.json \
  --runtime-certificate-chain pki/runtime-certificate-chain.pem \
  --public-ca-chain pki/deployment-ca-chain.pem \
  --postgresql-ca-chain /path/to/postgresql-public-ca-chain.pem \
  --server-component-manifest \
    dist/ahri-tre-test-datastore-deployment-kit-0.3.6/server/component-versions.json \
  --validator-release-root dist/release-v0.10.5/validator \
  --artifact-root dist/ahri-tre-test-datastore-deployment-kit-0.3.6

Review site/HITL.md and use its commands in order. The generated site carries the OCI bytes and their release evidence; it never rebuilds the validator and contains no Secret value or private key. Its additional site artifacts define the persistent Injected-secret source contract, boot projector, managed PostgreSQL service, Trusted runtime dependency drop-in, and guarded upgrade-secret-projector.sh. Fresh installs capture verified projections through install-secret-projector.sh; an installed 0.3.5 lifecycle uses the guarded boot-service upgrader. The projector recreates /run/secrets, including explicitly traversable shared namespaces, before PostgreSQL and the Runtime on every boot. The bounded readiness waiter tolerates transient Docker health states but does not release the Runtime until PostgreSQL is healthy.

The archive and checksum are published with v0.10.5. Their kit source revision is 2fd59cc5ea287b070c406c2e328104d92caa143f and the archive SHA-256 is 84cee3dd7dc1ef798673909c6cefc9b9801a1337986a342467f7b5afa31a5780. Live MinisForum qualification proved projection, PostgreSQL health gating, Runtime ordering, and Datastore persistence across a clean boot. Real admitted and valid-but-unadmitted ORCID Session checks remain human qualification steps, not infrastructure publication gates.

This page is for maintainers who need to build installable AHRI TRE local runtime packages. It is not required for ordinary users. End users should start with the Getting Started chapter.

The implemented maintainer interface is the workspace xtask package-release command:

cargo run -p xtask -- package-release --target x86_64-unknown-linux-gnu

The command builds or reuses release artifacts, stages an installer-ready package under dist/, audits dynamic dependencies, runs staged launch validation, writes package metadata and external-datastore examples, and archives the result. The package provides the local runtime used by the public CLI and language wrapper packages. It does not provision PostgreSQL server infrastructure or lake storage; users provide connectivity and credentials through profile and secret files.

Package Targets

Target selection is explicit. Pass one or more --target values:

cargo run -p xtask -- package-release \
  --target x86_64-unknown-linux-gnu \
  --target aarch64-unknown-linux-gnu

Missing targets are rejected by the CLI parser. Unsupported targets fail during planning before build or staging work begins. Repeated target selection lets a maintainer produce multiple packages from one invocation when the host has the required toolchain support.

Supported package targets are:

Native Windows runtime packages are out of scope for this packager slice.

CI Release Packaging

The CI release packaging path calls the same maintainer command as local packaging:

cargo run -p xtask -- package-release --target "<target-triple>"

The release-package matrix runs only for manual dispatches, GitHub release events, and version tag refs. Ordinary pull-request, branch, and scheduled CI runs still build documentation and run normal checks, but they do not produce release package candidates. This keeps untrusted or routine validation from publishing installer-ready runtime artifacts.

Each matrix entry builds one target on the runner family shown in the package target table, verifies the staged package with .github/scripts/verify-release-package-artifact.sh, writes a SHA-256 checksum for the target tarball, and uploads a workflow artifact named:

ahri-tre-<version>-<target>

The workflow artifact is the review surface for a release candidate. It contains the staged package directory, the deterministic tar archive, and the archive checksum:

dist/ahri-tre-<version>-<target>/
dist/ahri-tre-<version>-<target>.tar
dist/ahri-tre-<version>-<target>.tar.sha256

Inside the staged package, reviewers should expect the manifest, dependency-audit reports, staged validation summaries, installer metadata, generated README, generated profile and secrets examples, runtime libraries, C ABI header, CLI, daemon, and install script. The manifest records the validation commands, dependency report paths, installer contract, archive name, workspace version, package target, and package-relative runtime paths.

GitHub Release Assets

The release-package-publish job consumes the matrix workflow artifacts and attaches public assets only from a GitHub release event or a version tag ref. Pull-request, branch, scheduled, and manual-dispatch package runs do not attach assets to GitHub Releases. Manual dispatch is for producing reviewable workflow artifacts before a release, not for publication.

Before upload, .github/scripts/prepare-release-package-assets.sh verifies every supported target is present, rechecks the package artifact surface, requires the ahri-tre.package.v1 manifest schema and matching target triple, requires dependency reports and staged validation summaries, rejects known Restricted local references and secret material, and writes release checksums. Publication uses gh release upload against the existing release or tag. It does not create release notes, create GitHub releases, or infer versions from binding repositories.

Release assets use the stable names:

ahri-tre-<version>-<target>.tar
ahri-tre-<version>-<target>.tar.sha256

Binding repositories should select a runtime artifact by the AHRI TRE runtime version they support and the host target triple they are packaging for. For example, a Python, Julia, or R binding build targeting Apple Silicon macOS should download ahri-tre-<version>-aarch64-apple-darwin.tar, verify the matching .sha256, read share/ahri-tre/manifest.json, confirm schema_version is ahri-tre.package.v1, confirm the target matches the requested host triple, and then use the manifest and installer metadata to locate the C ABI library, header, CLI, and sibling daemon.

CI packaging intentionally remains a runtime-artifact publication path only. Container images, bundled PostgreSQL server infrastructure, lake provisioning, database migrations, filesystem mounting, .deb, .rpm, .pkg, Homebrew, PyPI, CRAN, Julia registry, and other installer-specific package formats stay out of scope for this guide and for the release package workflow.

Common Release Checks

Start from the release commit and run the normal repository validation before publishing release candidates:

cargo fmt --all
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

For a release candidate that changes Local deployment behaviour, use the supported deployment interface for its live checks:

./dev-env local up
./dev-env local test smoke
bash .devcontainer/scripts/check-lake.sh

Live PostgreSQL, lake, OAuth, ORCID, or REDCap checks are not default package-release steps because those services are external to installation.

The workflow contract check .github/scripts/check-release-package-workflow.sh runs in CI to make release workflow drift visible. It fails if the matrix stops invoking xtask package-release, if expected targets or runner families disappear, if workflow artifacts stop including staged packages, tarballs, and checksums, or if release asset publication is no longer gated to published GitHub Release events.

Published prereleases use the same package validation and asset publication gates. Only non-prerelease releases build and publish the stable documentation channel; a release candidate leaves the existing stable documentation in place.

Command Behaviour

By default, package-release invokes the target build, stages the package, audits dependencies, validates the staged binaries, writes package materials, and creates the archive:

cargo run -p xtask -- package-release --target x86_64-unknown-linux-gnu

Use --dry-run to review target planning without building or staging:

cargo run -p xtask -- package-release \
  --target x86_64-unknown-linux-gnu \
  --dry-run

Release packaging always builds its binaries from the clean checked-out revision. Reusing ignored Cargo target outputs is intentionally unsupported because it could attach current provenance to stale binaries.

Linux targets use cargo zigbuild --release --locked. The Apple Silicon macOS target uses native cargo build --release --locked. Every target includes the public CLI, local daemon, and stable C ABI crate used by language wrappers. The x86-64 Linux server target additionally builds the Trusted runtime and Web control plane.

The devcontainer image installs Zig and the workspace-pinned cargo-zigbuild version declared in the root Cargo.toml under workspace.metadata.ahri_tre.release_tools. If you are working outside the devcontainer, run:

bash .devcontainer/scripts/install-cross-tools.sh

That script reads the same workspace pin and installs the matching cargo-zigbuild binary before release packaging.

The script also accepts install-zig, install-rust-targets, and install-cargo-zigbuild phases. The devcontainer Dockerfile invokes these separately so a later failure does not invalidate completed cross-tool setup. Zig archives are resumed from a build cache, verified against the pinned upstream SHA-256 digest, and downloaded with visible progress.

Staged Layout

Each selected target stages an isolated package directory:

dist/ahri-tre-<version>-<target>/
  bin/
    ahri-tre
    ahri-tred
    ahri-tre-query-worker
    ahri-tre-runtime (x86-64 Linux server target)
    ahri-tre-web (x86-64 Linux server target)
  include/
    ahri_tre_ffi_c.h
  lib/
    libahri_tre_ffi_c.so or libahri_tre_ffi_c.dylib
    libduckdb.so or libduckdb.dylib
  share/ahri-tre/
    README.md
    installer.json
    manifest.json
    RELEASE_NOTES.md
    sbom.spdx.json
    licenses/
      LICENSE
      DUCKDB-LICENSE.txt
    dependency-audit/
      bin-ahri-tre.txt
      bin-ahri-tred.txt
      bin-ahri-tre-query-worker.txt
      bin-ahri-tre-runtime.txt (x86-64 Linux server target)
      bin-ahri-tre-web.txt (x86-64 Linux server target)
      lib-ffi.txt
  install.sh

The bin/ directory contains the user-facing CLI, local daemon, and private query/acquisition worker. The worker is installed beside the runtime binaries under libexec/ahri-tre, with a launcher for binding-side discovery. Its isolation is Linux-specific; packaging it on macOS does not enable unsupported execution. The x86-64 Linux server target additionally contains the Trusted runtime and Web control plane; workstation and Arm64 packages do not carry those services. The lib/ directory contains the bundled redistributable runtime libraries needed by those binaries and wrappers. DuckDB is located from the target release outputs and copied into lib/, so installed users do not need Cargo’s target directory or a development checkout.

The stable C ABI artifacts are staged as the shared library in lib/ and the public header in include/. Python, Julia, R, and future language wrapper packages can use these artifacts together with the sibling daemon path bin/ahri-tred recorded in installer metadata.

Runtime Libraries

The package bundles DuckDB and the stable AHRI TRE C ABI shared library as bundled-redistributable runtime libraries. Additional redistributable runtime libraries can be staged into lib/ by the packager when they become required. The generated installer copies lib/ into the install prefix and writes launchers for every binary present in that target package.

Installed launchers execute runtime binaries from libexec/ahri-tre and set the platform library path before dispatch:

The dependency audit allowlist treats staged libraries and expected platform libraries as acceptable. Host-specific or unexpected dynamic links are reported as warnings in command output and in dependency reports so maintainers can decide whether to bundle, install, or document them. Unresolved dependencies, for example libname.so => not found, fail packaging.

Manifest Contract

Every staged package writes share/ahri-tre/manifest.json with schema version ahri-tre.package.v1. The manifest is intended for release review and future CI automation, so paths are package-relative and must not expose Restricted local references.

At maintainer level, the manifest contains:

• schema_version, package_name, workspace_version, target, platform, git_commit, full source_revision, and build_profile.
• staged_binaries for bin/ahri-tre, bin/ahri-tred, and bin/ahri-tre-query-worker, plus the Trusted runtime and Web control plane on the x86-64 Linux server target.
• staged_libraries for the C ABI shared library and DuckDB.
• c_abi_artifacts for the wrapper-facing shared library and public header.
• required_runtime_libraries with library names, paths, and classifications.
• dependency_reports pointing at package audit files.
• validation_commands showing the staged smoke checks and library path environment used to run them.
• installer metadata for prefix-based installation, generated launchers, support files and wrapper runtime discovery.
• archive_path, written as ahri-tre-<version>-<target>.tar after the archive path is known.

Generated package material includes release notes, an SPDX SBOM, the workspace licence, and the DuckDB licence. It is checked for known secret canaries and patterns for Restricted local references before it is written. Non-fixture packaging requires a clean, committed checkout.

Installer Materials

The staged package includes human and machine installer material:

• share/ahri-tre/README.md describes package layout, prefix installation, external datastore configuration, smoke checks, and wrapper runtime paths.
• share/ahri-tre/installer.json records the ahri-tre.installer.v1 installer contract, install directories, launcher library-path strategy, and wrapper runtime locations.
• install.sh installs into AHRI_TRE_PREFIX or a prefix passed as the first argument. It copies lib/, include/, and share/ahri-tre/, stores runtime binaries under libexec/ahri-tre, and writes bin/ launchers.
• The package contains no profile dotenv file, secret overlay, token file, or credential template. Operators hand off a projected Client bootstrap through a protected deployment path; authentication artifacts remain in the Injected/Managed Secret subsystem.

The installer does not create databases, run migrations, mount filesystems, or own lake storage. Physical PostgreSQL database names, DuckLake catalog settings, configured container-visible Lake location, and DuckLake catalog credentials remain operator, create/adoption, diagnostic, or repair concerns rather than ordinary installation profile fields.

Staged Validation

Validation runs by default from the staged package, not from the build tree. The command sets the package lib/ directory on the platform library path and runs:

dist/ahri-tre-<version>-<target>/bin/ahri-tre version
dist/ahri-tre-<version>-<target>/bin/ahri-tre doctor --format json
dist/ahri-tre-<version>-<target>/bin/ahri-tre schema list --format json
dist/ahri-tre-<version>-<target>/bin/ahri-tred --help
dist/ahri-tre-<version>-x86_64-unknown-linux-gnu/bin/ahri-tre-runtime --help
dist/ahri-tre-<version>-x86_64-unknown-linux-gnu/bin/ahri-tre-web --help

The final two checks apply only to the x86-64 Linux server target.

Any validation command failure fails packaging for that target. When repeated targets are requested, the packager reports each target outcome and preserves successful packages for targets that completed before another target failed.

Archive Outputs

After dependency audit and staged validation pass, the packager writes a tar archive beside the staged package:

dist/
  ahri-tre-<version>-x86_64-unknown-linux-gnu/
  ahri-tre-<version>-x86_64-unknown-linux-gnu.tar

The archive contains the staged package under a top-level ahri-tre-<version>-<target>/ directory and preserves executable bits for commands and installer scripts. Multiple requested targets produce isolated staged directories, manifests, dependency reports, and archives.

Out Of Scope

This packager slice deliberately does not produce Dockerfiles, Compose bundles, container images, registry pushes, GitHub releases, Homebrew formulae, Debian packages, RPMs, macOS installer packages, or native Windows packages. It also does not bundle PostgreSQL server infrastructure, provision a lake filesystem, or ship operator-specific credentials.