This commit is contained in:
eric
201
docs/distribution-contract.json
Normal file
201
docs/distribution-contract.json
Normal file
@@ -0,0 +1,201 @@
|
||||
{
|
||||
"schema_version": "distribution-contract-v1",
|
||||
"contract_version": "1.0.0",
|
||||
"artifact": {
|
||||
"name": "codex-controller-loop",
|
||||
"entrypoints": [
|
||||
"codex-controller-loop"
|
||||
],
|
||||
"distribution_index": {
|
||||
"canonical": "dist/index.json",
|
||||
"legacy": [
|
||||
{
|
||||
"path": "dist/{contract_version}/index.json",
|
||||
"status": "deprecated",
|
||||
"deprecation_sunset": "2026-07-01T00:00:00Z",
|
||||
"migration_deadline": "2026-07-01T00:00:00Z",
|
||||
"notes": "Temporary compatibility path while downstream scripts migrate to dist/index.json."
|
||||
}
|
||||
],
|
||||
"resolution_precedence": [
|
||||
"dist/index.json",
|
||||
"dist/{contract_version}/index.json"
|
||||
]
|
||||
},
|
||||
"versioning": {
|
||||
"model": "semver",
|
||||
"release_channels": [
|
||||
"stable"
|
||||
],
|
||||
"pre_release": "supported",
|
||||
"pinning_guidance": "Pin by exact tuple: version, target, profile, git_rev, toolchain, dist_revision"
|
||||
},
|
||||
"naming": {
|
||||
"namespace": "dist",
|
||||
"canonical_pattern": "codex-controller-loop-v{version}-{target}-{profile}-{rust}-{gitsha}-{dist_revision}.{ext}",
|
||||
"immutable_fields": [
|
||||
"version",
|
||||
"target",
|
||||
"profile",
|
||||
"rust",
|
||||
"gitsha",
|
||||
"dist_revision"
|
||||
]
|
||||
},
|
||||
"release_artifacts": {
|
||||
"formats": [
|
||||
"tar.gz"
|
||||
],
|
||||
"required_manifests": [
|
||||
"checksums.json",
|
||||
"manifest.json",
|
||||
"provenance.json"
|
||||
],
|
||||
"index_path_template": "dist/index.json",
|
||||
"legacy_index_path_template": "dist/{contract_version}/index.json",
|
||||
"artifact_directory_template": "dist/{contract_version}/{version}/{target}/{profile}/{toolchain}/{gitsha}/{dist_revision}",
|
||||
"orchestrator": {
|
||||
"name": "scripts/release-orchestrator.py",
|
||||
"config": "scripts/release-orchestrator.config.json"
|
||||
}
|
||||
}
|
||||
},
|
||||
"compatibility_matrix": [
|
||||
{
|
||||
"platform_family": "linux",
|
||||
"os": "Linux",
|
||||
"arch": [
|
||||
"x86_64",
|
||||
"aarch64"
|
||||
],
|
||||
"compatibility": "recommended",
|
||||
"runtime_expectations": [
|
||||
"posix-like terminal with ANSI support",
|
||||
"UTF-8 locale",
|
||||
"interactive TTY for full features"
|
||||
]
|
||||
},
|
||||
{
|
||||
"platform_family": "darwin",
|
||||
"os": "Darwin",
|
||||
"arch": [
|
||||
"x86_64",
|
||||
"aarch64"
|
||||
],
|
||||
"compatibility": "recommended",
|
||||
"runtime_expectations": [
|
||||
"POSIX terminal",
|
||||
"UTF-8 locale",
|
||||
"interactive TTY for full features"
|
||||
]
|
||||
},
|
||||
{
|
||||
"platform_family": "windows",
|
||||
"os": "Windows",
|
||||
"arch": [
|
||||
"x86_64"
|
||||
],
|
||||
"compatibility": "planned",
|
||||
"runtime_expectations": [
|
||||
"UTF-8 locale",
|
||||
"terminal support in Windows console"
|
||||
]
|
||||
}
|
||||
],
|
||||
"assumptions": {
|
||||
"rust": {
|
||||
"edition": "2021",
|
||||
"toolchain": "release-time explicit rustc version",
|
||||
"minimum_guaranteed": null,
|
||||
"minimum_for_release": "recorded per artifact in manifest"
|
||||
},
|
||||
"terminal": "ANSI-capable terminal and TTY are required for interactive TUI mode",
|
||||
"non_tty_mode": "operable only for restricted command-and-control paths"
|
||||
},
|
||||
"reproducibility_metadata": {
|
||||
"required": true,
|
||||
"fields": [
|
||||
"version",
|
||||
"target",
|
||||
"profile",
|
||||
"build_time_inputs",
|
||||
"git_rev",
|
||||
"toolchain",
|
||||
"checksums"
|
||||
]
|
||||
},
|
||||
"provenance_metadata": {
|
||||
"schema_version": "distribution-provenance-v1",
|
||||
"required_fields": [
|
||||
"artifact",
|
||||
"build_inputs",
|
||||
"build_artifact",
|
||||
"generated_at"
|
||||
]
|
||||
},
|
||||
"checksum_policy": {
|
||||
"algorithm": "sha256",
|
||||
"required": true,
|
||||
"file": "checksums.json",
|
||||
"consumer_check_required": true
|
||||
},
|
||||
"maintenance_governance": {
|
||||
"release_ownership": {
|
||||
"primary_owner": "Repository maintainers and release steward on duty",
|
||||
"ownership_handoff_required": [
|
||||
"Update docs/distribution.md, docs/distribution-changelog.md, and docs/distribution-contract.json in lockstep for any compatibility-relevant changes",
|
||||
"Attach a passing scripts/release-gate.py run log to the release PR or merge checklist",
|
||||
"Verify the release steward handoff note in the PR description before publish"
|
||||
],
|
||||
"handoff_minimum_gap": "at least one full release cycle"
|
||||
},
|
||||
"deprecation_governance": {
|
||||
"required_notice_days": 60,
|
||||
"retention_for_retirement": "one release cycle",
|
||||
"retirement_announcement_channels": [
|
||||
"docs/distribution.md",
|
||||
"docs/distribution-changelog.md"
|
||||
]
|
||||
},
|
||||
"retention_minimum_generations": 6
|
||||
},
|
||||
"compatibility_policy": {
|
||||
"contract_versioning": "distribution-contract-v1",
|
||||
"breaking_change_requires_bump": true,
|
||||
"deprecation_notice_cycles": 1,
|
||||
"assumption_changes_requires_changelog": true
|
||||
},
|
||||
"deprecation_policy": {
|
||||
"legacy_index_path": {
|
||||
"supported_until": "2026-07-01T00:00:00Z",
|
||||
"sunset_reason": "Canonical index migration to dist/index.json.",
|
||||
"required_action": "All consumers must resolve artifacts from the canonical index path and remove legacy hard-coding before sunset.",
|
||||
"notice_channels": [
|
||||
"docs/distribution-changelog.md",
|
||||
"docs/distribution.md"
|
||||
]
|
||||
},
|
||||
"migration_window": {
|
||||
"minimum_notice_days": 60,
|
||||
"default_alias_removal_after": "2026-07-01T00:00:00Z"
|
||||
}
|
||||
},
|
||||
"retention_policy": {
|
||||
"kept_release_generations": 6,
|
||||
"retention_rationale": "Keep at least six release generations to support rollback and reproducible debugging.",
|
||||
"migration_required_on_removal": true,
|
||||
"migration_minimum_notice_window": "one release cycle"
|
||||
},
|
||||
"migration_steps": {
|
||||
"breaking_change_notice": [
|
||||
"Add an entry to docs/distribution-changelog.md with impact summary and effective release",
|
||||
"Provide compatibility matrix and assumption deltas in docs/distribution.md",
|
||||
"Publish manifest/metadata updates alongside artifacts before deprecation cutoff"
|
||||
],
|
||||
"rollback_path": "Consumers can repin immutable artifact tuple in their integration config."
|
||||
},
|
||||
"changelog": {
|
||||
"file": "docs/distribution-changelog.md",
|
||||
"required_on_contract_changes": true
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user