1use std::marker::PhantomData;
2
3use crate::{
4 adaptive::{AdaptivePolicy, EncodeDecision},
5 binary::{
6 decode_agent_delta, decode_agent_state, encode_agent_delta, encode_agent_state, AgentDelta,
7 },
8 error::DeltaError,
9 packet::{DecodeConfig, Packet, PacketKind},
10 replay::ReplayWindow,
11 schema::{
12 decode_generic_delta, decode_generic_snapshot, encode_generic_delta,
13 encode_generic_snapshot, DeltaState, JsonFieldDelta,
14 },
15 state::AgentState,
16};
17
18pub const AGENT_SCHEMA_NAME: &str = "delta-stream/AgentState/v2";
19
20pub fn agent_schema_hash() -> u64 {
21 fnv1a64(AGENT_SCHEMA_NAME.as_bytes())
22}
23
24pub fn state_hash(state: &AgentState) -> Result<u64, DeltaError> {
25 Ok(fnv1a64(&encode_agent_state(state)?))
26}
27
28pub fn fnv1a64(bytes: &[u8]) -> u64 {
29 let mut hash = 0xcbf29ce484222325u64;
30 for &b in bytes {
31 hash ^= b as u64;
32 hash = hash.wrapping_mul(0x100000001b3);
33 }
34 hash
35}
36
37fn raw_snapshot(sequence: u64, state: &AgentState) -> Result<Packet, DeltaError> {
38 Ok(Packet::snapshot(
39 sequence,
40 state_hash(state)?,
41 agent_schema_hash(),
42 encode_agent_state(state)?,
43 ))
44}
45
46#[derive(Debug, Default)]
47pub struct Encoder {
48 sequence: u64,
49 last_state: Option<AgentState>,
50 policy: AdaptivePolicy,
51 last_decision: Option<EncodeDecision>,
52}
53
54impl Encoder {
55 pub fn with_policy(policy: AdaptivePolicy) -> Self {
56 Self {
57 policy,
58 ..Self::default()
59 }
60 }
61
62 pub fn encode(&mut self, state: &AgentState) -> Result<Packet, DeltaError> {
65 self.sequence = self.sequence.saturating_add(1);
66 let sequence = self.sequence;
67 let snapshot = raw_snapshot(sequence, state)?;
68
69 let packet = match &self.last_state {
70 None => {
71 let (selected, decision) = self.policy.select_initial(snapshot)?;
72 self.last_decision = Some(decision);
73 selected
74 }
75 Some(previous) => {
76 let delta = AgentDelta::between(previous, state);
77 let delta = Packet::delta(
78 sequence,
79 sequence - 1,
80 state_hash(previous)?,
81 agent_schema_hash(),
82 encode_agent_delta(&delta)?,
83 );
84 let (selected, decision) = self.policy.select(snapshot, delta)?;
85 self.last_decision = Some(decision);
86 selected
87 }
88 };
89
90 self.last_state = Some(state.clone());
91 Ok(packet)
92 }
93
94 pub fn force_snapshot(&mut self, state: &AgentState) -> Result<Packet, DeltaError> {
95 self.sequence = self.sequence.saturating_add(1);
96 self.last_state = Some(state.clone());
97 let snapshot = raw_snapshot(self.sequence, state)?;
98 let (packet, decision) = self.policy.select_initial(snapshot)?;
99 self.last_decision = Some(decision);
100 Ok(packet)
101 }
102
103 pub fn recovery_snapshot(&self, state: &AgentState) -> Result<Packet, DeltaError> {
107 let snapshot = raw_snapshot(self.sequence, state)?;
108 Ok(self.policy.select_initial(snapshot)?.0)
109 }
110
111 pub fn sequence(&self) -> u64 {
112 self.sequence
113 }
114 pub fn last_decision(&self) -> Option<EncodeDecision> {
115 self.last_decision
116 }
117 pub fn policy(&self) -> AdaptivePolicy {
118 self.policy
119 }
120}
121
122#[derive(Debug, Clone, PartialEq)]
123pub enum ApplyResult {
124 Applied {
125 sequence: u64,
126 state: AgentState,
127 },
128 NeedSnapshot {
129 local_sequence: Option<u64>,
130 required_sequence: u64,
131 },
132 Duplicate {
133 sequence: u64,
134 },
135}
136
137#[derive(Debug, Default)]
138pub struct Decoder {
139 sequence: Option<u64>,
140 state: Option<AgentState>,
141 replay: ReplayWindow,
142}
143
144impl Decoder {
145 pub fn apply_packet(&mut self, packet: Packet) -> Result<ApplyResult, DeltaError> {
146 if packet.schema_hash != agent_schema_hash() {
147 return Err(DeltaError::SchemaMismatch {
148 expected: agent_schema_hash(),
149 received: packet.schema_hash,
150 });
151 }
152 if self.replay.contains(packet.sequence) {
153 return Ok(ApplyResult::Duplicate {
154 sequence: packet.sequence,
155 });
156 }
157 if self.sequence.is_some_and(|local| packet.sequence < local) {
158 return Ok(ApplyResult::Duplicate {
159 sequence: packet.sequence,
160 });
161 }
162
163 let result = match packet.kind {
164 PacketKind::Snapshot => {
165 let payload = packet.logical_payload_with_config(&DecodeConfig::default())?;
166 let state = decode_agent_state(&payload)?;
167 if state_hash(&state)? != packet.base_hash {
168 return Err(DeltaError::InvalidState("snapshot hash mismatch"));
169 }
170 self.sequence = Some(packet.sequence);
171 self.state = Some(state.clone());
172 ApplyResult::Applied {
173 sequence: packet.sequence,
174 state,
175 }
176 }
177 PacketKind::Delta => {
178 if self.sequence != Some(packet.base_sequence) {
179 return Ok(ApplyResult::NeedSnapshot {
180 local_sequence: self.sequence,
181 required_sequence: packet.base_sequence,
182 });
183 }
184 let current = self
185 .state
186 .as_ref()
187 .ok_or(DeltaError::InvalidState("decoder has no base state"))?;
188 if state_hash(current)? != packet.base_hash {
189 return Ok(ApplyResult::NeedSnapshot {
190 local_sequence: self.sequence,
191 required_sequence: packet.base_sequence,
192 });
193 }
194 let payload = packet.logical_payload_with_config(&DecodeConfig::default())?;
195 let delta = decode_agent_delta(&payload)?;
196 let next = delta.apply(current)?;
197 self.sequence = Some(packet.sequence);
198 self.state = Some(next.clone());
199 ApplyResult::Applied {
200 sequence: packet.sequence,
201 state: next,
202 }
203 }
204 };
205
206 self.replay.record(packet.sequence);
207 Ok(result)
208 }
209
210 pub fn state(&self) -> Option<&AgentState> {
211 self.state.as_ref()
212 }
213 pub fn sequence(&self) -> Option<u64> {
214 self.sequence
215 }
216 pub fn reset(&mut self) {
217 self.sequence = None;
218 self.state = None;
219 self.replay.clear();
220 }
221}
222
223pub struct GenericEncoder<T: DeltaState> {
224 sequence: u64,
225 last_state: Option<T>,
226 policy: AdaptivePolicy,
227 last_decision: Option<EncodeDecision>,
228}
229
230impl<T: DeltaState> Default for GenericEncoder<T> {
231 fn default() -> Self {
232 Self {
233 sequence: 0,
234 last_state: None,
235 policy: AdaptivePolicy::default(),
236 last_decision: None,
237 }
238 }
239}
240
241impl<T: DeltaState> GenericEncoder<T> {
242 pub fn with_policy(policy: AdaptivePolicy) -> Self {
243 Self {
244 policy,
245 ..Self::default()
246 }
247 }
248
249 pub fn encode(&mut self, state: &T) -> Result<Packet, DeltaError> {
250 self.sequence = self.sequence.saturating_add(1);
251 let sequence = self.sequence;
252 let bytes = encode_generic_snapshot(state)?;
253 let snapshot = Packet::snapshot(sequence, fnv1a64(&bytes), T::schema_hash(), bytes);
254
255 let packet = match &self.last_state {
256 None => {
257 let (selected, decision) = self.policy.select_initial(snapshot)?;
258 self.last_decision = Some(decision);
259 selected
260 }
261 Some(previous) => {
262 let old = encode_generic_snapshot(previous)?;
263 let delta = JsonFieldDelta::between(previous, state)?;
264 let delta = Packet::delta(
265 sequence,
266 sequence - 1,
267 fnv1a64(&old),
268 T::schema_hash(),
269 encode_generic_delta(&delta)?,
270 );
271 let (selected, decision) = self.policy.select(snapshot, delta)?;
272 self.last_decision = Some(decision);
273 selected
274 }
275 };
276
277 self.last_state = Some(state.clone());
278 Ok(packet)
279 }
280
281 pub fn force_snapshot(&mut self, state: &T) -> Result<Packet, DeltaError> {
282 self.sequence = self.sequence.saturating_add(1);
283 let bytes = encode_generic_snapshot(state)?;
284 self.last_state = Some(state.clone());
285 let snapshot = Packet::snapshot(self.sequence, fnv1a64(&bytes), T::schema_hash(), bytes);
286 let (packet, decision) = self.policy.select_initial(snapshot)?;
287 self.last_decision = Some(decision);
288 Ok(packet)
289 }
290
291 pub fn recovery_snapshot(&self, state: &T) -> Result<Packet, DeltaError> {
292 let bytes = encode_generic_snapshot(state)?;
293 let snapshot = Packet::snapshot(self.sequence, fnv1a64(&bytes), T::schema_hash(), bytes);
294 Ok(self.policy.select_initial(snapshot)?.0)
295 }
296
297 pub fn last_decision(&self) -> Option<EncodeDecision> {
298 self.last_decision
299 }
300 pub fn sequence(&self) -> u64 {
301 self.sequence
302 }
303}
304
305pub struct GenericDecoder<T: DeltaState> {
306 sequence: Option<u64>,
307 state: Option<T>,
308 replay: ReplayWindow,
309 decode_config: DecodeConfig,
310 _marker: PhantomData<T>,
311}
312
313impl<T: DeltaState> Default for GenericDecoder<T> {
314 fn default() -> Self {
315 Self {
316 sequence: None,
317 state: None,
318 replay: ReplayWindow::default(),
319 decode_config: DecodeConfig::default(),
320 _marker: PhantomData,
321 }
322 }
323}
324
325#[derive(Debug, Clone, PartialEq)]
331pub enum GenericApplyResult<T> {
332 Applied {
333 sequence: u64,
334 state: T,
335 },
336 NeedSnapshot {
337 local_sequence: Option<u64>,
338 required_sequence: u64,
339 },
340 Duplicate {
341 sequence: u64,
342 },
343}
344
345impl<T: DeltaState> GenericDecoder<T> {
346 pub fn with_decode_config(decode_config: DecodeConfig) -> Self {
347 Self {
348 decode_config,
349 ..Self::default()
350 }
351 }
352
353 pub fn apply_packet(&mut self, packet: Packet) -> Result<GenericApplyResult<T>, DeltaError> {
354 if packet.schema_hash != T::schema_hash() {
355 return Err(DeltaError::SchemaMismatch {
356 expected: T::schema_hash(),
357 received: packet.schema_hash,
358 });
359 }
360 if self.replay.contains(packet.sequence) {
361 return Ok(GenericApplyResult::Duplicate {
362 sequence: packet.sequence,
363 });
364 }
365 if self.sequence.is_some_and(|local| packet.sequence < local) {
366 return Ok(GenericApplyResult::Duplicate {
367 sequence: packet.sequence,
368 });
369 }
370
371 let result = match packet.kind {
372 PacketKind::Snapshot => {
373 let payload = packet.logical_payload_with_config(&self.decode_config)?;
374 if fnv1a64(&payload) != packet.base_hash {
375 return Err(DeltaError::InvalidState("snapshot hash mismatch"));
376 }
377 let state = decode_generic_snapshot::<T>(&payload)?;
378 self.sequence = Some(packet.sequence);
379 self.state = Some(state.clone());
380 GenericApplyResult::Applied {
381 sequence: packet.sequence,
382 state,
383 }
384 }
385 PacketKind::Delta => {
386 if self.sequence != Some(packet.base_sequence) {
387 return Ok(GenericApplyResult::NeedSnapshot {
388 local_sequence: self.sequence,
389 required_sequence: packet.base_sequence,
390 });
391 }
392 let current = self
393 .state
394 .as_ref()
395 .ok_or(DeltaError::InvalidState("decoder has no base state"))?;
396 let current_bytes = encode_generic_snapshot(current)?;
397 if fnv1a64(¤t_bytes) != packet.base_hash {
398 return Ok(GenericApplyResult::NeedSnapshot {
399 local_sequence: self.sequence,
400 required_sequence: packet.base_sequence,
401 });
402 }
403 let payload = packet.logical_payload_with_config(&self.decode_config)?;
404 let delta = decode_generic_delta(&payload)?;
405 let next = delta.apply(current)?;
406 self.sequence = Some(packet.sequence);
407 self.state = Some(next.clone());
408 GenericApplyResult::Applied {
409 sequence: packet.sequence,
410 state: next,
411 }
412 }
413 };
414
415 self.replay.record(packet.sequence);
416 Ok(result)
417 }
418 pub fn apply_packet_with_migrations(
419 &mut self,
420 packet: Packet,
421 migrations: &crate::migration::MigrationRegistry,
422 ) -> Result<GenericApplyResult<T>, DeltaError> {
423 if packet.schema_hash == T::schema_hash() {
424 return self.apply_packet(packet);
425 }
426 if packet.kind != PacketKind::Snapshot {
427 return Ok(GenericApplyResult::NeedSnapshot {
428 local_sequence: self.sequence,
429 required_sequence: packet.base_sequence,
430 });
431 }
432 if self.replay.contains(packet.sequence) {
433 return Ok(GenericApplyResult::Duplicate {
434 sequence: packet.sequence,
435 });
436 }
437 if self.sequence.is_some_and(|local| packet.sequence < local) {
438 return Ok(GenericApplyResult::Duplicate {
439 sequence: packet.sequence,
440 });
441 }
442 let payload = packet.logical_payload_with_config(&self.decode_config)?;
443 if fnv1a64(&payload) != packet.base_hash {
444 return Err(DeltaError::InvalidState("snapshot hash mismatch"));
445 }
446 let value: serde_json::Value = serde_json::from_slice(&payload)?;
447 let migrated = migrations.migrate(packet.schema_hash, T::schema_hash(), value)?;
448 let state: T = serde_json::from_value(migrated)?;
449 self.sequence = Some(packet.sequence);
450 self.state = Some(state.clone());
451 self.replay.record(packet.sequence);
452 Ok(GenericApplyResult::Applied {
453 sequence: packet.sequence,
454 state,
455 })
456 }
457
458 pub fn state(&self) -> Option<&T> {
459 self.state.as_ref()
460 }
461 pub fn sequence(&self) -> Option<u64> {
462 self.sequence
463 }
464 pub fn reset(&mut self) {
465 self.sequence = None;
466 self.state = None;
467 self.replay.clear();
468 }
469}