Skip to main content

subc_protocol/
scope.rs

1//! Scope records: owned identity records the daemon holds for sessions.
2//!
3//! A scope is identified by `(owner, ref)`. The owner is the module whose own
4//! registered connection synced it, never a value in the request, and the
5//! `ref` is an opaque string unique within that owner only. The design is
6//! `docs/designs/daemon-scopes.md`; the wire shapes here are the owner-facing
7//! half of it (`scope.sync`, `scope.apply`, `scope.describe`).
8//!
9//! Every record type refuses unknown fields. A field this daemon does not know
10//! may be one that narrows authority in a later version (a carrier's target
11//! list, say), and silently dropping it would widen what the scope grants, so
12//! an owner sending one is told its body is malformed instead.
13
14use serde::{Deserialize, Serialize};
15
16use crate::Principal;
17
18// Scope principals are authority-bearing input: an unrecognized constraint must
19// not silently widen a grant. Principal elsewhere is a forward-compatible caller
20// fact, so keep its general decoder lenient and enforce this only on scope input.
21#[derive(Deserialize)]
22#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
23enum ScopePrincipal {
24    Reserved { module_id: String },
25    Direct {},
26    Unverified {},
27}
28
29impl From<ScopePrincipal> for Principal {
30    fn from(value: ScopePrincipal) -> Self {
31        match value {
32            ScopePrincipal::Reserved { module_id } => Self::Reserved { module_id },
33            ScopePrincipal::Direct {} => Self::Direct,
34            ScopePrincipal::Unverified {} => Self::Unverified,
35        }
36    }
37}
38
39fn deserialize_scope_principal<'de, D: serde::Deserializer<'de>>(
40    deserializer: D,
41) -> Result<Principal, D::Error> {
42    ScopePrincipal::deserialize(deserializer).map(Into::into)
43}
44
45fn deserialize_scope_principals<'de, D: serde::Deserializer<'de>>(
46    deserializer: D,
47) -> Result<Vec<Principal>, D::Error> {
48    Vec::<ScopePrincipal>::deserialize(deserializer)
49        .map(|principals| principals.into_iter().map(Into::into).collect())
50}
51
52/// A scope bind-proof hash is the lowercase hexadecimal SHA-256 digest.
53pub fn validate_bind_proof_sha256(hash: &str) -> Result<(), &'static str> {
54    if hash.len() == 64
55        && hash
56            .bytes()
57            .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
58    {
59        Ok(())
60    } else {
61        Err("bind_proof_sha256 must be exactly 64 lowercase hexadecimal characters")
62    }
63}
64
65fn deserialize_bind_proof_sha256<'de, D: serde::Deserializer<'de>>(
66    deserializer: D,
67) -> Result<Option<String>, D::Error> {
68    let hash = Option::<String>::deserialize(deserializer)?;
69    if let Some(hash) = &hash {
70        validate_bind_proof_sha256(hash).map_err(serde::de::Error::custom)?;
71    }
72    Ok(hash)
73}
74
75/// The `server.describe` capability a daemon advertises when it admits routes
76/// under scopes. A carrier that needs a scoped route and does not see it fails
77/// the call (`scope_unsupported`) instead of opening an unscoped route.
78pub const CAP_SCOPES_V1: &str = "scopes/v1";
79
80/// The `server.describe` capability a daemon advertises when it checks a
81/// `route.open`'s `role_versions` and forwards them on the module's bind. A
82/// daemon without it drops the field silently, so a consumer that relies on
83/// the provider seeing its role versions checks for this first.
84pub const CAP_ROUTE_ROLE_VERSIONS_V1: &str = "route-role-versions/v1";
85
86/// Module-to-subc op that registers an owner's full scope set.
87pub const SCOPE_SYNC_OP: &str = "scope.sync";
88/// Module-to-subc op that upserts or ends scopes without replacing the owner's
89/// full scope set.
90pub const SCOPE_APPLY_OP: &str = "scope.apply";
91/// Module-to-subc op that reads one scope's current state.
92pub const SCOPE_DESCRIBE_OP: &str = "scope.describe";
93
94/// Most live scopes one owner may hold. A sync naming more is refused whole.
95pub const MAX_LIVE_SCOPES_PER_OWNER: usize = 10_000;
96/// Most bytes one scope's `attributes` may take, measured as compact JSON. A
97/// sync carrying a larger record is refused whole.
98pub const MAX_SCOPE_ATTRIBUTE_BYTES: usize = 4 * 1024;
99/// Most ended scopes the daemon remembers per owner. The oldest is forgotten
100/// first, and reaching the bound never refuses a sync.
101pub const MAX_SCOPE_TOMBSTONES_PER_OWNER: usize = 1_000;
102/// Most modules one targeted carrier entry may list.
103pub const MAX_CARRIER_TARGETS: usize = 16;
104/// Most milliseconds a new scope epoch's deadline may be ahead of the daemon's
105/// current Unix wall clock: 24 hours.
106pub const MAX_SCOPE_EXPIRY_AHEAD_MS: u64 = 86_400_000;
107
108/// What a scope stands for. Closed, and fixed for the life of one
109/// `scope_epoch`: a different kind needs a new epoch, which ends the old scope.
110#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
111#[serde(rename_all = "snake_case")]
112pub enum ScopeKind {
113    Head,
114    Worker,
115    Ephemeral,
116}
117
118/// A link from a scope to another scope, pinned to that scope's session by its
119/// epoch.
120#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
121#[serde(deny_unknown_fields)]
122#[non_exhaustive]
123pub struct ScopeParent {
124    #[serde(deserialize_with = "deserialize_scope_principal")]
125    pub owner: Principal,
126    #[serde(rename = "ref")]
127    pub scope_ref: String,
128    pub scope_epoch: u64,
129}
130
131impl ScopeParent {
132    pub fn new(owner: Principal, scope_ref: impl Into<String>, scope_epoch: u64) -> Self {
133        Self {
134            owner,
135            scope_ref: scope_ref.into(),
136            scope_epoch,
137        }
138    }
139}
140
141/// Who, besides the owner, may open routes under a scope.
142///
143/// `targets` absent means the carrier may open to any module. Present, it
144/// names the only module ids the carrier may open to, and must hold between 1
145/// and [`MAX_CARRIER_TARGETS`] entries: an empty list is refused rather than
146/// read as either "none" or "all".
147#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
148#[serde(deny_unknown_fields)]
149#[non_exhaustive]
150pub struct ScopeCarrier {
151    #[serde(deserialize_with = "deserialize_scope_principal")]
152    pub principal: Principal,
153    #[serde(default, skip_serializing_if = "Option::is_none")]
154    pub targets: Option<Vec<String>>,
155}
156
157impl ScopeCarrier {
158    pub fn new(principal: Principal) -> Self {
159        Self {
160            principal,
161            targets: None,
162        }
163    }
164
165    #[must_use]
166    pub fn with_targets(mut self, targets: Option<Vec<String>>) -> Self {
167        self.targets = targets;
168        self
169    }
170}
171
172/// Declaring this in a manifest's `capabilities.provides` promises that the
173/// module recognises a scope carrying `flow_id` and applies flow behaviour:
174/// it never treats the flow as its owner agent.
175/// During migration, either this capability or
176/// [`crate::call_mode::CALL_MODES_CAPABILITY`] admits flow scopes.
177pub const FLOW_SCOPES_CAPABILITY: &str = "flow-scopes/v1";
178
179/// Declaring this in a manifest's `capabilities.provides` promises that the
180/// module recognises `run_id` as one agent run and does not exercise the agent's
181/// delegated authority under that scope.
182/// During migration it admits non-delegating run scopes; delegating runs require
183/// [`crate::call_mode::CALL_MODES_CAPABILITY`] instead.
184pub const AGENT_RUN_SCOPES_CAPABILITY: &str = "agent-run-scopes/v1";
185
186/// Declaring this in a manifest's `capabilities.provides` promises that the
187/// module recognises `on_behalf_of_agent` as attribution only, never authority.
188/// The daemon also advertises this capability to scope-authority owners.
189pub const SCOPE_ON_BEHALF_OF_CAPABILITY: &str = "scope-on-behalf-of/v1";
190
191/// The daemon can answer whether a module acknowledged a bind under an owned scope epoch.
192pub const SCOPE_SERVED_BY_CAPABILITY: &str = "scope-served-by/v1";
193
194/// The authority-controlled attributes the daemon copies into scope stamps,
195/// subject to each field's target capability gate.
196/// Only an owner module named in the daemon config's `scope_authority_owners`
197/// list (by default the module that owns agent sessions) may set them; a scope
198/// owned by any other module must leave them empty.
199#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
200#[serde(deny_unknown_fields)]
201#[non_exhaustive]
202pub struct ScopeAttributes {
203    /// The agent the scope's session belongs to. Identity, never permission.
204    #[serde(default, skip_serializing_if = "Option::is_none")]
205    pub agent_id: Option<String>,
206    /// Attribution only, never authority. A provider may use this to choose
207    /// identity-scoped presentation (bot choice, read budgets, bound
208    /// repositories) and for logging. It must never treat this as authority to
209    /// act as that agent, hand out the agent's per-agent handles or consent on
210    /// its strength, or treat it as `agent_id`.
211    ///
212    /// Set only by a scope-authority owner and validated with `agent_id`'s
213    /// token rule. Mutually exclusive with `agent_id`, `delegates` and `flow_id`;
214    /// `run_id` requires `agent_id` and is therefore excluded too. Adding,
215    /// changing or removing this within an epoch increments the content version
216    /// and closes routes with `scope_delegation_changed`. Bind stamps include
217    /// it only for targets providing [`SCOPE_ON_BEHALF_OF_CAPABILITY`]; describe
218    /// replies include it only for callers providing that capability.
219    #[serde(default, skip_serializing_if = "Option::is_none")]
220    pub on_behalf_of_agent: Option<String>,
221    /// Whether a provider may act as `agent_id`. Refused without `agent_id`.
222    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
223    pub delegates: bool,
224    /// This scope belongs to the named flow, an automated workflow run on an
225    /// agent's behalf. Set only by an authority owner (see above), validated
226    /// with [`validate_flow_id`], and stamped verbatim. It needs neither
227    /// `agent_id` nor `delegates`. Providers treat a module other than the
228    /// owner that opens a route under a flow scope as the flow's carrier.
229    ///
230    /// Like an `agent_id` change, changing this within the same scope epoch is
231    /// accepted: the scope's content version increases (the number providers
232    /// compare to notice a change), and every route under the scope is closed
233    /// with the reason `scope_delegation_changed`, so no live route keeps the
234    /// old identity.
235    /// A target must provide [`FLOW_SCOPES_CAPABILITY`] or
236    /// [`crate::call_mode::CALL_MODES_CAPABILITY`] before the daemon may send a
237    /// bind stamped with this field. Decoding it alone is not enough:
238    /// the target must also apply flow behaviour instead of agent behaviour.
239    #[serde(default, skip_serializing_if = "Option::is_none")]
240    pub flow_id: Option<String>,
241    /// Identifies one run carried out on behalf of `agent_id`. Requires
242    /// `agent_id`, forbids `flow_id`, and uses
243    /// [`validate_run_id`]'s token rule.
244    /// Adding, changing or removing it within an epoch increments the scope's
245    /// content version and closes routes under the scope with
246    /// `scope_delegation_changed`. The daemon sends this field in a bind only to
247    /// a target module providing [`AGENT_RUN_SCOPES_CAPABILITY`] or
248    /// [`crate::call_mode::CALL_MODES_CAPABILITY`]. A delegating run scope is
249    /// accepted as a record, but binds only to a target providing the latter.
250    #[serde(default, skip_serializing_if = "Option::is_none")]
251    pub run_id: Option<String>,
252}
253
254impl ScopeAttributes {
255    pub fn new() -> Self {
256        Self::default()
257    }
258
259    #[must_use]
260    pub fn with_agent_id(mut self, agent_id: Option<String>) -> Self {
261        self.agent_id = agent_id;
262        self
263    }
264
265    #[must_use]
266    pub fn with_on_behalf_of_agent(mut self, on_behalf_of_agent: Option<String>) -> Self {
267        self.on_behalf_of_agent = on_behalf_of_agent;
268        self
269    }
270
271    #[must_use]
272    pub fn with_delegates(mut self, delegates: bool) -> Self {
273        self.delegates = delegates;
274        self
275    }
276
277    #[must_use]
278    pub fn with_flow_id(mut self, flow_id: Option<String>) -> Self {
279        self.flow_id = flow_id;
280        self
281    }
282
283    #[must_use]
284    pub fn with_run_id(mut self, run_id: Option<String>) -> Self {
285        self.run_id = run_id;
286        self
287    }
288
289    pub fn is_empty(&self) -> bool {
290        self.agent_id.is_none()
291            && self.on_behalf_of_agent.is_none()
292            && !self.delegates
293            && self.flow_id.is_none()
294            && self.run_id.is_none()
295    }
296}
297
298/// Check a flow id using the shared opaque-token rule: 1–256 printable,
299/// non-space ASCII bytes. Errors name `flow_id`. Scope refs remain opaque and
300/// are not subject to this token rule.
301pub fn validate_flow_id(flow_id: &str) -> Result<(), crate::tool_call::OpaqueFieldError> {
302    crate::tool_call::validate_opaque_field("flow_id", flow_id)
303}
304
305/// Check a run id using the shared opaque-token rule: 1–256 ASCII bytes in
306/// `0x21`–`0x7E`. Errors name `run_id`.
307pub fn validate_run_id(run_id: &str) -> Result<(), crate::tool_call::OpaqueFieldError> {
308    crate::tool_call::validate_opaque_field("run_id", run_id)
309}
310
311/// Check attribution using the agent token rule: 1–256 printable, non-space
312/// ASCII bytes. Errors name `on_behalf_of_agent`.
313pub fn validate_on_behalf_of_agent(agent: &str) -> Result<(), crate::tool_call::OpaqueFieldError> {
314    crate::tool_call::validate_opaque_field("on_behalf_of_agent", agent)
315}
316
317/// Capability declaring that a provider accepts session folder and project stamps.
318pub const SCOPE_WORKDIR_CAPABILITY: &str = "scope-workdir/v1";
319
320/// Check an Entorhinal project id without interpreting its opaque contents.
321pub fn validate_project_id(value: &str) -> Result<(), &'static str> {
322    if value.is_empty() || value.len() > 128 {
323        return Err("project_id must contain 1 to 128 bytes");
324    }
325    if !value.bytes().all(|byte| (0x21..=0x7e).contains(&byte)) {
326        return Err("project_id must be printable ASCII without whitespace");
327    }
328    Ok(())
329}
330
331/// One scope as its owner registers it in `scope.sync` or `scope.apply`.
332#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
333#[serde(deny_unknown_fields)]
334#[non_exhaustive]
335pub struct ScopeRecord {
336    #[serde(rename = "ref")]
337    pub scope_ref: String,
338    /// Owner-supplied session number. The owner keeps it with its own record of
339    /// the session, re-sends the same value for the same session after any
340    /// restart, and uses a higher one when it reuses the ref for a new session.
341    pub scope_epoch: u64,
342    pub kind: ScopeKind,
343    /// Absolute session folder, canonicalized by the daemon and fixed per epoch.
344    /// Attribution only: this grants no authority.
345    #[serde(default, skip_serializing_if = "Option::is_none")]
346    pub workdir: Option<String>,
347    /// Opaque Entorhinal project id, fixed per epoch and never authority-gated.
348    #[serde(default, skip_serializing_if = "Option::is_none")]
349    pub project_id: Option<String>,
350    /// Only the holder of the scope's bind proof can bind it when this hash is
351    /// present. Without a hash, admission is unchanged and proofs are ignored.
352    #[serde(
353        default,
354        skip_serializing_if = "Option::is_none",
355        deserialize_with = "deserialize_bind_proof_sha256"
356    )]
357    pub bind_proof_sha256: Option<String>,
358    /// Refuse an epoch replacement or bind-proof change while routes are bound
359    /// to the live epoch, including binds admitted but not yet committed, or
360    /// connected presence holders remain. Send only after capability discovery.
361    /// This is a request condition, not a stored scope attribute.
362    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
363    pub replace_only_if_idle: bool,
364    /// Absolute Unix wall-clock deadline in milliseconds. It cannot be added,
365    /// changed or removed within this scope epoch; absent means no deadline.
366    /// This is not an authority attribute.
367    #[serde(default, skip_serializing_if = "Option::is_none")]
368    pub expires_at_ms: Option<u64>,
369    #[serde(default, skip_serializing_if = "Option::is_none")]
370    pub parent: Option<ScopeParent>,
371    /// Principals, other than the owner, allowed to register child scopes under
372    /// this one. Listing a principal here grants it nothing else.
373    #[serde(
374        default,
375        skip_serializing_if = "Vec::is_empty",
376        deserialize_with = "deserialize_scope_principals"
377    )]
378    pub child_owners: Vec<Principal>,
379    #[serde(default, skip_serializing_if = "Vec::is_empty")]
380    pub carriers: Vec<ScopeCarrier>,
381    #[serde(default, skip_serializing_if = "ScopeAttributes::is_empty")]
382    pub attributes: ScopeAttributes,
383}
384
385impl ScopeRecord {
386    pub fn new(scope_ref: impl Into<String>, scope_epoch: u64, kind: ScopeKind) -> Self {
387        Self {
388            scope_ref: scope_ref.into(),
389            scope_epoch,
390            kind,
391            workdir: None,
392            project_id: None,
393            bind_proof_sha256: None,
394            replace_only_if_idle: false,
395            expires_at_ms: None,
396            parent: None,
397            child_owners: Vec::new(),
398            carriers: Vec::new(),
399            attributes: ScopeAttributes::default(),
400        }
401    }
402
403    #[must_use]
404    pub fn with_workdir(mut self, workdir: Option<String>) -> Self {
405        self.workdir = workdir;
406        self
407    }
408
409    #[must_use]
410    pub fn with_project_id(mut self, project_id: Option<String>) -> Self {
411        self.project_id = project_id;
412        self
413    }
414
415    #[must_use]
416    pub fn with_bind_proof_sha256(mut self, hash: Option<String>) -> Self {
417        self.bind_proof_sha256 = hash;
418        self
419    }
420
421    #[must_use]
422    pub fn with_replace_only_if_idle(mut self, replace_only_if_idle: bool) -> Self {
423        self.replace_only_if_idle = replace_only_if_idle;
424        self
425    }
426
427    #[must_use]
428    pub fn with_expires_at_ms(mut self, expires_at_ms: Option<u64>) -> Self {
429        self.expires_at_ms = expires_at_ms;
430        self
431    }
432
433    #[must_use]
434    pub fn with_parent(mut self, parent: Option<ScopeParent>) -> Self {
435        self.parent = parent;
436        self
437    }
438
439    #[must_use]
440    pub fn with_child_owners(mut self, child_owners: Vec<Principal>) -> Self {
441        self.child_owners = child_owners;
442        self
443    }
444
445    #[must_use]
446    pub fn with_carriers(mut self, carriers: Vec<ScopeCarrier>) -> Self {
447        self.carriers = carriers;
448        self
449    }
450
451    #[must_use]
452    pub fn with_attributes(mut self, attributes: ScopeAttributes) -> Self {
453        self.attributes = attributes;
454        self
455    }
456}
457
458/// A request to end one scope session in `scope.apply`.
459#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
460#[serde(deny_unknown_fields)]
461#[non_exhaustive]
462pub struct ScopeEnd {
463    #[serde(rename = "ref")]
464    pub scope_ref: String,
465    pub scope_epoch: u64,
466}
467
468impl ScopeEnd {
469    pub fn new(scope_ref: impl Into<String>, scope_epoch: u64) -> Self {
470        Self {
471            scope_ref: scope_ref.into(),
472            scope_epoch,
473        }
474    }
475}
476
477/// What `scope.apply` did with one requested end.
478#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
479#[serde(rename_all = "snake_case")]
480pub enum ScopeEndOutcome {
481    /// The named scope ref was live at this epoch and was ended.
482    Ended,
483    /// The named scope ref was not live at this epoch; this end request changed
484    /// nothing.
485    NotLive,
486}
487
488/// The per-end result in a `scope.apply` reply, in request order.
489#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
490#[serde(deny_unknown_fields)]
491#[non_exhaustive]
492pub struct ScopeEndResult {
493    #[serde(rename = "ref")]
494    pub scope_ref: String,
495    pub scope_epoch: u64,
496    pub outcome: ScopeEndOutcome,
497}
498
499impl ScopeEndResult {
500    pub fn new(scope_ref: impl Into<String>, scope_epoch: u64, outcome: ScopeEndOutcome) -> Self {
501        Self {
502            scope_ref: scope_ref.into(),
503            scope_epoch,
504            outcome,
505        }
506    }
507}
508
509/// The scope a `route.open` asks to be admitted under.
510///
511/// `scope_epoch` is optional on the wire only so that leaving it out is
512/// refused by name (`scope_epoch_required`) rather than as a malformed body:
513/// every opener must name it, the owner included.
514#[derive(Clone, Serialize, Deserialize, PartialEq, Eq)]
515#[serde(deny_unknown_fields)]
516#[non_exhaustive]
517pub struct ScopeSelector {
518    #[serde(deserialize_with = "deserialize_scope_principal")]
519    pub owner: Principal,
520    #[serde(rename = "ref")]
521    pub scope_ref: String,
522    #[serde(default, skip_serializing_if = "Option::is_none")]
523    pub scope_epoch: Option<u64>,
524    /// Base64url-encoded 32-byte secret, without padding. Ignored for records
525    /// without a bind-proof hash, so holders may always send their proof.
526    #[serde(default, skip_serializing_if = "Option::is_none")]
527    pub bind_proof: Option<String>,
528    /// Keep connection-held presence after an admitted open, even if its route
529    /// closes. Send only to daemons advertising `scope-replace-if-idle/v1`.
530    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
531    pub hold_presence: bool,
532}
533
534impl ScopeSelector {
535    pub fn new(owner: Principal, scope_ref: impl Into<String>, scope_epoch: Option<u64>) -> Self {
536        Self {
537            owner,
538            scope_ref: scope_ref.into(),
539            scope_epoch,
540            bind_proof: None,
541            hold_presence: false,
542        }
543    }
544
545    #[must_use]
546    pub fn with_bind_proof(mut self, proof: Option<String>) -> Self {
547        self.bind_proof = proof;
548        self
549    }
550
551    #[must_use]
552    pub fn with_hold_presence(mut self, hold_presence: bool) -> Self {
553        self.hold_presence = hold_presence;
554        self
555    }
556}
557
558impl std::fmt::Debug for ScopeSelector {
559    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
560        f.debug_struct("ScopeSelector")
561            .field("owner", &self.owner)
562            .field("scope_ref", &self.scope_ref)
563            .field("scope_epoch", &self.scope_epoch)
564            .field(
565                "bind_proof",
566                &self.bind_proof.as_ref().map(|_| "<redacted>"),
567            )
568            .finish()
569    }
570}
571
572impl std::fmt::Display for ScopeSelector {
573    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
574        std::fmt::Debug::fmt(self, f)
575    }
576}
577
578/// The state of a scope's parent link.
579#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
580#[serde(rename_all = "snake_case")]
581pub enum ParentState {
582    /// The parent is live at the named epoch and the link was permitted.
583    Linked,
584    /// The parent's owner has not synced in this daemon incarnation, so the
585    /// link is unverified and grants nothing yet.
586    Pending,
587    /// The parent is gone or live at another epoch, or the link was refused
588    /// when the parent's owner synced. Final for this link.
589    Ended,
590}
591
592/// What a `scope.sync` or `scope.apply` did with one record.
593#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
594#[serde(rename_all = "snake_case")]
595pub enum ScopeRecordOutcome {
596    /// The ref was not live before; the scope was created.
597    Created,
598    /// The ref was live at a lower epoch; that scope ended and this one began.
599    Replaced,
600    /// The ref was live at this epoch and its content changed.
601    Updated,
602    /// The ref was live at this epoch with identical content; its `version`
603    /// did not move.
604    Unchanged,
605    /// The record was refused on its own merits (`code` says why). The refusal
606    /// itself does not change the ref or undo any expiry processing.
607    Refused,
608}
609
610/// The per-record result in a `scope.sync` or `scope.apply` reply, in request order.
611#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
612pub struct ScopeRecordResult {
613    #[serde(rename = "ref")]
614    pub scope_ref: String,
615    /// The epoch the record named, which for a refusal may differ from the
616    /// epoch still held.
617    pub scope_epoch: u64,
618    pub outcome: ScopeRecordOutcome,
619    /// The refusal code when `outcome` is `refused`.
620    #[serde(default, skip_serializing_if = "Option::is_none")]
621    pub code: Option<String>,
622    #[serde(default, skip_serializing_if = "Option::is_none")]
623    pub message: Option<String>,
624    /// The daemon's content counter for the scope held under this ref after
625    /// the sync; absent when no scope is live under it.
626    #[serde(default, skip_serializing_if = "Option::is_none")]
627    pub version: Option<u64>,
628    /// The parent link's state after the sync, for a scope with a parent.
629    #[serde(default, skip_serializing_if = "Option::is_none")]
630    pub parent_state: Option<ParentState>,
631}
632
633/// A scope session of the calling owner that ended through omission from
634/// `scope.sync`, an explicit `scope.apply` end, replacement by a higher epoch
635/// for the same ref or expiry.
636#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
637pub struct ScopeEnded {
638    #[serde(rename = "ref")]
639    pub scope_ref: String,
640    pub scope_epoch: u64,
641}
642
643/// `scope.describe`'s answer about one `(owner, ref)`.
644#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
645#[serde(rename_all = "snake_case")]
646pub enum ScopeStatus {
647    Live,
648    /// Ended in this daemon incarnation, and still remembered.
649    Ended,
650    /// Neither live nor remembered as ended. With `owner_synced` true the scope
651    /// is gone: an owner's first sync of an incarnation is its full set. With
652    /// `owner_synced` false and `owner_configured` true the owner has not
653    /// re-synced since a daemon restart, so a reader waits. With
654    /// `owner_configured` false the owner will never sync.
655    NotLive,
656}
657
658/// The fields the daemon stamps for a live scope.
659/// Build with [`ScopeStamp::new`] and the setters so future fields are additive.
660#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
661#[non_exhaustive]
662pub struct ScopeStamp {
663    pub owner: Principal,
664    #[serde(rename = "ref")]
665    pub scope_ref: String,
666    pub scope_epoch: u64,
667    pub kind: ScopeKind,
668    /// Canonical session folder. Sent on binds only to providers declaring
669    /// [`SCOPE_WORKDIR_CAPABILITY`]; absent fields keep older binds unchanged.
670    #[serde(default, skip_serializing_if = "Option::is_none")]
671    pub workdir: Option<String>,
672    /// Entorhinal project id for attribution, never authority.
673    #[serde(default, skip_serializing_if = "Option::is_none")]
674    pub project_id: Option<String>,
675    #[serde(default, skip_serializing_if = "Option::is_none")]
676    pub parent: Option<ScopeParent>,
677    #[serde(default, skip_serializing_if = "Option::is_none")]
678    pub parent_state: Option<ParentState>,
679    #[serde(default, skip_serializing_if = "ScopeAttributes::is_empty")]
680    pub attributes: ScopeAttributes,
681    /// Whether the owner is listed in the daemon's `scope_authority_owners`.
682    /// Providers decide on this flag and keep no copy of the list.
683    pub owner_authorized: bool,
684    /// Absolute Unix wall-clock deadline in milliseconds, fixed for this epoch.
685    /// On route binds the daemon sends this deadline only to targets declaring
686    /// [`crate::call_mode::CALL_MODES_CAPABILITY`], because older providers may
687    /// reject unfamiliar scope-stamp fields.
688    #[serde(default, skip_serializing_if = "Option::is_none")]
689    pub expires_at_ms: Option<u64>,
690}
691
692impl ScopeStamp {
693    /// A stamp with no parent, attributes or deadline, and no owner authority.
694    pub fn new(
695        owner: Principal,
696        scope_ref: impl Into<String>,
697        scope_epoch: u64,
698        kind: ScopeKind,
699    ) -> Self {
700        Self {
701            owner,
702            scope_ref: scope_ref.into(),
703            scope_epoch,
704            kind,
705            workdir: None,
706            project_id: None,
707            parent: None,
708            parent_state: None,
709            attributes: ScopeAttributes::new(),
710            owner_authorized: false,
711            expires_at_ms: None,
712        }
713    }
714
715    #[must_use]
716    pub fn with_workdir(mut self, workdir: Option<String>) -> Self {
717        self.workdir = workdir;
718        self
719    }
720
721    #[must_use]
722    pub fn with_project_id(mut self, project_id: Option<String>) -> Self {
723        self.project_id = project_id;
724        self
725    }
726
727    #[must_use]
728    pub fn with_parent(mut self, parent: Option<ScopeParent>) -> Self {
729        self.parent = parent;
730        self
731    }
732
733    #[must_use]
734    pub fn with_parent_state(mut self, parent_state: Option<ParentState>) -> Self {
735        self.parent_state = parent_state;
736        self
737    }
738
739    #[must_use]
740    pub fn with_attributes(mut self, attributes: ScopeAttributes) -> Self {
741        self.attributes = attributes;
742        self
743    }
744
745    #[must_use]
746    pub fn with_owner_authorized(mut self, owner_authorized: bool) -> Self {
747        self.owner_authorized = owner_authorized;
748        self
749    }
750
751    #[must_use]
752    pub fn with_expires_at_ms(mut self, expires_at_ms: Option<u64>) -> Self {
753        self.expires_at_ms = expires_at_ms;
754        self
755    }
756}
757
758#[cfg(test)]
759mod tests {
760    use super::*;
761    use crate::tool_call::OpaqueFieldError;
762
763    #[test]
764    fn project_id_is_an_opaque_non_space_ascii_token_of_at_most_128_bytes() {
765        for valid in ["p", "!~Project:7/path", &"p".repeat(128)] {
766            assert_eq!(validate_project_id(valid), Ok(()));
767        }
768        for invalid in ["", "p p", "p\t", "pé", "p\u{7f}", &"p".repeat(129)] {
769            assert!(validate_project_id(invalid).is_err(), "{invalid:?}");
770        }
771    }
772
773    #[test]
774    fn scope_project_fields_round_trip_and_absence_keeps_exact_bytes() {
775        let record = ScopeRecord::new("session", 1, ScopeKind::Head);
776        assert_eq!(
777            serde_json::to_string(&record).unwrap(),
778            r#"{"ref":"session","scope_epoch":1,"kind":"head"}"#
779        );
780        let record = record
781            .with_workdir(Some("/folder".into()))
782            .with_project_id(Some("project:1".into()));
783        let encoded = serde_json::to_string(&record).unwrap();
784        assert_eq!(
785            serde_json::from_str::<ScopeRecord>(&encoded).unwrap(),
786            record
787        );
788        let stamp = ScopeStamp::new(Principal::Direct, "session", 1, ScopeKind::Head);
789        assert_eq!(
790            serde_json::to_string(&stamp).unwrap(),
791            r#"{"owner":{"kind":"direct"},"ref":"session","scope_epoch":1,"kind":"head","owner_authorized":false}"#
792        );
793        let stamp = stamp
794            .with_workdir(record.workdir)
795            .with_project_id(record.project_id);
796        let encoded = serde_json::to_string(&stamp).unwrap();
797        assert_eq!(serde_json::from_str::<ScopeStamp>(&encoded).unwrap(), stamp);
798    }
799
800    #[test]
801    fn flow_id_uses_the_shared_opaque_token_bounds_and_names_its_field() {
802        let field = "flow_id";
803        assert_eq!(validate_flow_id(""), Err(OpaqueFieldError::Empty { field }));
804        assert_eq!(validate_flow_id("f"), Ok(()));
805        assert_eq!(validate_flow_id(&"f".repeat(256)), Ok(()));
806        assert_eq!(
807            validate_flow_id(&"f".repeat(257)),
808            Err(OpaqueFieldError::TooLong { field, length: 257 })
809        );
810        assert_eq!(validate_flow_id("!~Flow:7/step"), Ok(()));
811        for bad in ["f é", "f\t", "fé", "f\u{7f}"] {
812            let error = validate_flow_id(bad).unwrap_err();
813            assert_eq!(
814                error,
815                OpaqueFieldError::InvalidCharacter { field, index: 1 }
816            );
817            assert_eq!(error.field(), "flow_id");
818        }
819    }
820
821    #[test]
822    fn flow_only_attributes_round_trip_and_absence_keeps_the_bytes() {
823        let attributes = ScopeAttributes::default();
824        assert!(attributes.is_empty());
825        assert_eq!(serde_json::to_string(&attributes).unwrap(), "{}");
826        assert_eq!(
827            serde_json::from_str::<ScopeAttributes>("{}").unwrap(),
828            attributes
829        );
830        let attributes = ScopeAttributes {
831            flow_id: Some("flow:7".to_string()),
832            ..ScopeAttributes::default()
833        };
834        assert!(!attributes.is_empty());
835        let encoded = serde_json::to_string(&attributes).unwrap();
836        assert_eq!(encoded, r#"{"flow_id":"flow:7"}"#);
837        assert_eq!(
838            serde_json::from_str::<ScopeAttributes>(&encoded).unwrap(),
839            attributes
840        );
841        assert!(
842            serde_json::from_str::<ScopeAttributes>(r#"{"flow_id":"flow:7","unknown":true}"#)
843                .is_err()
844        );
845    }
846}