heddle_object_model/object/visibility_tier.rs
1// SPDX-License-Identifier: Apache-2.0
2//! Shared audience-tier vocabulary.
3//!
4//! [`VisibilityTier`] is the single content-side visibility vocabulary used
5//! across annotations, discussions, and per-state commit visibility. The
6//! *reader's* tier (who is asking) is [`AudienceTier`]; this enum is the
7//! *content's* tier (who the content is for). The who-sees-what mapping
8//! between the two lives in [`visible`](super::visible), beside both
9//! vocabularies.
10//!
11//! `Public` is the default — it matches the pre-unification behavior where
12//! every annotation was effectively public, so legacy data on disk decodes
13//! unchanged.
14
15use serde::{Deserialize, Serialize};
16
17/// Content-side visibility tier. Shared by annotations, discussions, and
18/// states so the per-commit visibility tiers and annotation/discussion
19/// visibility draw from one vocabulary rather than parallel enums.
20#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
21pub enum VisibilityTier {
22 #[default]
23 Public,
24 Internal,
25 TeamScoped {
26 team_id: String,
27 },
28 Restricted {
29 scope_label: String,
30 },
31 /// The strictest tier: withheld from **every** audience — including the
32 /// otherwise all-seeing `Internal` audience — except the one holder of
33 /// the matching `Restricted(scope_label)`. Used for embargoed per-state
34 /// commit visibility, where even internal callers must not see the
35 /// content. The who-sees-what arm lives in `visible`, placed above the
36 /// `(_, Internal) => true` arm so the embargo holds.
37 Private {
38 scope_label: String,
39 },
40}
41
42impl VisibilityTier {
43 /// Stable wire/storage token for the tier discriminant. The labelled
44 /// variants collapse to their kind name here; the label travels in a
45 /// separate field. Shared by the discussion RPC vocabulary and the
46 /// state-visibility signing payload, so it must stay stable.
47 pub fn as_str(&self) -> &'static str {
48 match self {
49 Self::Public => "public",
50 Self::Internal => "internal",
51 Self::TeamScoped { .. } => "team_scoped",
52 Self::Restricted { .. } => "restricted",
53 Self::Private { .. } => "private",
54 }
55 }
56
57 /// Restrictiveness ordering used by the `visibility promote` monotonicity
58 /// check (heddle#317). **Lower rank = LESS restrictive** (the tier reaches a
59 /// broader audience):
60 ///
61 /// | tier | rank | audience reach |
62 /// |--------------|------|---------------------------------------------|
63 /// | `Public` | 0 | every audience (least restrictive) |
64 /// | `Internal` | 1 | the workspace-internal set (+ every team) |
65 /// | `TeamScoped` | 2 | one named team |
66 /// | `Restricted` | 3 | one named scope label |
67 /// | `Private` | 4 | only the matching scope holder (most restrictive, even `Internal` is excluded) |
68 ///
69 /// This is the *defined* total order for "less restrictive", consistent with
70 /// spike #266 §5.2 (`Internal` content is one of the least-restrictive
71 /// values; `Private` the most — it is the embargo tier that withholds from
72 /// every audience including `Internal`). The labelled variants compare by
73 /// rank only — a lateral move between two teams / two scope labels is the
74 /// **same** rank, hence not *strictly* less restrictive, and must go through
75 /// `set` rather than `promote`.
76 pub fn restrictiveness_rank(&self) -> u8 {
77 match self {
78 Self::Public => 0,
79 Self::Internal => 1,
80 Self::TeamScoped { .. } => 2,
81 Self::Restricted { .. } => 3,
82 Self::Private { .. } => 4,
83 }
84 }
85
86 /// `true` iff `self` is **strictly** less restrictive than `other` — i.e. a
87 /// `promote` from `other` to `self` is a valid opening transition. A
88 /// narrowing (`self` more restrictive) or lateral (equal rank, including a
89 /// different team/scope label at the same rank) change returns `false` and
90 /// must be expressed with `set`. See [`restrictiveness_rank`](Self::restrictiveness_rank).
91 pub fn is_strictly_less_restrictive_than(&self, other: &Self) -> bool {
92 self.restrictiveness_rank() < other.restrictiveness_rank()
93 }
94}
95
96#[cfg(test)]
97mod tests {
98 use super::*;
99
100 fn team(id: &str) -> VisibilityTier {
101 VisibilityTier::TeamScoped { team_id: id.into() }
102 }
103 fn restricted(label: &str) -> VisibilityTier {
104 VisibilityTier::Restricted {
105 scope_label: label.into(),
106 }
107 }
108
109 #[test]
110 fn restrictiveness_rank_orders_public_least_restricted_most() {
111 assert!(
112 VisibilityTier::Public.restrictiveness_rank()
113 < VisibilityTier::Internal.restrictiveness_rank()
114 );
115 assert!(VisibilityTier::Internal.restrictiveness_rank() < team("a").restrictiveness_rank());
116 assert!(team("a").restrictiveness_rank() < restricted("legal").restrictiveness_rank());
117 }
118
119 #[test]
120 fn strictly_less_restrictive_only_when_rank_drops() {
121 // Opening transitions (lower rank) are strictly less restrictive.
122 assert!(
123 VisibilityTier::Public.is_strictly_less_restrictive_than(&VisibilityTier::Internal)
124 );
125 assert!(VisibilityTier::Internal.is_strictly_less_restrictive_than(&restricted("legal")));
126 assert!(VisibilityTier::Internal.is_strictly_less_restrictive_than(&team("infra")));
127
128 // Narrowing transitions (higher rank) are NOT.
129 assert!(!restricted("legal").is_strictly_less_restrictive_than(&VisibilityTier::Internal));
130 assert!(
131 !VisibilityTier::Internal.is_strictly_less_restrictive_than(&VisibilityTier::Public)
132 );
133
134 // Lateral (same rank) is NOT strictly less restrictive — even across
135 // different team/scope labels. A re-scope must go through `set`.
136 assert!(!team("a").is_strictly_less_restrictive_than(&team("b")));
137 assert!(!restricted("legal").is_strictly_less_restrictive_than(&restricted("security")));
138 assert!(
139 !VisibilityTier::Internal.is_strictly_less_restrictive_than(&VisibilityTier::Internal)
140 );
141 }
142}