Skip to main content

qualia_vision/
generator.rs

1//! Swarm G — native image generation ABI (Phase 8).
2//!
3//! Deterministic seeded generator using pure-Rust noise + iterative smooth/refine.
4//! **Honest scope:** this is a native, licence-clear reference generator for the
5//! ABI, receipts, and media-store path — not a foundation DiT/UNet checkpoint.
6//! Swap the `step` body for Forge-backed denoiser weights when a licence-approved
7//! model is selected (G0 audit). No Python / ComfyUI.
8
9use crate::semantic::{media_digest, q_hash, MediaDigest, VisionQuin};
10use crate::types::VisionError;
11
12pub const GENERATOR_MODEL_ID: &str = "qualia-vision-native-generator-ref-v1";
13pub const P_GENERATED_IMAGE: &str = "https://ns.webizen.org/q42/generatedImage";
14pub const P_GEN_SEED: &str = "https://ns.webizen.org/q42/generationSeed";
15pub const P_GEN_PROMPT: &str = "https://ns.webizen.org/q42/generationPromptHash";
16pub const CTX_GENERATION: &str = "https://ns.webizen.org/q42/vision-generation";
17
18/// Immutable generation receipt for Q42 / sidecars.
19#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20pub struct GenerationReceipt {
21    pub model_hash: u64,
22    pub seed: u64,
23    pub steps: u32,
24    pub width: u32,
25    pub height: u32,
26    pub prompt_hash: u64,
27    pub output_digest: MediaDigest,
28    /// True for the built-in reference path (not a third-party foundation model).
29    pub is_reference_generator: bool,
30    /// Shared media timeline slot (ms or frame base) for cross-modal join with audio.
31    pub media_time_ms: u64,
32}
33
34/// Cooperative cancel flag (generation is cold path; checked between steps).
35#[derive(Debug, Clone, Copy, Default)]
36pub struct CancelFlag {
37    pub cancelled: bool,
38}
39
40impl CancelFlag {
41    /// Creates a new instance.
42    pub fn new() -> Self {
43        Self { cancelled: false }
44    }
45    /// Cancels.
46    pub fn cancel(&mut self) {
47        self.cancelled = true;
48    }
49}
50
51/// Native image generator session (cold construct; hot path is `generate_rgb8`).
52#[derive(Debug, Clone)]
53pub struct NativeImageGenerator {
54    pub model_hash: u64,
55    pub is_reference: bool,
56}
57
58impl Default for NativeImageGenerator {
59    fn default() -> Self {
60        Self::new()
61    }
62}
63
64impl NativeImageGenerator {
65    /// Creates a new instance.
66    pub fn new() -> Self {
67        Self {
68            model_hash: q_hash(GENERATOR_MODEL_ID),
69            is_reference: true,
70        }
71    }
72
73    /// Generate RGB8 into `out` (len ≥ w*h*3). Prompt is hashed only (no string retained).
74    pub fn generate_rgb8(
75        &self,
76        prompt: &str,
77        seed: u64,
78        steps: u32,
79        width: u32,
80        height: u32,
81        out: &mut [u8],
82    ) -> Result<GenerationReceipt, VisionError> {
83        self.generate_rgb8_cancellable(prompt, seed, steps, width, height, out, None, 0)
84    }
85
86    /// Same as `generate_rgb8` with optional cancel between steps and media timeline stamp.
87    pub fn generate_rgb8_cancellable(
88        &self,
89        prompt: &str,
90        seed: u64,
91        steps: u32,
92        width: u32,
93        height: u32,
94        out: &mut [u8],
95        cancel: Option<&CancelFlag>,
96        media_time_ms: u64,
97    ) -> Result<GenerationReceipt, VisionError> {
98        let w = width.max(1);
99        let h = height.max(1);
100        let need = (w as usize).saturating_mul(h as usize).saturating_mul(3);
101        if out.len() < need {
102            return Err(VisionError::OutputBufferTooSmall);
103        }
104        let steps = steps.clamp(1, 64);
105        let prompt_hash = q_hash(prompt);
106        let state = seed ^ prompt_hash ^ self.model_hash;
107
108        let n = (w * h) as usize;
109        let mut rch = vec![0.0f32; n];
110        let mut gch = vec![0.0f32; n];
111        let mut bch = vec![0.0f32; n];
112        // Multi-octave value noise (still deterministic reference, richer structure).
113        for i in 0..n {
114            let x = (i % w as usize) as f32 / w as f32;
115            let y = (i / w as usize) as f32 / h as f32;
116            let (nr, ng, nb) = octave_noise(x, y, state);
117            rch[i] = nr;
118            gch[i] = ng;
119            bch[i] = nb;
120        }
121
122        let br = ((prompt_hash) & 0xFF) as f32 / 255.0 * 2.0 - 1.0;
123        let bg = ((prompt_hash >> 8) & 0xFF) as f32 / 255.0 * 2.0 - 1.0;
124        let bb = ((prompt_hash >> 16) & 0xFF) as f32 / 255.0 * 2.0 - 1.0;
125
126        let mut scratch = vec![0.0f32; n];
127        for step in 0..steps {
128            if cancel.map(|c| c.cancelled).unwrap_or(false) {
129                // Leave no partial claim: zero output and fail closed.
130                out[..need].fill(0);
131                return Err(VisionError::BackendUnavailable);
132            }
133            let t = (step + 1) as f32 / steps as f32;
134            blur3_into(&rch, w, h, &mut scratch);
135            rch.copy_from_slice(&scratch);
136            blur3_into(&gch, w, h, &mut scratch);
137            gch.copy_from_slice(&scratch);
138            blur3_into(&bch, w, h, &mut scratch);
139            bch.copy_from_slice(&scratch);
140            for i in 0..n {
141                rch[i] = rch[i] * (1.0 - 0.18 * t) + br * 0.18 * t;
142                gch[i] = gch[i] * (1.0 - 0.18 * t) + bg * 0.18 * t;
143                bch[i] = bch[i] * (1.0 - 0.18 * t) + bb * 0.18 * t;
144            }
145        }
146
147        for i in 0..n {
148            out[i * 3] = ((rch[i].tanh() * 0.5 + 0.5) * 255.0).clamp(0.0, 255.0) as u8;
149            out[i * 3 + 1] = ((gch[i].tanh() * 0.5 + 0.5) * 255.0).clamp(0.0, 255.0) as u8;
150            out[i * 3 + 2] = ((bch[i].tanh() * 0.5 + 0.5) * 255.0).clamp(0.0, 255.0) as u8;
151        }
152
153        let dig = media_digest(&out[..need]);
154        Ok(GenerationReceipt {
155            model_hash: self.model_hash,
156            seed,
157            steps,
158            width: w,
159            height: h,
160            prompt_hash,
161            output_digest: dig,
162            is_reference_generator: self.is_reference,
163            media_time_ms,
164        })
165    }
166}
167
168/// Compile generation receipt into epistemic quins (media --generated--> model, seed, prompt).
169pub fn compile_generation_receipt_quins(
170    receipt: &GenerationReceipt,
171    out: &mut [VisionQuin],
172) -> usize {
173    if out.len() < 3 {
174        return 0;
175    }
176    let media = receipt.output_digest.hash;
177    let ctx = q_hash(CTX_GENERATION) ^ receipt.model_hash;
178    out[0] = VisionQuin::with_parity(
179        media,
180        q_hash(P_GENERATED_IMAGE),
181        receipt.model_hash,
182        ctx,
183        receipt.media_time_ms,
184    );
185    out[1] = VisionQuin::with_parity(
186        media,
187        q_hash(P_GEN_SEED),
188        receipt.seed,
189        ctx,
190        receipt.steps as u64,
191    );
192    out[2] = VisionQuin::with_parity(
193        media,
194        q_hash(P_GEN_PROMPT),
195        receipt.prompt_hash,
196        ctx,
197        ((receipt.width as u64) << 32) | receipt.height as u64,
198    );
199    3
200}
201
202fn octave_noise(x: f32, y: f32, seed: u64) -> (f32, f32, f32) {
203    let mut amp = 1.0f32;
204    let mut freq = 1.0f32;
205    let mut r = 0.0f32;
206    let mut g = 0.0f32;
207    let mut b = 0.0f32;
208    let mut norm = 0.0f32;
209    for o in 0..4u64 {
210        let s = splitmix64(seed.wrapping_add(o * 0x9E37));
211        let n = value_noise(x * freq, y * freq, s);
212        r += n * amp;
213        g += value_noise(x * freq + 17.0, y * freq, splitmix64(s)) * amp;
214        b += value_noise(x * freq, y * freq + 31.0, splitmix64(s ^ 1)) * amp;
215        norm += amp;
216        amp *= 0.5;
217        freq *= 2.0;
218    }
219    let inv = 1.0 / norm.max(1e-6);
220    (r * inv, g * inv, b * inv)
221}
222
223fn value_noise(x: f32, y: f32, seed: u64) -> f32 {
224    let x0 = x.floor() as i32;
225    let y0 = y.floor() as i32;
226    let fx = x - x0 as f32;
227    let fy = y - y0 as f32;
228    let sx = fx * fx * (3.0 - 2.0 * fx);
229    let sy = fy * fy * (3.0 - 2.0 * fy);
230    let n00 = hash2(x0, y0, seed);
231    let n10 = hash2(x0 + 1, y0, seed);
232    let n01 = hash2(x0, y0 + 1, seed);
233    let n11 = hash2(x0 + 1, y0 + 1, seed);
234    let ix0 = n00 * (1.0 - sx) + n10 * sx;
235    let ix1 = n01 * (1.0 - sx) + n11 * sx;
236    ix0 * (1.0 - sy) + ix1 * sy
237}
238
239fn hash2(x: i32, y: i32, seed: u64) -> f32 {
240    let mut h =
241        seed ^ ((x as u64).wrapping_mul(0x85eb_ca6b)) ^ ((y as u64).wrapping_mul(0xc2b2_ae35));
242    h = splitmix64(h);
243    (h as f32 / u64::MAX as f32) * 2.0 - 1.0
244}
245
246#[inline]
247fn splitmix64(mut x: u64) -> u64 {
248    x = x.wrapping_add(0x9e37_79b9_7f4a_7c15);
249    let mut z = x;
250    z = (z ^ (z >> 30)).wrapping_mul(0xbf58_476d_1ce4_e5b9);
251    z = (z ^ (z >> 27)).wrapping_mul(0x94d0_49bb_1331_11eb);
252    z ^ (z >> 31)
253}
254
255fn blur3_into(src: &[f32], w: u32, h: u32, dst: &mut [f32]) {
256    let w = w as usize;
257    let h = h as usize;
258    for y in 0..h {
259        for x in 0..w {
260            let mut s = 0.0f32;
261            let mut c = 0.0f32;
262            for dy in -1i32..=1 {
263                for dx in -1i32..=1 {
264                    let xx = x as i32 + dx;
265                    let yy = y as i32 + dy;
266                    if xx >= 0 && yy >= 0 && (xx as usize) < w && (yy as usize) < h {
267                        s += src[yy as usize * w + xx as usize];
268                        c += 1.0;
269                    }
270                }
271            }
272            dst[y * w + x] = s / c.max(1.0);
273        }
274    }
275}
276
277#[cfg(test)]
278mod tests {
279    use super::*;
280
281    #[test]
282    fn seed_deterministic() {
283        let g = NativeImageGenerator::new();
284        let mut a = vec![0u8; 16 * 16 * 3];
285        let mut b = vec![0u8; 16 * 16 * 3];
286        let ra = g
287            .generate_rgb8("teal field", 99, 4, 16, 16, &mut a)
288            .unwrap();
289        let rb = g
290            .generate_rgb8("teal field", 99, 4, 16, 16, &mut b)
291            .unwrap();
292        assert_eq!(a, b);
293        assert_eq!(ra.output_digest, rb.output_digest);
294        assert!(ra.is_reference_generator);
295    }
296
297    #[test]
298    fn different_seeds_differ() {
299        let g = NativeImageGenerator::new();
300        let mut a = vec![0u8; 8 * 8 * 3];
301        let mut b = vec![0u8; 8 * 8 * 3];
302        g.generate_rgb8("x", 1, 2, 8, 8, &mut a).unwrap();
303        g.generate_rgb8("x", 2, 2, 8, 8, &mut b).unwrap();
304        assert_ne!(a, b);
305    }
306
307    #[test]
308    fn cancel_fails_closed() {
309        let g = NativeImageGenerator::new();
310        let mut out = vec![0u8; 8 * 8 * 3];
311        let mut c = CancelFlag::new();
312        c.cancel();
313        let r = g.generate_rgb8_cancellable("x", 1, 8, 8, 8, &mut out, Some(&c), 0);
314        assert!(r.is_err());
315        assert!(out.iter().all(|&b| b == 0));
316    }
317
318    #[test]
319    fn receipt_quins() {
320        let g = NativeImageGenerator::new();
321        let mut out = vec![0u8; 8 * 8 * 3];
322        let rec = g.generate_rgb8("hi", 3, 2, 8, 8, &mut out).unwrap();
323        let mut q = [VisionQuin::with_parity(0, 0, 0, 0, 0); 4];
324        let n = compile_generation_receipt_quins(&rec, &mut q);
325        assert_eq!(n, 3);
326        assert_eq!(q[0].subject, rec.output_digest.hash);
327    }
328}