logit-loom-core 0.2.0

Backend-neutral contracts for mechanistic token-stream manipulation
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Versioned contracts and receipts for target-authoritative speculation.

use serde::{Deserialize, Serialize};

use crate::{
    ActivationTelemetryDispositionV1, CoreError, Digest, MAX_SPECULATIVE_TOKENS,
    TextModelTopologyV1, TextSpeculativeMechanismV1, TokenId,
};

/// Maximum sequence slots declared by one speculative plan.
pub const MAX_SPECULATION_SEQUENCES: u32 = 4_096;
/// Maximum completed proposal boundaries retained in one aggregate receipt.
pub const MAX_SPECULATION_BOUNDARIES: usize = 1_048_576;
/// Maximum activation telemetry resolutions retained at one proposal boundary.
pub const MAX_SPECULATION_TELEMETRY_RESOLUTIONS: usize = 65_536;
/// Maximum opaque speculative implementation-state bytes.
pub const MAX_SPECULATION_STATE_BYTES: u64 = 64 * 1024 * 1024;

/// Explicit target and draft activation-program selection.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
pub enum SpeculationActivationPolicyV1 {
    /// Run no activation program in either context.
    None,
    /// Apply one program to target prefill, generation, and verification only.
    TargetOnly {
        /// Exact target activation-program identity.
        target_program: Digest,
    },
    /// Apply independently validated programs to target and draft contexts.
    SeparateDraftProgram {
        /// Exact target activation-program identity.
        target_program: Digest,
        /// Exact draft activation-program identity.
        draft_program: Digest,
    },
}

impl SpeculationActivationPolicyV1 {
    /// Returns the selected target-program identity.
    pub const fn target_program(&self) -> Option<&Digest> {
        match self {
            Self::None => None,
            Self::TargetOnly { target_program }
            | Self::SeparateDraftProgram { target_program, .. } => Some(target_program),
        }
    }

    /// Returns the independently selected draft-program identity.
    pub const fn draft_program(&self) -> Option<&Digest> {
        match self {
            Self::SeparateDraftProgram { draft_program, .. } => Some(draft_program),
            Self::None | Self::TargetOnly { .. } => None,
        }
    }
}

/// Complete backend-neutral configuration for one speculative text operation.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculationPlanV1 {
    /// Target model artifact identity.
    pub target_model: Digest,
    /// Target topology identity.
    pub target_topology: Digest,
    /// Draft model artifact identity.
    pub draft_model: Digest,
    /// Draft topology identity.
    pub draft_topology: Digest,
    /// Exact native and safe-wrapper implementation identity.
    pub implementation: Digest,
    /// Native proposal mechanism.
    pub mechanism: TextSpeculativeMechanismV1,
    /// Concurrent sequence slots.
    pub sequences: u32,
    /// Inclusive proposal-token bound at each boundary.
    pub maximum_draft_tokens: u32,
    /// Minimum proposal tokens requested from the draft implementation.
    pub minimum_draft_tokens: u32,
    /// Exact IEEE-754 draft probability-floor bits.
    pub probability_floor_bits: u32,
    /// Explicit target/draft activation selection.
    pub activation: SpeculationActivationPolicyV1,
}

impl SpeculationPlanV1 {
    /// Returns the finite draft probability floor.
    ///
    /// # Errors
    ///
    /// Returns an error when the encoded value is NaN, infinite, or outside
    /// the inclusive unit interval.
    pub fn probability_floor(&self) -> Result<f32, CoreError> {
        let value = f32::from_bits(self.probability_floor_bits);
        if !value.is_finite() || !(0.0..=1.0).contains(&value) {
            return Err(CoreError::invalid(
                "speculation probability floor",
                "value must be finite and between zero and one",
            ));
        }
        Ok(value)
    }

    /// Validates model, topology, mechanism, and bound compatibility.
    ///
    /// # Errors
    ///
    /// Returns an error for mismatched topology lineage, an unavailable
    /// mechanism, incompatible MTP/EAGLE model relationships, or malformed
    /// sequence, proposal, probability, or activation bounds.
    pub fn digest_for(
        &self,
        target: &TextModelTopologyV1,
        draft: &TextModelTopologyV1,
    ) -> Result<Digest, CoreError> {
        let target_topology = target.digest()?;
        let draft_topology = draft.digest()?;
        if self.target_model != target.model
            || self.target_topology != target_topology
            || self.draft_model != draft.model
            || self.draft_topology != draft_topology
        {
            return Err(CoreError::invalid(
                "speculation plan",
                "model or topology lineage does not match",
            ));
        }
        if !target.supported_speculation.contains(&self.mechanism) {
            return Err(CoreError::invalid(
                "speculation plan",
                "target topology does not report the selected mechanism",
            ));
        }
        match self.mechanism {
            TextSpeculativeMechanismV1::Mtp => {
                if target.model != draft.model || target_topology != draft_topology {
                    return Err(CoreError::invalid(
                        "speculation plan",
                        "MTP requires target and draft contexts over one exact topology",
                    ));
                }
                if target.nextn_layers == 0 {
                    return Err(CoreError::invalid(
                        "speculation plan",
                        "MTP requires at least one reported NextN layer",
                    ));
                }
            }
            TextSpeculativeMechanismV1::Eagle3 => {
                if target.model == draft.model {
                    return Err(CoreError::invalid(
                        "speculation plan",
                        "EAGLE-3 requires a separately identified draft model",
                    ));
                }
            }
        }
        if self.sequences == 0 || self.sequences > MAX_SPECULATION_SEQUENCES {
            return Err(CoreError::invalid(
                "speculation plan",
                "sequence count is outside the supported bound",
            ));
        }
        if self.maximum_draft_tokens == 0
            || self.maximum_draft_tokens > MAX_SPECULATIVE_TOKENS
            || self.minimum_draft_tokens > self.maximum_draft_tokens
        {
            return Err(CoreError::invalid(
                "speculation plan",
                "draft token bounds are inconsistent or excessive",
            ));
        }
        self.probability_floor()?;
        Digest::of_serializable("speculation-plan-v1", self)
    }
}

/// Final disposition of one provisional activation telemetry record.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculationTelemetryResolutionV1 {
    /// Identity emitted while target verification was unresolved.
    pub provisional: Digest,
    /// Target-authoritative final disposition.
    pub disposition: ActivationTelemetryDispositionV1,
    /// Identity of the final admitted or rejected activation record.
    pub resolved: Digest,
}

impl SpeculationTelemetryResolutionV1 {
    fn validate(&self) -> Result<(), CoreError> {
        if self.disposition == ActivationTelemetryDispositionV1::Provisional {
            return Err(CoreError::invalid(
                "speculation telemetry resolution",
                "final disposition cannot remain provisional",
            ));
        }
        Ok(())
    }
}

/// Target-authoritative accounting for one completed proposal boundary.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculationBoundaryReceiptV1 {
    /// Exact speculation-plan identity.
    pub plan: Digest,
    /// Zero-based completed boundary index.
    pub boundary: u64,
    /// Identity of proposed token IDs in exact draft order.
    pub proposal: Digest,
    /// Number of proposed token IDs.
    pub proposed: u32,
    /// Accepted proposal prefix length.
    pub accepted: u32,
    /// Rejected proposal suffix length.
    pub rejected: u32,
    /// Provisional telemetry resolved by this target decision.
    #[serde(default)]
    pub telemetry: Vec<SpeculationTelemetryResolutionV1>,
}

impl SpeculationBoundaryReceiptV1 {
    /// Constructs exact boundary accounting from one proposal and accepted
    /// prefix length.
    ///
    /// # Errors
    ///
    /// Returns an error for an excessive proposal, an accepted prefix beyond
    /// the proposal, or identity encoding failure. A zero-token proposal is a
    /// valid completed boundary when the accepted count is also zero.
    pub fn from_tokens(
        plan: &SpeculationPlanV1,
        plan_identity: Digest,
        boundary: u64,
        proposed_tokens: &[TokenId],
        accepted: u32,
        telemetry: Vec<SpeculationTelemetryResolutionV1>,
    ) -> Result<Self, CoreError> {
        let proposed = u32::try_from(proposed_tokens.len()).map_err(|_| {
            CoreError::invalid("speculation boundary", "proposal length exceeds u32")
        })?;
        if proposed > plan.maximum_draft_tokens || accepted > proposed {
            return Err(CoreError::invalid(
                "speculation boundary",
                "proposal or accepted-prefix count is invalid",
            ));
        }
        let rejected = proposed
            .checked_sub(accepted)
            .ok_or_else(|| CoreError::invalid("speculation boundary", "count underflowed"))?;
        let receipt = Self {
            plan: plan_identity,
            boundary,
            proposal: Digest::of_serializable(
                "speculation-proposal-token-ids-v1",
                proposed_tokens,
            )?,
            proposed,
            accepted,
            rejected,
            telemetry,
        };
        receipt.validate_for(plan)?;
        Ok(receipt)
    }

    /// Validates boundary accounting against a plan.
    ///
    /// The caller must first obtain the supplied plan identity from
    /// [`SpeculationPlanV1::digest_for`].
    ///
    /// # Errors
    ///
    /// Returns an error for mismatched lineage, impossible counts, excessive
    /// telemetry, or unresolved provisional dispositions.
    pub fn validate_for(&self, plan: &SpeculationPlanV1) -> Result<(), CoreError> {
        if self.plan != Digest::of_serializable("speculation-plan-v1", plan)?
            || self.proposed > plan.maximum_draft_tokens
            || self.accepted > self.proposed
            || self.rejected != self.proposed - self.accepted
            || self.telemetry.len() > MAX_SPECULATION_TELEMETRY_RESOLUTIONS
        {
            return Err(CoreError::invalid(
                "speculation boundary receipt",
                "plan lineage, counts, or telemetry bounds are invalid",
            ));
        }
        for resolution in &self.telemetry {
            resolution.validate()?;
        }
        Ok(())
    }

    /// Returns the stable completed-boundary identity.
    ///
    /// # Errors
    ///
    /// Returns a validation or serialization error.
    pub fn digest_for(&self, plan: &SpeculationPlanV1) -> Result<Digest, CoreError> {
        self.validate_for(plan)?;
        Digest::of_serializable("speculation-boundary-receipt-v1", self)
    }
}

/// Aggregate proposal and target-acceptance accounting.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculationReceiptV1 {
    /// Exact speculation-plan identity.
    pub plan: Digest,
    /// Ordered completed-boundary identities.
    pub boundaries: Vec<Digest>,
    /// Total proposed tokens.
    pub proposed: u64,
    /// Total target-accepted proposal tokens.
    pub accepted: u64,
    /// Total rejected proposal tokens.
    pub rejected: u64,
}

impl SpeculationReceiptV1 {
    /// Builds aggregate accounting from exact ordered boundary receipts.
    ///
    /// # Errors
    ///
    /// Returns an error for excessive boundaries, non-contiguous indices,
    /// mismatched plans, arithmetic overflow, or malformed boundary
    /// accounting. An operation that terminates before its first proposal
    /// boundary has valid zeroed aggregate accounting.
    pub fn from_boundaries(
        plan: &SpeculationPlanV1,
        boundaries: &[SpeculationBoundaryReceiptV1],
    ) -> Result<Self, CoreError> {
        if boundaries.len() > MAX_SPECULATION_BOUNDARIES {
            return Err(CoreError::invalid(
                "speculation receipt",
                "boundary count exceeds the supported bound",
            ));
        }
        let plan_identity = Digest::of_serializable("speculation-plan-v1", plan)?;
        let mut identities = Vec::with_capacity(boundaries.len());
        let mut proposed = 0_u64;
        let mut accepted = 0_u64;
        let mut rejected = 0_u64;
        for (index, boundary) in boundaries.iter().enumerate() {
            let expected = u64::try_from(index).map_err(|_| {
                CoreError::invalid("speculation receipt", "boundary index exceeds u64")
            })?;
            if boundary.boundary != expected || boundary.plan != plan_identity {
                return Err(CoreError::invalid(
                    "speculation receipt",
                    "boundaries must be contiguous and plan-bound",
                ));
            }
            identities.push(boundary.digest_for(plan)?);
            proposed = proposed
                .checked_add(u64::from(boundary.proposed))
                .ok_or_else(|| {
                    CoreError::invalid("speculation receipt", "proposal count overflowed")
                })?;
            accepted = accepted
                .checked_add(u64::from(boundary.accepted))
                .ok_or_else(|| {
                    CoreError::invalid("speculation receipt", "acceptance count overflowed")
                })?;
            rejected = rejected
                .checked_add(u64::from(boundary.rejected))
                .ok_or_else(|| {
                    CoreError::invalid("speculation receipt", "rejection count overflowed")
                })?;
        }
        Ok(Self {
            plan: plan_identity,
            boundaries: identities,
            proposed,
            accepted,
            rejected,
        })
    }

    /// Validates aggregate accounting against exact boundary receipts.
    ///
    /// # Errors
    ///
    /// Returns an error when recomputed aggregate evidence differs.
    pub fn digest_for(
        &self,
        plan: &SpeculationPlanV1,
        boundaries: &[SpeculationBoundaryReceiptV1],
    ) -> Result<Digest, CoreError> {
        if *self != Self::from_boundaries(plan, boundaries)? {
            return Err(CoreError::invalid(
                "speculation receipt",
                "aggregate evidence does not match its boundary receipts",
            ));
        }
        Digest::of_serializable("speculation-receipt-v1", self)
    }
}

/// Serializable evidence for one quiescent speculative checkpoint envelope.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpeculativeCheckpointReceiptV1 {
    /// Exact aggregate text-mechanics plan identity.
    pub mechanics: Digest,
    /// Exact speculation-plan identity.
    pub speculation: Digest,
    /// Exact target causal-state checkpoint receipt.
    pub target_state: Digest,
    /// Exact draft causal-state checkpoint receipt.
    pub draft_state: Digest,
    /// Identity of opaque speculative implementation state.
    pub implementation_state: Digest,
    /// Opaque speculative implementation-state byte count.
    pub implementation_state_bytes: u64,
    /// Target sampler clone lineage identity.
    pub target_sampler_lineage: Digest,
    /// Exact admitted target token-history identity.
    pub admitted_history: Digest,
    /// Next target causal position.
    pub position: u64,
    /// Number of completely resolved speculation boundaries.
    pub completed_boundaries: u64,
    /// Active target activation-program identity.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub target_activation: Option<Digest>,
    /// Active draft activation-program identity.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub draft_activation: Option<Digest>,
    /// Parent checkpoint identity for a restored branch.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub parent: Option<Digest>,
}

impl SpeculativeCheckpointReceiptV1 {
    /// Validates quiescent checkpoint accounting and returns its identity.
    ///
    /// # Errors
    ///
    /// Returns an error for zero/excessive implementation state, activation
    /// lineage inconsistent with the speculation plan, or serialization
    /// failure.
    pub fn digest_for(&self, plan: &SpeculationPlanV1) -> Result<Digest, CoreError> {
        if self.speculation != Digest::of_serializable("speculation-plan-v1", plan)?
            || self.implementation_state_bytes == 0
            || self.implementation_state_bytes > MAX_SPECULATION_STATE_BYTES
            || self.target_activation != plan.activation.target_program().cloned()
            || self.draft_activation != plan.activation.draft_program().cloned()
        {
            return Err(CoreError::invalid(
                "speculative checkpoint receipt",
                "state bounds or plan lineage are invalid",
            ));
        }
        Digest::of_serializable("speculative-checkpoint-receipt-v1", self)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn topology(model: &[u8], mtp: bool) -> TextModelTopologyV1 {
        TextModelTopologyV1 {
            model: Digest::of_bytes("test-model", model),
            backend: Digest::of_bytes("test-backend", b"one"),
            architecture_implementation: Digest::of_bytes("test-architecture", b"one"),
            layers: 4,
            embedding_width: 8,
            experts: None,
            experts_used: None,
            nextn_layers: u32::from(mtp),
            supported_speculation: if mtp {
                vec![
                    TextSpeculativeMechanismV1::Mtp,
                    TextSpeculativeMechanismV1::Eagle3,
                ]
            } else {
                vec![TextSpeculativeMechanismV1::Eagle3]
            },
        }
    }

    fn mtp_plan(topology: &TextModelTopologyV1) -> SpeculationPlanV1 {
        SpeculationPlanV1 {
            target_model: topology.model.clone(),
            target_topology: topology.digest().unwrap(),
            draft_model: topology.model.clone(),
            draft_topology: topology.digest().unwrap(),
            implementation: Digest::of_bytes("test-speculation", b"one"),
            mechanism: TextSpeculativeMechanismV1::Mtp,
            sequences: 1,
            maximum_draft_tokens: 4,
            minimum_draft_tokens: 0,
            probability_floor_bits: 0.0_f32.to_bits(),
            activation: SpeculationActivationPolicyV1::None,
        }
    }

    #[test]
    fn mtp_requires_one_exact_model_topology() {
        let target = topology(b"target", true);
        let mut plan = mtp_plan(&target);
        assert!(plan.digest_for(&target, &target).is_ok());

        let draft = topology(b"draft", true);
        plan.draft_model = draft.model.clone();
        plan.draft_topology = draft.digest().unwrap();
        assert!(plan.digest_for(&target, &draft).is_err());
    }

    #[test]
    fn eagle_requires_a_separate_draft_identity() {
        let target = topology(b"target", true);
        let draft = topology(b"draft", false);
        let plan = SpeculationPlanV1 {
            target_model: target.model.clone(),
            target_topology: target.digest().unwrap(),
            draft_model: draft.model.clone(),
            draft_topology: draft.digest().unwrap(),
            implementation: Digest::of_bytes("test-speculation", b"one"),
            mechanism: TextSpeculativeMechanismV1::Eagle3,
            sequences: 1,
            maximum_draft_tokens: 4,
            minimum_draft_tokens: 0,
            probability_floor_bits: 0.1_f32.to_bits(),
            activation: SpeculationActivationPolicyV1::None,
        };
        assert!(plan.digest_for(&target, &draft).is_ok());
    }

    #[test]
    fn boundaries_preserve_zero_partial_and_complete_acceptance() {
        let topology = topology(b"target", true);
        let plan = mtp_plan(&topology);
        let plan_identity = plan.digest_for(&topology, &topology).unwrap();
        let proposed = [
            TokenId::new(1).unwrap(),
            TokenId::new(2).unwrap(),
            TokenId::new(3).unwrap(),
        ];
        let boundaries = [0_u32, 2, 3]
            .into_iter()
            .enumerate()
            .map(|(index, accepted)| {
                SpeculationBoundaryReceiptV1::from_tokens(
                    &plan,
                    plan_identity.clone(),
                    u64::try_from(index).unwrap(),
                    &proposed,
                    accepted,
                    Vec::new(),
                )
                .unwrap()
            })
            .collect::<Vec<_>>();
        let receipt = SpeculationReceiptV1::from_boundaries(&plan, &boundaries).unwrap();
        assert_eq!(receipt.proposed, 9);
        assert_eq!(receipt.accepted, 5);
        assert_eq!(receipt.rejected, 4);
        assert!(receipt.digest_for(&plan, &boundaries).is_ok());
    }

    #[test]
    fn pre_boundary_terminal_selection_has_zeroed_speculation_accounting() {
        let topology = topology(b"target", true);
        let plan = mtp_plan(&topology);
        let receipt = SpeculationReceiptV1::from_boundaries(&plan, &[]).unwrap();
        assert!(receipt.boundaries.is_empty());
        assert_eq!(
            (receipt.proposed, receipt.accepted, receipt.rejected),
            (0, 0, 0)
        );
        assert!(receipt.digest_for(&plan, &[]).is_ok());
    }

    #[test]
    fn provisional_telemetry_requires_a_final_disposition() {
        let resolution = SpeculationTelemetryResolutionV1 {
            provisional: Digest::of_bytes("test-provisional", b"one"),
            disposition: ActivationTelemetryDispositionV1::Provisional,
            resolved: Digest::of_bytes("test-resolved", b"one"),
        };
        assert!(resolution.validate().is_err());
    }
}