# Architecture Policy

**Base Policy Version:** 1.3

**Last Updated**: 2026-10-06

**Upstream Source:** [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)

## Purpose And Ownership

ReleaseKit is an opinionated Go library and release executable for common
publication, builds, version injection, and delivery. This policy owns
responsibility boundaries, dependency direction, and adopted constraints for
development. The [product roadmap](../roadmap/releasekit.md) owns proposed
capabilities, implementation status, and sequencing.

The [internal documentation](../internal/overview.md) owns concrete package
inventory and implementation mechanics. Canonical public contracts own exact
behavior; ADRs record decision rationale.

## Adopted Constraints And Implemented Structure

Architectural constraints govern current and future development and reflect
deliberately selected requirements and decisions. Current architecture describes
implemented structure. Roadmaps record proposals, implementation status, and
sequencing; ADRs record significant decisions and rationale. Internal
implementation choices evolve within these constraints.

## Success Criteria

Evaluate ReleaseKit development and adoption against both criteria:

1. Applications delete substantial release infrastructure while retaining clear
   ownership of product-specific checks and compatibility decisions.
2. Consumers adopt one coherent set of deliberately selected release conventions.

Consumer implementations supply evidence of needs. ReleaseKit selects a common
model and enough flexibility to express genuine product requirements. API
designs should demonstrate reduced consumer infrastructure and consistent
conventions through representative consumers.

## Responsibility Boundaries

ReleaseKit owns the mechanics of selected publication, version injection,
cross-build, and delivery conventions. Applications supply product identity,
their main package, selected build targets, application-specific candidate
checks, and delivery declarations. Applications own their compatibility
decisions and adaptation of version output to the supported runtime accessor.

The release executable invokes the supported orchestration facade and owns
argument parsing, output, and exit codes. Library operations return meaningful
errors and outcomes, including partial progress and uncertain publication state.
Consumers map those values to their own user interfaces.

ReleaseKit builds and tests independently of consuming repositories. Production
dependencies use supported public contracts available independently of consumer
checkouts. Committed module and workspace configuration supports independent
builds; temporary local development configuration remains local.

## Public Facades And Dependency Direction

[ADR 0001](../adr/0001-public-facade.md) records the accepted decision for the root
`releasekit` orchestration facade and separate `buildinfo` runtime facade.
Both belong to one Go module and share its versioning and compatibility
obligations. Each facade exposes a cohesive consumer contract.

Public named types belong to their facade. Exported signatures, fields,
callbacks, and method sets use facade-owned types and deliberately selected
public dependencies. Handles retain private implementation state, with explicit
forwarding and conversions preserving supported identity, ownership, error
semantics, and callback lifetime.

Implementation packages live under Go's `internal/` boundary. Dependencies run
from facades into internal implementation; internal production packages depend
on internal contracts. Git operations, Go toolchain execution, Gitea integration,
and orchestration bookkeeping belong behind that boundary. Additional public
packages and extension interfaces require a deliberate decision grounded in a
durable consumer need.

Go declarations and GoDoc own exact API contracts. Compiled-export checks,
dependency checks, and external-package behavioral tests protect the selected
facade boundaries.

## Runtime Version Boundary

The `buildinfo` public API exposes runtime information justified by
consumer needs. Its implementation uses the standard library and a small
internal dependency graph independent of release orchestration. Applications
read their embedded version through its supported accessor.

The builder and runtime implementation own the linker symbol and injection
mechanism together. Dependency checks protect the runtime boundary;
build-and-run integration tests verify that the builder injects the selected
version and the public accessor reports it correctly.

## External Effects

Keep Git, filesystem, Go toolchain, and Gitea effects behind proportionate
internal boundaries and perform them through explicit operations. Select
interfaces and package layout for actual responsibilities and testability.
The library owns reusable outcomes and failure handling; the executable owns
presentation and process exits.

Source publication and asynchronous delivery have distinct outcomes. The
[release policy](release.md) governs releases of ReleaseKit itself. Go
declarations and GoDoc define supported consumer API contracts;
[consumer guides](../consumers/) explain their use, and
[integration guides](../integrations/) define external formats and protocols.
The product roadmap records planned capabilities and implementation status.

## Trust Boundaries And Threat Scope

Base defenses and guarantees on selected requirements. Candidate validation,
remote-state changes, transport failures, and partial delivery receive explicit
handling. Additional threat scenarios require a deliberate scope decision under
the [agent policy](agents.md).

Public API, [configuration](../config.md), and integration contracts own
credential supply and observable handling. Internal documents own the mechanisms.
Tests use local collaborators and controlled failures as specified by the
[testing policy](testing.md).