🏗️ [architecture] spec(distribution): extend release declarations with distribution targets, package coordinates, and publisher bindings #63

Outcome

Extend the existing egohygiene.repository-release/v1 release declaration with a tool-neutral, machine-readable distribution-target contract that tells agents, Relay, Pace, Observatory, and downstream consumers exactly where a released component is intended to be built, published, installed, and verified.

This issue formalizes the declaration layer for the Hygiene universal distribution policy. It does not implement publishing workflows or own credentials.

Context

Existing release work already distinguishes repository tags, component versions, release profiles, and external distribution channels:

• spec(releases): define the organization-wide semantic release and changelog contract #61
• policy(distribution): define the universal tool distribution and native-installability profile hygiene#29

The missing piece is a stable schema for describing those channels and their relationship to build targets and package identities.

Distribution declaration

Define versioned schema/types capable of expressing, per component:

Component identity

• component/package ID;
• release profile;
• authoritative version source;
• source revision/tag relationship.

Build targets

• canonical target ID;
• OS;
• architecture;
• ABI/libc/runtime distinctions where material;
• artifact kind;
• support state/tier;
• required build/test environment.

Distribution targets

• stable channel/provider ID;
• channel class, such as GitHub Release, language registry, OS package manager, OCI registry, direct installer, or other approved adapter;
• package coordinate/name/formula/cask/bucket/repository identifier;
• public account/organization/namespace identifier when applicable;
• source artifact mapping;
• version mapping rules;
• supported build targets;
• install/upgrade/uninstall/verify command metadata or command-template references where appropriate;
• publisher adapter ID/version;
• publication state semantics.

Publisher authority

Model references, never credentials:

• publishing owner;
• GitHub environment or approval boundary;
• symbolic secret/OIDC binding names;
• account/namespace recovery documentation reference;
• whether publication is manual-review, dispatch, or release-event authorized.

Do not permit plaintext tokens, passwords, signing keys, or recovery secrets in the declaration.

Evidence projection

Define the stable output shape needed to report:

• expected target/channel;
• built artifact and digest;
• published package version;
• publication timestamp;
• install-test result;
• evidence source/freshness;
• supported, experimental, unavailable, blocked, stale, not-published, or not-applicable state.

Catalog vocabulary

Provide canonical IDs/examples for common target/channel classes without hard-coding policy that every repository must use them.

Examples should cover at least:

• GitHub Releases;
• crates.io;
• PyPI;
• npm;
• Homebrew;
• Nix;
• Debian/APT;
• RPM-family package distribution;
• Alpine/APK;
• AUR;
• Snap;
• Scoop;
• Chocolatey;
• WinGet;
• OCI/container registries.

Provider-specific details should live in adapter extensions where necessary rather than destabilizing the core schema.

Examples

Publish complete examples for at least:

1. a Rust CLI distributed as binaries + crates.io + native package managers;
2. a Python CLI distributed as wheel/sdist + PyPI + selected native wrappers;
3. a CLI that is only directly released and containerized;
4. an internal/not-published tool;
5. a partially supported matrix with explicit unavailable targets.

Agent guidance

Add an Aether skill/template that can:

• inspect a repository and propose a distribution declaration;
• avoid inventing accounts/namespaces;
• preserve existing package identities;
• distinguish package creation from publication;
• identify missing publisher prerequisites as blockers;
• generate/update the declaration without touching credentials.

Acceptance criteria

• The release declaration can express build targets and distribution targets independently.
• Package coordinates and public account/namespace identifiers are machine-readable.
• Publisher authority is modeled through symbolic environment/secret/OIDC references only.
• A target can be supported, experimental, unavailable, blocked, stale, not published, or not applicable without ambiguity.
• Install/upgrade/uninstall/verify metadata can be represented without hard-coding one CLI shape.
• The schema supports multiple components and multiple channels per component.
• Rust, Python, container-only, internal-only, and partial-matrix fixtures validate.
• Agent guidance refuses to fabricate package-manager accounts or credentials.
• The contract composes egohygiene.repository-release/v1 rather than creating a second release protocol.

Dependencies

• policy(distribution): define the universal tool distribution and native-installability profile hygiene#29
• completed semantic-release foundation: spec(releases): define the organization-wide semantic release and changelog contract #61

September 28 — compatibility with the evolving release model

Program: egohygiene/.github#20. Coordinate this existing distribution schema with #95 and the applicability policy in Hygiene #29. The original requirement to compose repository-release/v1 means preserving the existing release protocol and its migration path; if the accepted design chooses a successor schema, reference that version explicitly rather than freezing an incompatible v1-only extension or inventing a second protocol.

The distribution contract must distinguish build targets, adapter requests, publication/install receipts, native package revision mappings, and symbolic publisher authority. Its first Relay consumers are egohygiene/relay#124 and egohygiene/relay#125. Do not require all delivery adapters to exist before landing the schema and fixtures.