Skip to main content

qualia_core_db/services/swarm/
job.rs

1//! The job envelope: a deterministic, content-addressed specification of work plus
2//! its result. "Deterministic" matters — a job is reproducible from its `(kind, input,
3//! seed)`, so any node can re-derive or verify it, and a paid job's outcome is
4//! auditable rather than taken on trust.
5
6use crate::solvers::learning::kg_embedding::{EmbeddingTable, TrainConfig};
7
8/// The kind of work a job carries. Each maps to a kernel-class with a CPU reference
9/// (§13) and a verification strategy ([`super::verify()`]).
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub enum JobKind {
12    /// Dense matrix product `C = A·B` (kernel-class `DenseLinear`). Verified by
13    /// Freivalds' algorithm.
14    DenseLinearProduct,
15    /// Train a knowledge-graph embedding table (the heavy, run-once, affordability-
16    /// gated artifact). Verified by ranking reproduction on a held-out check set.
17    EmbeddingArtifact,
18}
19
20/// How a job is dispatched across the socially-defined network.
21#[derive(Debug, Clone, PartialEq, Eq)]
22pub enum JobMode {
23    /// The principal's own devices cooperate. No payment.
24    Personal,
25    /// Done with named peers (DID hashes). No payment.
26    Collaborative { peers: Vec<u64> },
27    /// Dispatched to a provider for payment — the solar-excess case.
28    Paid {
29        requester_did: u64,
30        provider_did: u64,
31        /// Agreed price in abstract minor units (µ-units), settled only on `Verified`.
32        price_micro_units: u64,
33    },
34}
35
36/// The actual work payload. Carries the real inputs (content-addressed into the job
37/// id), so an executor has everything it needs and a verifier can re-derive the answer.
38#[derive(Debug, Clone, PartialEq)]
39pub enum JobInput {
40    /// `A` is `m×k`, `B` is `k×n`, both row-major.
41    DenseLinearProduct {
42        m: usize,
43        k: usize,
44        n: usize,
45        a: Vec<f64>,
46        b: Vec<f64>,
47    },
48    /// Train an embedding over `triples`; `check` is the held-out set used to verify
49    /// the returned table actually learned (not just terminated).
50    EmbeddingArtifact {
51        triples: Vec<(usize, usize, usize)>,
52        n_entities: usize,
53        n_relations: usize,
54        cfg: TrainConfig,
55        check: Vec<(usize, usize, usize)>,
56    },
57}
58
59impl JobInput {
60    /// The kind tag.
61    pub fn kind(&self) -> JobKind {
62        match self {
63            JobInput::DenseLinearProduct { .. } => JobKind::DenseLinearProduct,
64            JobInput::EmbeddingArtifact { .. } => JobKind::EmbeddingArtifact,
65        }
66    }
67
68    /// True if the input is internally well-formed (dimensions consistent).
69    pub fn is_well_formed(&self) -> bool {
70        match self {
71            JobInput::DenseLinearProduct { m, k, n, a, b } => {
72                *m > 0 && *k > 0 && *n > 0 && a.len() == m * k && b.len() == k * n
73            }
74            JobInput::EmbeddingArtifact {
75                triples,
76                n_entities,
77                n_relations,
78                ..
79            } => {
80                !triples.is_empty()
81                    && *n_entities > 0
82                    && *n_relations > 0
83                    && triples
84                        .iter()
85                        .all(|&(h, r, t)| h < *n_entities && t < *n_entities && r < *n_relations)
86            }
87        }
88    }
89}
90
91/// The result an executor returns.
92#[derive(Debug, Clone, PartialEq)]
93pub enum JobResult {
94    DenseLinearProduct { c: Vec<f64> },
95    EmbeddingArtifact { table: EmbeddingTable },
96}
97
98impl JobResult {
99    /// The kind tag.
100    pub fn kind(&self) -> JobKind {
101        match self {
102            JobResult::DenseLinearProduct { .. } => JobKind::DenseLinearProduct,
103            JobResult::EmbeddingArtifact { .. } => JobKind::EmbeddingArtifact,
104        }
105    }
106}
107
108/// A full job: a content-addressed id, its dispatch mode, and the work payload.
109#[derive(Debug, Clone, PartialEq)]
110pub struct JobSpec {
111    /// Content id — a deterministic hash of `input`. Two identical jobs share an id.
112    pub id: u64,
113    pub mode: JobMode,
114    pub input: JobInput,
115}
116
117impl JobSpec {
118    /// Creates a default `JobSpec`.
119    pub fn new(mode: JobMode, input: JobInput) -> Self {
120        let id = content_id(&input);
121        Self { id, mode, input }
122    }
123
124    /// The kind tag.
125    pub fn kind(&self) -> JobKind {
126        self.input.kind()
127    }
128}
129
130/// Deterministic content id (FNV-1a over the structural bytes of the input). Stable
131/// across nodes — the basis for content-addressed dispatch and dedup.
132pub fn content_id(input: &JobInput) -> u64 {
133    let mut h: u64 = 0xcbf29ce484222325;
134    let byte = |b: u8, h: &mut u64| {
135        *h ^= b as u64;
136        *h = h.wrapping_mul(0x100000001b3);
137    };
138    let word = |w: u64, h: &mut u64| {
139        for b in w.to_le_bytes() {
140            byte(b, h);
141        }
142    };
143    match input {
144        JobInput::DenseLinearProduct { m, k, n, a, b } => {
145            byte(0x01, &mut h);
146            word(*m as u64, &mut h);
147            word(*k as u64, &mut h);
148            word(*n as u64, &mut h);
149            for &v in a.iter().chain(b.iter()) {
150                word(v.to_bits(), &mut h);
151            }
152        }
153        JobInput::EmbeddingArtifact {
154            triples,
155            n_entities,
156            n_relations,
157            cfg,
158            check,
159        } => {
160            byte(0x02, &mut h);
161            word(*n_entities as u64, &mut h);
162            word(*n_relations as u64, &mut h);
163            word(cfg.seed, &mut h);
164            word(cfg.rank as u64, &mut h);
165            word(cfg.epochs as u64, &mut h);
166            for &(a, b, c) in triples.iter().chain(check.iter()) {
167                word(a as u64, &mut h);
168                word(b as u64, &mut h);
169                word(c as u64, &mut h);
170            }
171        }
172    }
173    h
174}
175
176#[cfg(test)]
177mod tests {
178    use super::*;
179
180    fn dense() -> JobInput {
181        JobInput::DenseLinearProduct {
182            m: 2,
183            k: 2,
184            n: 2,
185            a: vec![1.0, 2.0, 3.0, 4.0],
186            b: vec![1.0, 0.0, 0.0, 1.0],
187        }
188    }
189
190    #[test]
191    fn content_id_is_deterministic_and_input_sensitive() {
192        let a = content_id(&dense());
193        let b = content_id(&dense());
194        assert_eq!(a, b, "same input → same id");
195        let mut other = dense();
196        if let JobInput::DenseLinearProduct { a, .. } = &mut other {
197            a[0] = 9.0;
198        }
199        assert_ne!(content_id(&other), a, "different input → different id");
200    }
201
202    #[test]
203    fn well_formedness_catches_bad_dims() {
204        assert!(dense().is_well_formed());
205        let bad = JobInput::DenseLinearProduct {
206            m: 2,
207            k: 2,
208            n: 2,
209            a: vec![1.0],
210            b: vec![1.0; 4],
211        };
212        assert!(!bad.is_well_formed());
213    }
214
215    #[test]
216    fn spec_carries_kind_and_id() {
217        let spec = JobSpec::new(JobMode::Personal, dense());
218        assert_eq!(spec.kind(), JobKind::DenseLinearProduct);
219        assert_eq!(spec.id, content_id(&dense()));
220    }
221}