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    /// A hidden embargo blocks descendants, even when a descendant's own tier
44    /// is visible. Internal and TeamScoped restrict only their own state.
45    pub fn is_embargo(&self) -> bool {
46        matches!(self, Self::Private { .. } | Self::Restricted { .. })
47    }
48
49    /// Stable wire/storage token for the tier discriminant. The labelled
50    /// variants collapse to their kind name here; the label travels in a
51    /// separate field. Shared by the discussion RPC vocabulary and the
52    /// state-visibility signing payload, so it must stay stable.
53    pub fn as_str(&self) -> &'static str {
54        match self {
55            Self::Public => "public",
56            Self::Internal => "internal",
57            Self::TeamScoped { .. } => "team_scoped",
58            Self::Restricted { .. } => "restricted",
59            Self::Private { .. } => "private",
60        }
61    }
62
63    /// Restrictiveness ordering used by the `visibility promote` monotonicity
64    /// check (heddle#317). **Lower rank = LESS restrictive** (the tier reaches a
65    /// broader audience):
66    ///
67    /// | tier         | rank | audience reach                              |
68    /// |--------------|------|---------------------------------------------|
69    /// | `Public`     | 0    | every audience (least restrictive)          |
70    /// | `Internal`   | 1    | the workspace-internal set (+ every team)   |
71    /// | `TeamScoped` | 2    | one named team                              |
72    /// | `Restricted` | 3    | one named scope label                        |
73    /// | `Private`    | 4    | only the matching scope holder (most restrictive, even `Internal` is excluded) |
74    ///
75    /// This is the *defined* total order for "less restrictive", consistent with
76    /// spike #266 §5.2 (`Internal` content is one of the least-restrictive
77    /// values; `Private` the most — it is the embargo tier that withholds from
78    /// every audience including `Internal`). The labelled variants compare by
79    /// rank only — a lateral move between two teams / two scope labels is the
80    /// **same** rank, hence not *strictly* less restrictive, and must go through
81    /// `set` rather than `promote`.
82    pub fn restrictiveness_rank(&self) -> u8 {
83        match self {
84            Self::Public => 0,
85            Self::Internal => 1,
86            Self::TeamScoped { .. } => 2,
87            Self::Restricted { .. } => 3,
88            Self::Private { .. } => 4,
89        }
90    }
91
92    /// `true` iff `self` is **strictly** less restrictive than `other` — i.e. a
93    /// `promote` from `other` to `self` is a valid opening transition. A
94    /// narrowing (`self` more restrictive) or lateral (equal rank, including a
95    /// different team/scope label at the same rank) change returns `false` and
96    /// must be expressed with `set`. See [`restrictiveness_rank`](Self::restrictiveness_rank).
97    pub fn is_strictly_less_restrictive_than(&self, other: &Self) -> bool {
98        self.restrictiveness_rank() < other.restrictiveness_rank()
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    fn team(id: &str) -> VisibilityTier {
107        VisibilityTier::TeamScoped { team_id: id.into() }
108    }
109    fn restricted(label: &str) -> VisibilityTier {
110        VisibilityTier::Restricted {
111            scope_label: label.into(),
112        }
113    }
114
115    #[test]
116    fn restrictiveness_rank_orders_public_least_restricted_most() {
117        assert!(
118            VisibilityTier::Public.restrictiveness_rank()
119                < VisibilityTier::Internal.restrictiveness_rank()
120        );
121        assert!(VisibilityTier::Internal.restrictiveness_rank() < team("a").restrictiveness_rank());
122        assert!(team("a").restrictiveness_rank() < restricted("legal").restrictiveness_rank());
123    }
124
125    #[test]
126    fn strictly_less_restrictive_only_when_rank_drops() {
127        // Opening transitions (lower rank) are strictly less restrictive.
128        assert!(
129            VisibilityTier::Public.is_strictly_less_restrictive_than(&VisibilityTier::Internal)
130        );
131        assert!(VisibilityTier::Internal.is_strictly_less_restrictive_than(&restricted("legal")));
132        assert!(VisibilityTier::Internal.is_strictly_less_restrictive_than(&team("infra")));
133
134        // Narrowing transitions (higher rank) are NOT.
135        assert!(!restricted("legal").is_strictly_less_restrictive_than(&VisibilityTier::Internal));
136        assert!(
137            !VisibilityTier::Internal.is_strictly_less_restrictive_than(&VisibilityTier::Public)
138        );
139
140        // Lateral (same rank) is NOT strictly less restrictive — even across
141        // different team/scope labels. A re-scope must go through `set`.
142        assert!(!team("a").is_strictly_less_restrictive_than(&team("b")));
143        assert!(!restricted("legal").is_strictly_less_restrictive_than(&restricted("security")));
144        assert!(
145            !VisibilityTier::Internal.is_strictly_less_restrictive_than(&VisibilityTier::Internal)
146        );
147    }
148}
heddle_object_model/object/visibility_tier.rs

heddle_object_model/object/
visibility_tier.rs
