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}
69
70/// One concrete publish destination in a sealed plan.
71///
72/// Mirrors the contract's [`crate::contract::schema::Target`] but is a distinct
73/// wire type: the plan may *resolve* a `null` package name from repo facts, so
74/// its `package` is the concrete name the human approves, not necessarily the
75/// contract's (which the executor would otherwise infer at cut time).
76#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
77pub struct PlanTarget {
78 /// The ecosystem this target publishes for.
79 pub ecosystem: Ecosystem,
80 /// The package/crate name — resolved from the detected manifest facts when
81 /// the contract left it `null`; still `null` if no manifest named it (the
82 /// executor would infer it at cut time).
83 pub package: Option<String>,
84 /// The publish destination.
85 pub registry: Registry,
86 /// The release tool pinned for this target.
87 pub adapter: Adapter,
88}
89
90/// One phase of the coordinator's irreversibility-ordered pipeline (ADR-0002
91/// §2). The sequence is invariant across every plan; [`PlanPhase::sequence`]
92/// yields it in order.
93#[derive(Debug, Clone, Copy, PartialEq, Eq)]
94pub enum PlanPhase {
95 /// Dry-run every target (re-runnable, no side effects).
96 DryRunAll,
97 /// Build every target (re-runnable).
98 BuildAll,
99 /// Publish every target (per-target irreversible).
100 PublishAll,
101 /// Create + push the one shared git tag and GitHub Release (coordinator-only).
102 Tag,
103}
104
105impl PlanPhase {
106 /// The wire string for this phase (kebab-case; the single source the
107 /// `Serialize` impl also emits, so text and JSON never drift).
108 #[must_use]
109 pub fn as_str(self) -> &'static str {
110 match self {
111 Self::DryRunAll => "dry-run-all",
112 Self::BuildAll => "build-all",
113 Self::PublishAll => "publish-all",
114 Self::Tag => "tag",
115 }
116 }
117
118 /// The invariant phase order a cut drives, dry-run-all → tag.
119 pub const SEQUENCE: [PlanPhase; 4] =
120 [Self::DryRunAll, Self::BuildAll, Self::PublishAll, Self::Tag];
121
122 /// The invariant phase order a cut drives, dry-run-all → tag (borrowed view
123 /// of [`Self::SEQUENCE`]; no allocation).
124 #[must_use]
125 pub fn sequence() -> &'static [PlanPhase] {
126 &Self::SEQUENCE
127 }
128}
129
130impl serde::Serialize for PlanPhase {
131 fn serialize<S: serde::Serializer>(&self, ser: S) -> Result<S::Ok, S::Error> {
132 ser.serialize_str(self.as_str())
133 }
134}