146 lines
6.8 KiB
Markdown
146 lines
6.8 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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.
|