Skip to main content

stateknot_runtime/agent_service/
activity.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4use super::{
5    AgentRunSnapshot, AgentServiceCaller, AgentServiceError, AgentServiceRunOperation,
6    AgentServiceRunTarget, AgentServiceV1,
7};
8use stateknot_core::{JournalHead, RunId};
9use stateknot_store_postgres::JournalPageSize;
10
11/// Public metadata for at most one durable activity notification and a current
12/// snapshot. These are separate observations, NOT a historical state projection.
13/// Journal payloads, custom kinds and worker details never cross this boundary.
14#[derive(Clone, Debug)]
15pub struct AgentRunActivityPage {
16    snapshot: AgentRunSnapshot,
17    head: Option<JournalHead>,
18    has_more: bool,
19}
20
21impl AgentRunActivityPage {
22    /// Returns the verified snapshot observed before the journal page read.
23    #[must_use]
24    pub const fn snapshot(&self) -> &AgentRunSnapshot {
25        &self.snapshot
26    }
27
28    /// Exact committed metadata; the checksum is integrity evidence, not authority.
29    #[must_use]
30    pub const fn head(&self) -> Option<&JournalHead> {
31        self.head.as_ref()
32    }
33
34    /// Whether another event existed in the journal read's database snapshot.
35    #[must_use]
36    pub const fn has_more(&self) -> bool {
37        self.has_more
38    }
39}
40
41impl AgentServiceV1 {
42    /// Authorizes before verifying an Agent and reading one exact journal suffix.
43    ///
44    /// A one-event page bounds private payload materialization in the store. No
45    /// cursor starts at sequence one. The store checks a supplied head against
46    /// the retained event; it never treats caller metadata as trusted authority.
47    /// Snapshots may coalesce transitions and must not be interpreted at the head.
48    ///
49    /// # Errors
50    ///
51    /// Denial precedes existence/cursor validation. Missing history, changed scope
52    /// or any mismatch fails closed rather than silently restarting replay.
53    pub async fn load_activity(
54        &self,
55        caller: AgentServiceCaller,
56        run_id: RunId,
57        after: Option<&JournalHead>,
58    ) -> Result<AgentRunActivityPage, AgentServiceError> {
59        self.authorize_run(
60            &caller,
61            AgentServiceRunTarget::Run(run_id),
62            AgentServiceRunOperation::Read,
63        )
64        .await?;
65        let snapshot = self.runs.load(caller.tenant_id(), run_id).await?;
66        let page = self
67            .store
68            .load_journal_page(
69                caller.tenant_id(),
70                run_id,
71                after,
72                JournalPageSize::new(1).expect("static bounded journal page"),
73            )
74            .await?;
75        Ok(AgentRunActivityPage {
76            snapshot,
77            head: page.next_cursor(),
78            has_more: page.has_more(),
79        })
80    }
81}