ossctl_core/protocol/plan.rs
1//! Public wire DTO for the sealed, content-addressed release plan
2//! (`ossctl release plan` — ADR-0002 §3).
3//!
4//! A [`ReleasePlan`] is the read-only pre-image a human approves: the ordered
5//! concrete target set a cut would publish, the invariant phase sequence the
6//! coordinator will drive, the git `HEAD` it was sealed against, the chosen
7//! release version, and the content-addressed [`ReleasePlan::plan_id`]. `release
8//! cut --plan <plan_id>` re-derives the plan from *current* repo state and
9//! refuses (`plan_stale`) if the id no longer matches — so a commit, a manifest
10//! rename, a schema bump, or a different chosen version between approval and
11//! execution aborts rather than silently publishing something else.
12//!
13//! Consumers read this document under the CLI's canonical `data` envelope:
14//! `{schema_version, data: <this shape>, warnings}` — the same envelope every
15//! `ossctl --json` command shares (`crate::SCHEMA_VERSION` versions that wire
16//! envelope). Like `facts` and `audit`, the plan is *derived*, never authored,
17//! so it has no document version of its own; the envelope's `schema_version` is
18//! the wire version consumers gate on. [`ReleasePlan::contract_schema_version`]
19//! is a *content* field (the contract-document version the plan was sealed
20//! against, part of the content address), not the wire-envelope version.
21//!
22//! The plan **reuses** [`Ecosystem`], [`Registry`], and [`Adapter`] from the
23//! canonical contract model rather than restating their wire strings: the plan,
24//! the contract, and the release adapters must agree on `"rust"` /
25//! `"crates.io"` / `"cargo-publish"` down to the byte, and sharing the one enum
26//! makes that agreement structural instead of coincidental.
27
28use serde::Serialize;
29
30use crate::contract::schema::{Adapter, Ecosystem, Registry};
31
32/// A sealed, content-addressed release plan — the artifact `release plan`
33/// emits and a human approves.
34///
35/// Every field except [`Self::plan_id`] is an *input* to the content address
36/// (`plan_id` is the SHA-256 digest **over** those inputs — plus the full
37/// normalized contract and a domain/seal-format tag — so it is derived, never
38/// authored, and is deliberately excluded from the hashed pre-image: a hash
39/// cannot cover itself). See [`crate::release::plan`] for the exact pre-image.
40#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
41pub struct ReleasePlan {
42 /// The content-addressed plan id: a lowercase 64-character SHA-256 hex
43 /// digest over the sealed pre-image (see [`crate::release::plan`] for
44 /// exactly what is hashed). Stable — identical inputs always yield this same
45 /// id; any change to a hashed input yields a different one. This is the
46 /// token passed back as `release cut --plan <plan_id>`.
47 pub plan_id: String,
48 /// The `OSS-RELEASE.md` contract-document schema version this plan was
49 /// sealed against (part of the content address). A schema bump between
50 /// approval and execution is drift.
51 pub contract_schema_version: u32,
52 /// The git `HEAD` commit sha the plan was sealed against. A new commit
53 /// between approval and execution is drift.
54 pub head_sha: String,
55 /// The chosen release version (the human's bump per design §3.4), supplied
56 /// as a validated input to `release plan`. Sealed verbatim; changing it
57 /// requires a new plan.
58 pub version: String,
59 /// The ordered, concrete publish targets a cut would execute — one per
60 /// configured `ecosystem → package → registry`, with `null` package names
61 /// resolved from detected repo facts where possible.
62 pub targets: Vec<PlanTarget>,
63 /// The invariant coordinator phase sequence a cut drives (ADR-0002 §2):
64 /// dry-run-all → build-all → publish-all → tag. Constant for every plan and
65 /// therefore *not* part of the content address (an invariant cannot drift);
66 /// carried here so the sealed artifact is self-describing for the approver.
67 pub phases: Vec<PlanPhase>,
68 /// The Homebrew tap repo (`owner/repo`) the cut's generated formula is
69 /// pushed to, or `null` when the contract configured none. Copied verbatim
70 /// from the (already content-addressed) normalized contract's
71 /// `distribution.homebrew_tap` — carried on the plan, like [`Self::phases`],
72 /// only so the coordinator can hand it to the Homebrew adapter's
73 /// first-formula bootstrap without re-reading the contract. Being a copy of a
74 /// value the pre-image already hashes, it changes no `plan_id`.
75 pub homebrew_tap: Option<String>,
76 /// The SPDX license expression the cut's generated Homebrew formula records,
77 /// copied from the normalized contract's `license`. Carried for the same
78 /// reason (and with the same content-address neutrality) as
79 /// [`Self::homebrew_tap`].
80 pub license: Option<String>,
81}
82
83/// One concrete publish destination in a sealed plan.
84///
85/// Mirrors the contract's [`crate::contract::schema::Target`] but is a distinct
86/// wire type: the plan may *resolve* a `null` package name from repo facts, so
87/// its `package` is the concrete name the human approves, not necessarily the
88/// contract's (which the executor would otherwise infer at cut time).
89#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
90pub struct PlanTarget {
91 /// The ecosystem this target publishes for.
92 pub ecosystem: Ecosystem,
93 /// The package/crate name — resolved from the detected manifest facts when
94 /// the contract left it `null`; still `null` if no manifest named it (the
95 /// executor would infer it at cut time).
96 pub package: Option<String>,
97 /// The publish destination.
98 pub registry: Registry,
99 /// The release tool pinned for this target.
100 pub adapter: Adapter,
101}
102
103/// One phase of the coordinator's irreversibility-ordered pipeline (ADR-0002
104/// §2). The sequence is invariant across every plan; [`PlanPhase::sequence`]
105/// yields it in order.
106#[derive(Debug, Clone, Copy, PartialEq, Eq)]
107pub enum PlanPhase {
108 /// Dry-run every target (re-runnable, no side effects).
109 DryRunAll,
110 /// Build every target (re-runnable).
111 BuildAll,
112 /// Publish every target (per-target irreversible).
113 PublishAll,
114 /// Create + push the one shared git tag and GitHub Release (coordinator-only).
115 Tag,
116}
117
118impl PlanPhase {
119 /// The wire string for this phase (kebab-case; the single source the
120 /// `Serialize` impl also emits, so text and JSON never drift).
121 #[must_use]
122 pub fn as_str(self) -> &'static str {
123 match self {
124 Self::DryRunAll => "dry-run-all",
125 Self::BuildAll => "build-all",
126 Self::PublishAll => "publish-all",
127 Self::Tag => "tag",
128 }
129 }
130
131 /// The invariant phase order a cut drives, dry-run-all → tag.
132 pub const SEQUENCE: [PlanPhase; 4] =
133 [Self::DryRunAll, Self::BuildAll, Self::PublishAll, Self::Tag];
134
135 /// The invariant phase order a cut drives, dry-run-all → tag (borrowed view
136 /// of [`Self::SEQUENCE`]; no allocation).
137 #[must_use]
138 pub fn sequence() -> &'static [PlanPhase] {
139 &Self::SEQUENCE
140 }
141}
142
143impl serde::Serialize for PlanPhase {
144 fn serialize<S: serde::Serializer>(&self, ser: S) -> Result<S::Ok, S::Error> {
145 ser.serialize_str(self.as_str())
146 }
147}