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}