Distribution Contract for `codex-controller-loop`

v1 Contract

This document defines the first stable, versioned distribution contract for the Rust controller binary. It is the canonical compatibility and consumption reference for external projects.

1) Contract version and release identity

Contract version: distribution-contract@1.0
Release artifact identity is immutable for a given tuple:
- artifact_version (semver)
- git_rev (full SHA, immutable reference)
- toolchain and build_profile
- target
- dist_revision (incrementing revision when rebuilds occur for the same release tuple)
Consumers must pin by immutable tuple, never by moving tags.

2) Canonical artifact entrypoint

Primary entrypoint: codex-controller-loop CLI.
Canonical binary names:
- codex-controller-loop (single binary)
Canonical distribution entrypoint index: dist/index.json.
Deprecated compatibility entrypoint (removed after 2026-07-01): dist/{distribution_contract_version}/index.json.

3) Canonical dist layout and naming

dist/ is the only published artifact namespace.
Directory template (contract version stable):
- dist/{distribution_contract_version}/{artifact_version}/{target}/{profile}/{toolchain}/{gitsha}/{dist_revision}/
- Example: dist/1.0.0/0.1.0/x86_64-unknown-linux-gnu/release/1.84.0/ab12cd34/r1/
Canonical artifact filename:
- codex-controller-loop-v{version}-{target}-{profile}-{rust}-{gitsha}-{dist_revision}.{ext}
  - version = semver release (e.g. 1.4.2)
  - target = Rust target triple
  - profile = release or debug
  - rust = rustc version string used in build
  - gitsha = short git commit hash of source revision
  - dist_revision = r1, r2, ... for immutable re-build iterations
  - ext = container format used by release pipeline (e.g. tar.gz)
Canonical generator entrypoint:
- scripts/release-orchestrator.py (single orchestrator)
- Controlled by scripts/release-orchestrator.config.json
- Index manifest output: dist/index.json
Deterministic provenance snapshot in generated index:
- Each index artifact row is keyed by version + target + profile + toolchain + gitsha + dist_revision
- artifact_file, manifest_file, checksums_file, artifact_sha256, and source_date_epoch are emitted

8) Consumer integration examples

Use the canonical index first, then fail fast if no rows match the requested immutable tuple. Optional legacy fallback is accepted only during migration.

VERSION=0.1.0
TARGET=x86_64-unknown-linux-gnu
PROFILE=release
TOOLCHAIN=1.84.0
GITSHA=ab12cd34
DIST_REVISION=r1

INDEX=dist/index.json
if [ ! -f "$INDEX" ]; then
  INDEX=dist/1.0.0/index.json
  echo "warning: using deprecated index path, remove by 2026-07-01"
fi

ARTIFACTS=$(jq -r --arg version "$VERSION" --arg target "$TARGET" --arg profile "$PROFILE" \
  --arg toolchain "$TOOLCHAIN" --arg git "$GITSHA" --arg dist "$DIST_REVISION" \
  '.releases[] | select(.version==$version) | .targets[] | select(.target==$target) | .profiles[] | select(.profile==$profile) | .artifacts[] | select(.toolchain|startswith($toolchain)) | select(.git_rev|startswith($git)) | select(.dist_revision==$dist) | .artifact_file' "$INDEX")

COUNT=$(printf "%s\n" "$ARTIFACTS" | awk 'NF {count += 1} END {print count + 0}')
if [ "$COUNT" -ne 1 ]; then
  echo "expected exactly one artifact for immutable tuple" >&2
  exit 1
fi

ARTIFACT_FILE=$(printf "%s" "$ARTIFACTS")
echo "resolved artifact: $ARTIFACT_FILE"

PACKAGE_DIR="${ARTIFACT_FILE%/*}/package"
CHECKSUMS="$PACKAGE_DIR/checksums.json"

python - <<PY
import hashlib, json, pathlib
artifact = pathlib.Path("${ARTIFACT_FILE}")
checksums = json.loads(pathlib.Path("${CHECKSUMS}").read_text())
actual = hashlib.sha256(artifact.read_bytes()).hexdigest()
if actual != checksums["artifact_sha256"]:
    raise SystemExit("artifact checksum mismatch")
print(f"artifact sha256: {actual}")
PY

4) Release compatibility matrix

Platform	OS	Arch	Binary compatibility	Runtime assumptions	Notes
Linux	Linux	`x86_64` / `aarch64`	Recommended	UTF-8 locale and terminal (TTY)	Required for TUI rendering
macOS	Darwin	`aarch64` / `x86_64`	Recommended	UTF-8 locale and terminal (TTY)	Build validation expected
Windows	Windows	`x86_64`	Planned / not guaranteed	UTF-8 locale and terminal (TTY)	Future support candidate

Rust compatibility: Release pipelines are required to document exact rust toolchain versions per artifact.
Source compatibility is guaranteed only for the same distribution_contract_version and artifact_version tuple.

5) Checksums and integrity

Every release artifact must include checksums.json, manifest.json, and provenance.json.
All checksums use SHA-256.
Consumers treat a release as valid only if:
1. Artifact checksum matches manifest entry.
2. Manifest has reproducibility metadata matching expected tuple (version, target, profile, toolchain, git rev).

6) Retention and migration

The canonical contract file is immutable once published for a release version.
Backward compatibility matrix changes require a migration note in the contract changelog.
Deprecated/removed platform support is announced via the changelog and removed only after a deprecation cycle.
Contract index migration note: dist/{distribution_contract_version}/index.json is a temporary compatibility alias and is retired on 2026-07-01.

7) Changelog and compatibility governance

Compatibility assumption changes require a changelog entry in docs/distribution-changelog.md.
Contract fields are first-class API: any consumer-facing contract change must update:
- docs/distribution.md
- docs/distribution-contract.json
- docs/distribution-changelog.md

8) Source-of-truth documents

Machine-readable contract file: docs/distribution-contract.json

The JSON contract is the machine-readable interface; this ADR should be treated as the human-readable interpretation.

9) Operational governance and release hygiene

Release ownership handoff is explicit and bounded:
- The active release steward must own the distribution contract updates for the PR.
- Ownership is transferred only after docs/distribution.md, docs/distribution-changelog.md, and docs/distribution-contract.json are updated together.
- Handoff requires at least one release cycle of overlap so downstream consumers have a recovery window.
Deprecation workflow is fixed:
- Legacy index path support remains for the documented minimum notice period.
- Any compatibility assumption change requires a changelog entry and a migration step before sunset.
Minimum retention window:
- Keep at least six release generations in the contract retention policy.
- Do not remove deprecated aliases before the contract's documented notice date and retention cleanup policy are both met.

6.8 KiB Raw Blame History

Distribution Contract for codex-controller-loop