Activity-Relay Directory 1.3.0

Activity-Relay Directory 1.3.0

The 1.3 release adds reviewed relay profiles, bounded CSV exchange, lifecycle Protocol v2/v3 support, participating-site telemetry, improved public presentation, and stronger operator workflows while preserving the separation between descriptive metadata and Directory-observed operational state.

Highlights

Relay profiles

ARD now stores source-scoped descriptive relay profile assertions with private append-only history.

Effective values are resolved independently per field using:

override > relay > csv

Profiles may describe registration policy, relay type, languages, countries, regions, topics, operator contact information, participation URLs, availability, and notes.

Descriptive profile data does not determine heartbeat state, reachability, moderation, enrollment, pruning, tier placement, or public eligibility.

CSV import and export

ARD 1.3 adds bounded profile-aware CSV import/export with spreadsheet formula-injection protection and deterministic list escaping.

CSV imports preview field-level changes before confirmation.

An exact relay actor already retained as an active lifecycle or discovery identity may now receive CSV metadata updates even when that relay is currently unreachable. This makes it possible to maintain descriptive information for unavailable or Graveyard relays already legitimately present in the Directory.

Unknown candidates still require the normal actor-validation path or explicit --add-dead-relays retention.

CSV profile updates never fabricate heartbeat or reachability evidence.

For 1.3.0, participation_mode values are case-sensitive and should use exact lowercase:

open
restricted
closed

or be left empty.

Lifecycle Protocol v2 and v3

Protocol v2 adds authenticated relay-profile synchronization while keeping heartbeat and unregister identity-only.

Protocol v3 extends the lifecycle contract with optional bounded participating_instance_count telemetry.

Protocol v1 remains supported for compatibility.

Schema 12 stores Protocol-v3 participating-instance telemetry separately from the earlier receiving-instance telemetry. Public Sites prefers the v3 value and falls back to the older value during rolling upgrades.

Telemetry is descriptive only and cannot affect Directory tiering or eligibility.

Registration is current liveness evidence

Every successful authenticated registration now counts as current relay liveness.

Create, unchanged/profile-sync, and restore registration outcomes update both lifecycle last-seen state and the retained heartbeat/liveness timestamp. Explicit heartbeat does the same.

CSV, discovery, moderation, presentation, and independent reachability changes do not fabricate authenticated liveness.

Production RC4 validation with Activity-Relay confirmed that a normal relay restart generated a fresh authenticated heartbeat and returned the relay to Tier 1 without requiring a configuration change.

Richer public Directory

/v2/relays schema 5 publishes the reviewed effective profile together with bounded telemetry and independent operational evidence.

The human Directory can display and filter registration status as:

• Open
• Restricted
• Closed
• Not reported

The existing four operational tiers remain unchanged:

1. Tier 1 — Heartbeat + Online
2. Tier 2 — Online, no current heartbeat
3. Tier 3 — Offline / Unreachable
4. Tier 4 — Graveyard

Profiles and self-reported telemetry cannot move a relay between tiers.

Operator presentation

ARD now supports optional presentation settings including:

• Directory title;
• HTTPS banner;
• operator contact information; and
• support links or plain-text support values.

The package-managed configuration reference is:

/etc/activity-relay-directory/config.yml.example

The live configuration remains operator-owned:

/etc/activity-relay-directory/config.yml

and is not created or overwritten by the package.

Documentation and release packaging

The project README has been reduced to a concise overview and operator entry point. Detailed installation, administration, configuration, discovery, profile, storage, moderation, retention, and development material now lives in focused documents.

Canonical release artifacts are transported inside the deterministic activity-relay-directory-canonical.tar carrier, preserving expected Unix modes and deterministic release timestamps across Forgejo artifact transport.

Compatibility and upgrade

• Application version: 1.3.0
• Debian package version: 1.3.0-1
• SQLite schema: 12
• Supported lifecycle protocols: 1, 2, and 3
• Previous stable release: 1.2.0

Existing schema-9 through schema-11 databases upgrade in place through the reviewed migrations to schema 12.

The frozen /v1/relays compatibility API and Lifecycle Protocol v1 remain supported.

In-place SQLite downgrade is not supported. Restore the backup associated with the older release before starting an older binary.

Unavailable and Graveyard relays remain retained for recovery by default. Reversible soft pruning remains separate from destructive hard retention, and hard retention remains disabled by default.

Release lineage

• Stable release: v1.3.0
• Accepted release-candidate baseline: v1.3.0-rc4
• Debian package version: 1.3.0-1

v1.2.0

Activity-Relay Directory 1.2.0

Activity-Relay Directory 1.2 expands relay discovery, long-term availability tracking, and the public-facing Directory while preserving the authenticated V1 lifecycle protocol and the frozen /v1/relays compatibility API.

Highlights

• More resilient relay discovery and bulk imports
• Retention and automatic retry of unavailable relay candidates
• ActivityStreams Group relay actor support
• Four public operational relay tiers
• 30-day transition to the Graveyard tier
• Aggregate online, offline, and pending-verification counts on the public-facing Directory page
• Local tier-scoped exports and public plain-text relay downloads
• Automatic recovery of previously unavailable relays
• Debian upgrade handling that reloads systemd definitions without automatically restarting an active Directory

Relay discovery

Discovery imports now accept:

• bare hostnames;
• non-default HTTPS ports;
• base URLs;
• /actor URLs; and
• /inbox URLs.

A relay must still pass canonical actor validation before becoming verified public Directory state.

ActivityStreams Group actors are now accepted in addition to the previously supported relay actor forms.

Imports distinguish between:

• newly discovered relays;
• relays already known through discovery or lifecycle state;
• duplicate lines in the same input; and
• unavailable or incompatible candidates.

Existing relay identities are not duplicated merely because they appear in another import.

Retained unavailable candidates

discovery import --add-dead-relays can retain unavailable or incompatible candidates privately for future retry.

Retry timing is:

• 6 hours
• 12 hours
• 24 hours
• 3 days
• weekly thereafter

A retained candidate remains private until a later actor check successfully validates and promotes it. Candidate identities, failure details, source labels, and other discovery provenance are not published.

Public relay tiers

Verified relays are grouped into four operational tiers:

1. Tier 1 — Heartbeat + Online
   The relay has a current Directory heartbeat and is currently reachable.

2. Tier 2 — Online, no current heartbeat
   The relay is currently reachable but does not have a current Directory heartbeat.

3. Tier 3 — Offline / Unreachable
   The relay is currently unreachable but has been seen online within the last 30 days.

4. Tier 4 — Graveyard
   The relay has not been seen online for at least 30 days.

Relays are ordered alphabetically within each tier. Heartbeat frequency, check recency, popularity, and traffic do not affect placement.

Graveyard relays are not deleted. They continue periodic recovery checks and automatically return to Tier 1 or Tier 2 if they recover.

The public-facing Directory page also summarizes the number of verified relays known, currently online, currently offline, and additional candidates pending verification.

Exports and downloads

Operators can export relay lists locally:

activity-relay-directory admin export --scope active --format hosts
activity-relay-directory admin export --scope unavailable --format hosts
activity-relay-directory admin export --scope all --format actors

When public listing is enabled, host lists are also available at:

/downloads/active.txt
/downloads/unavailable.txt
/downloads/all.txt

Host exports preserve non-default HTTPS ports and can be fed back into a later discovery import.

Private provenance and unresolved candidate identities are never included in exports or public downloads.

Compatibility

Activity-Relay Directory 1.2 uses:

Database schema:        9
/v1/status schema:      3
/v1/relays schema:      1
/v2/relays schema:      3
v2 cursor format:       2
Lifecycle protocol:     1
Minimum Go version:     1.26.0
Debian package version: 1.2.0-1

/v1/relays remains frozen for 1.0 compatibility.

Migrations 0001 through 0008 remain byte-identical to the v1.1.0 release. 0009_discovery_candidates.sql is the only new migration in 1.2.

Existing schema-8 databases upgrade in place to schema 9.

In-place database downgrade is not supported. Back up the SQLite database before upgrading and restore the matching older backup if returning to an older binary.

Debian upgrades

Package upgrades preserve the current service enablement state and do not stop or restart an operator-activated Directory.

Package configuration automatically reloads systemd unit definitions. After reviewing the upgraded package and configuration, restart the service manually when you are ready to load the new binary:

sudo systemctl restart activity-relay-directory

Normal package removal preserves the Directory database and service account. Explicit package purge remains the destructive boundary.

Safe defaults

Fresh installations remain deliberately inactive until configured.

The following remain disabled by default:

• authenticated lifecycle endpoints;
• public listing;
• background reachability maintenance;
• automatic soft pruning;
• positive hard-retention policy; and
• administrator email notifications.

The public Directory remains read-only. Moderation records, operator reasons, discovery provenance, signatures, nonces, private probe errors, client addresses, database paths, and other administrative information remain private.

Release acceptance

The accepted RC2 source passed the 1.2 source acceptance suite covering:

• schema and migration identity;
• discovery compatibility;
• retained-candidate retry and promotion;
• tiering and 30-day Graveyard behavior;
• exports and public downloads; and
• V1/V2 public API compatibility.

Release identity

Tag:        v1.2.0
Commit:     978a90d98ed4c96928a3970594acb5cecb9cf896
Debian:     1.2.0-1
Schema:     9

Activity-Relay Directory 1.1.0

Activity-Relay Directory 1.1.0

Status: stable release.

Version information

• Git tag: v1.1.0
• Application version: 1.1.0
• Debian package version: 1.1.0-1
• Accepted release candidate: v1.1.0-rc2
• Previous stable release: v1.0.0

What's new in 1.1

Activity-Relay Directory 1.1 adds operator-controlled relay discovery,
independent reachability checks, a richer V2 public API, and an improved
human-facing directory.

The accepted 1.1.0-rc2 behavior is being promoted to stable without runtime
behavior changes. Stable 1.1.0 will be built and published as its own release;
the published RC2 files and container image remain unchanged.

Relay discovery and reachability

Operators can add relays for discovery without treating them as registered
lifecycle participants. Directory can separately check whether a relay actor is
reachable and can record non-mutating inbox diagnostics.

Heartbeat and reachability remain separate. A relay can therefore have an old
or missing lifecycle heartbeat while still being reachable, or have a recent
heartbeat while a later reachability check fails.

Discovered-only relays must have a recent successful actor check to remain
eligible for the public directory. Administrative suspension takes precedence
over both registered and discovered relay eligibility.

Human-facing pages

The human-facing directory uses compact, responsive relay rows with clearer
heartbeat and reachability information.

Larger directories provide Previous and Next navigation so visitors can move
through the listing in either direction. The human-facing pages use the same
public relay information as the V2 public API while keeping detailed technical
diagnostics out of the main listing.

V1 Protocol and compatibility

The authenticated V1 Protocol remains unchanged. Existing Activity-Relay
clients continue to use the same registration, heartbeat, and unregister
behavior.

The /v1/relays public API also remains compatible with Activity-Relay
Directory 1.0. Its wire format and established behavior are unchanged.

Compatibility versions remain:

• database schema: 8
• /v1/status schema: 3
• /v1/relays schema: 1
• lifecycle protocol: version 1
• Go module floor: 1.26.0

V2 public API

GET /v2/relays provides the richer 1.1 public relay listing. It is disabled by
default along with the human-facing directory.

The V2 public API can show heartbeat state, actor reachability, validated inbox
information, and positive RFC 9421 evidence while keeping those observations
separate. Discovered-only relays are not given artificial registration or
heartbeat timestamps.

This is version 2 of the public relay API; it does not introduce a V2 lifecycle
protocol.

Discovery provenance, operator notes and reasons, private probe errors, audit
events, database identifiers, request signatures, client addresses, resolver
details, and internal participation flags are not published.

Package upgrades and removal

Normal package upgrades and package removal preserve the Directory database and
the dedicated activity-relay-directory service account. This allows the
package to be upgraded or reinstalled without discarding retained Directory
state.

Explicit package purge is the destructive boundary: it removes the package's
state directory and dedicated service account.

/etc/activity-relay-directory/config.yml remains operator-owned. It is not a
package conffile and is not deleted by the custom package-maintenance scripts.

Upgrade notes

Schema 8 adds the 1.1 discovery and reachability data. Existing installations
upgrade in place.

Before upgrading an existing installation, take and verify a standalone SQLite
backup. In-place database downgrade is not supported; to return to an older
release, restore the database backup made for that older version.

Safe defaults

A fresh installation remains inactive until an operator enables the features
they want:

• lifecycle routes are disabled;
• enrollment is closed;
• the public directory is disabled;
• background reachability checks are disabled;
• automatic soft pruning is disabled;
• inactive-record retention is 0 (indefinite); and
• administrator email is disabled.

Enabling the public directory does not automatically enable lifecycle
registration, reachability checks, pruning, retention, or any public
state-changing route.

Activity-Relay Directory 1.1.0-rc2

Activity-Relay Directory 1.1.0-rc2

Status: release-candidate source draft. Canonical artifacts, tag, publication,
deployment, and feature activation remain separate gates.

1.1.0-rc1 was prepared as a source candidate but was not tagged or published.
This RC2 draft supersedes that unpublished candidate after the human-directory
and Debian lifecycle corrections merged to master.

Version identity

• Git tag: v1.1.0-rc2
• Application version: 1.1.0-rc2
• Debian package version: 1.1.0~rc2-1
• Stable baseline: v1.0.0
• RC2 pre-freeze baseline merge: b181f599d0d48720dcaacd385f68a48b46c4de80
• Prior 1.1.0-rc1 tag/publication: none

Candidate scope

Activity-Relay Directory 1.1 continues to add operator-controlled discovery and
independent relay reachability without changing the authenticated version 1
lifecycle or reinterpreting heartbeat recency. Schema version 8 records
discovery state, actor/inbox observations, and positive RFC 9421 evidence while
preserving private provenance and audit boundaries.

RC2 carries the RC1 1.1 feature set and adds the following post-RC1 corrections:

• scale the human directory into compact responsive relay rows with clearer
  heartbeat and reachability presentation while intentionally leaving detailed
  inbox/RFC 9421 evidence in the JSON projection;
• add signed previous/next navigation to the human directory using the existing
  bounded v2 cursor format, while keeping /v2/relays itself forward-only;
• make Debian package removal non-destructive for retained SQLite state and the
  dedicated service account, with explicit package purge as the destructive
  boundary;
• keep operator-owned /etc/activity-relay-directory/config.yml outside the
  package conffile set and outside maintainer-script deletion; and
• validate built maintainer scripts and package ownership boundaries under a
  Debian Trixie / debhelper >= 13.25 release-build contract.

These changes do not introduce a new database migration, lifecycle protocol
version, or public JSON schema version beyond the RC1 1.1 candidate.

Compatibility and schemas

• Database schema: 8.
• /v1/status schema: 3.
• /v1/relays schema: 1, frozen for 1.0 compatibility.
• /v2/relays schema: 2.
• Lifecycle protocol: version 1.
• Go module floor: 1.26.0; release toolchain: 1.26.5.

Migrations 0001 through 0007 remain byte-identical to the v1.0.0 release;
0008_discovery_reachability.sql remains the only 1.1 migration. Existing
retained lifecycle/audit state upgrades in place to schema 8. In-place database
downgrade is unsupported: take and verify a standalone SQLite backup before
upgrade, and restore the matching older backup when downgrading.

Human directory and public contract

/v1/relays retains the 1.0 wire and semantic contract. The v2 projection keeps
lifecycle heartbeat, actor reachability, inbox diagnostics, and RFC 9421
evidence independent. Discovered-only relays never receive fabricated
registration or heartbeat timestamps. Administrative suspension overrides both
registration and discovery eligibility.

The human / view remains a presentation over the same bounded v2 projection.
It now supports signed reverse traversal with before in addition to normal
forward cursor navigation. Reverse traversal does not extend the original
five-minute walk lifetime. /v2/relays remains forward-only and rejects the
human-only reverse parameter.

Discovery source/provenance, operator and reason values, private probe errors,
audit events, database identifiers, request signatures, client addresses,
resolver details, and internal participation flags remain non-public.

Debian lifecycle contract

Ordinary package removal and upgrade preserve
/var/lib/activity-relay-directory and the dedicated
activity-relay-directory system account so the package can be reinstalled or
upgraded without discarding retained directory state.

Package purge is explicitly destructive: it removes the state directory and the
dedicated system user/group. The optional
/etc/activity-relay-directory/config.yml is operator-owned, is not a package
conffile, and is not deleted by the custom maintainer scripts. The package-created
parent directory is removed only when otherwise empty. Purge under DPKG_ROOT
is rejected rather than attempting destructive account/state cleanup against an
alternate root.

The release builder inspects the generated .deb, requires generated postinst,
prerm, and postrm scripts, checks their shell syntax, proves the custom
destructive operations occur only behind the purge guard, verifies the exact
package conffile set, and confirms operator config.yml is absent from the
payload.

Default safety posture

Fresh installations remain deliberately inert until configured. In particular:

• lifecycle routes remain disabled by default and enrollment remains closed;
• public directory presentation remains disabled by default;
• background reachability remains disabled by default;
• automatic soft pruning remains disabled by default;
• inactive-record retention remains 0 (indefinite); and
• administrator email remains disabled.

Enabling the public listing does not activate lifecycle, reachability, pruning,
retention, or any public mutation route.

Source and release-build gates

The accepted 1.1 source gate continues to cover exact 1.0.0/schema-7 upgrade
identity, registered and discovered-only participation paths, candidate URL
convergence, fail-closed resolver/network behavior, inbox method rejection, a
real RFC 9421 signed lifecycle request persisted through SQLite, independent
registration/discovery transitions, suspension, pruning races, and schema-8
inactive retention.

The RC2 pre-freeze master baseline additionally passed Forgejo container,
Debian package, and Go test workflows after the human-directory and Debian
lifecycle corrections were merged. Canonical package construction now runs on
the shared forgejo-workstation execution profile, requires Debian Trixie,
installs debhelper from Trixie backports, and fails closed below version
13.25.

This source-preparation commit must still pass the normal branch/PR checks before
it becomes the exact reviewed source identity for a canonical RC2 dispatch.

Candidate artifact and operator gates

Forgejo is authoritative. After this candidate-preparation source state is
reviewed and merged, the manual exact-commit workflow must build one new
canonical 1.1.0-rc2 artifact set. The Debian package and Docker archive from
that exact set must then be independently install-tested using separate SQLite
state and bind ports before tagging or publication.

Do not relabel RC1 or 1.0.0 artifacts. Tagging, release publication, deployment,
activation of the default-off 1.1 surfaces, production verification/soak, and
stable 1.1 promotion remain separate explicit approvals.

Activity-Relay Directory 1.0.0

Activity-Relay Directory 1.0.0

Status: first stable release.

Version identity

• Git tag: v1.0.0
• Application version: 1.0.0
• Debian package version: 1.0.0-1
• Accepted release-candidate baseline: 0.1.0-rc4
• There is no final v0.1.0 tag.

Stable scope

Activity-Relay Directory 1.0.0 promotes the accepted RC4 runtime contract to
stable. The stable-preparation source delta is limited to release/version
metadata, documentation, and generalizing the exact-commit canonical artifact
workflow so it can build stable semantic versions. It does not change the Go
runtime behavior accepted during the RC soak.

The stable service provides the version 1 authenticated register, heartbeat,
and unregister lifecycle; bounded health projection; default-off public JSON
and human listings; local enrollment/moderation/pruning/retention/storage
administration; durable replay protection; SSRF-resistant actor/key
resolution; and SQLite-backed audited state.

Compatibility and schemas

• Database schema: 7.
• /v1/status schema: 3.
• /v1/relays schema: 1.
• Lifecycle protocol: version 1.
• Go module floor: 1.26.0; release toolchain: 1.26.5.

The stable release preserves the RC migration contract. In-place database
downgrade is not supported. Before upgrading an existing deployment, take and
verify a standalone SQLite backup. To downgrade, restore the database backup
that matches the older binary rather than starting an older binary against a
newer schema.

Accepted live integration

The first stable release was accepted against the Activity-Relay 3.0 release
line using directory.argentwolf.org as a real Directory service. Acceptance
included:

• successful schema-3 status consumption by Activity-Relay;
• registration and public projection of both relay.argentwolf.org and
  relay2.argentwolf.org;
• natural scheduler-driven heartbeat refresh from both relays after the daily
  interval;
• healthy public projection throughout the soak;
• authenticated removal of relay2 with durable local suppression;
• confirmed absence of relay2 from /v1/relays while disabled; and
• re-enable plus automatic scheduler registration returning relay2 to the
  healthy public listing.

The Compose lifecycle exercise also established an operator requirement for
Activity-Relay deployments that bind config.yml as a single file: an atomic
host-file replacement is not visible to an already-running container using the
old bind-mounted inode. Activity-Relay operator documentation carries the safe
container sequence; this is not a Directory protocol or persistence defect.

Default safety posture

Fresh installations remain deliberately inert until configured:

• lifecycle routes are disabled;
• enrollment is closed;
• the public listing and human directory are disabled;
• automatic soft pruning is disabled;
• inactive-record retention is 0 (indefinite); and
• administrator email is disabled.

Package installation remains separate from service activation. The Debian
package does not enable or start the service automatically, and package removal
or purge does not delete SQLite state.

Release artifacts

Forgejo is authoritative. The canonical exact-commit workflow builds one
checksummed artifact set containing the Debian package, standalone binary,
CycloneDX SBOM, build metadata, and Docker-loadable linux/amd64 image archive.
The exact accepted bytes are promoted to the release surface; do not rebuild or
rename RC4 artifacts as 1.0.0.

Activity Relay Directory 0.1.0-rc1

Activity Relay Directory 0.1.0-rc1

This is the first release candidate toward Activity Relay Directory 1.0.0.

Canonical release artifacts were built once from the reviewed signed source
commit b3b8c62c33feab7e361fe754a56dd9c2f13dd8dd (tree 3b52940bf63962eefd819df4fde9144799c155cc) and promoted without rebuild.

The exact Debian package and Docker archive were independently install-tested
on a clean Ubuntu 26.04 LTS amd64 VM. Fresh Debian installation remained
disabled/inactive until explicit operator activation; both Debian and container
paths passed health/readiness/status checks and the default-off lifecycle and
public-listing contract using separate writable SQLite state.

Included release files:

• activity-relay-directory_0.1.0-rc1-1_amd64.deb
• activity-relay-directory_0.1.0-rc1_amd64.cdx.json
• activity-relay-directory_0.1.0-rc1_linux_amd64
• BUILD-METADATA.txt
• activity-relay-directory_0.1.0-rc1_linux_amd64.docker.tar
• SHA256SUMS

Verify the five checksummed canonical assets with:

sha256sum -c SHA256SUMS

Application version: 0.1.0-rc1
Debian version: 0.1.0~rc1-1

This is a prerelease candidate, not the 1.0.0 stable release.