nx_synthesis_engine.nx source
↩ module page · 177 lines · 9260 B
1// nx_synthesis_engine.nx -- meta-level signal generation across all domains.
2//
3// module: nishi-core.perception.synthesis_engine
4// depends: nishi-core.perception.profile + nishi-core.perception.transducer_characterizer +
5// nishi-core.io.syscalls
6// disk_kb: 5
7// capability: PERCEPTION
8// wired_status: PARTIAL_WIRED
9//
10// MISSING_CAPABILITIES:
11// - LOG_SWEPT_SINE_GENERATOR (Farina 2000 method; needs nx_sincos or
12// CORDIC for argument-bounded sine; queued)
13// - MLS_SEQUENCE_GENERATOR (linear-feedback shift register; trivial when
14// PARTIAL → FULLY)
15// - PINK_NOISE_GENERATOR (Voss-McCartney algorithm or filtered white)
16// - GRANULAR_SYNTH (overlap-add of small grains from source sample with
17// pitch/duration/position jitter; THE primitive that makes prey-spec
18// audio never repeat for habituation defeat)
19// - BREATH_DRIVEN_RNG (low-frequency modulator that mimics biological
20// breath cycles; drives grain-rate and amplitude envelope of prey
21// vocalizations)
22// - VISUAL_TEST_PATTERN (gradient, checkerboard, color bars for visual
23// transducer characterization)
24// - GAS_BOLUS_PROFILE (controlled-concentration injection profile for
25// scent cartridge characterization)
26//
27// license_tier: PUBLIC_NISHI_SUBSTRATE
28// genealogy_id: feedback-substrate-primitives-meta-not-one-off_2026 +
29// feedback-multi-species-perceptual-substrate-not-anthropocentric_2026 +
30// farina_2000_swept_sine_room_acoustics_aes +
31// schroeder_1979_mls_measurement +
32// voss_1976_one_over_f_noise +
33// roads_1988_granular_synthesis +
34// feedback-build-intelligence-never-strip-features
35//
36// Per cardinals [[feedback-substrate-primitives-meta-not-one-off]] and
37// [[feedback-multi-species-perceptual-substrate-not-anthropocentric]]:
38// THIS primitive generates any signal needed by the substrate — stimulus
39// signals for nx_transducer_characterizer, prey-spec audio for the dog toy,
40// calming audio for separation anxiety, deterrence signals for humane pest
41// control, test patterns for visual transducer characterization, controlled
42// gas-injection profiles for scent cartridge characterization.
43//
44// Reuse set served by this single primitive:
45// - Stimulus generation for nx_transducer_characterizer (every kind)
46// - Prey-spec audio for the dog toy ([[project-prey-spec-dog-toy]])
47// - Granular synth from real-prey samples (never-repeats, defeats
48// habituation per [[feedback-multi-species-perceptual-substrate-not-anthropocentric]])
49// - Calming audio for separation anxiety
50// - Working-dog training cues
51// - Humane pest deterrence (species-specific aversive signals)
52// - Conservation acoustic playback (call-back surveys)
53// - Visual test patterns for camera + display characterization
54// - Scent cartridge dispense profiles for characterization
55//
56// The granular-synth + breath-driven-RNG combo is the critical primitive
57// for the dog toy: no two playbacks repeat exactly; substrate generates
58// fresh micro-variations from real-prey source samples; defeats the
59// classical-conditioning habituation that kills every existing pet toy
60// audio after a few exposures.
61
62import "nx_syscalls.nx"
63import "nx_perceptual_profile.nx"
64import "nx_transducer_characterizer.nx"
65
66// ===== Generation verdicts ========================================
67
68const NX_SYN_OK: i64 = 0
69const NX_SYN_FAIL_BAD_STIMULUS: i64 = 1
70const NX_SYN_FAIL_BAD_DOMAIN: i64 = 2
71const NX_SYN_FAIL_BAD_PROFILE: i64 = 3
72const NX_SYN_FAIL_BUFFER_TOO_SMALL: i64 = 4
73const NX_SYN_FAIL_DEPENDENCY_MISSING: i64 = 5 // PARTIAL_WIRED default
74const NX_SYN_FAIL_SOURCE_SAMPLE_MISSING: i64 = 6 // granular synth needs source
75
76func nx_syn_verdict_name(v: i64) -> *u8 {
77 if v == NX_SYN_OK { return "OK" }
78 if v == NX_SYN_FAIL_BAD_STIMULUS { return "FAIL_BAD_STIMULUS" }
79 if v == NX_SYN_FAIL_BAD_DOMAIN { return "FAIL_BAD_DOMAIN" }
80 if v == NX_SYN_FAIL_BAD_PROFILE { return "FAIL_BAD_PROFILE" }
81 if v == NX_SYN_FAIL_BUFFER_TOO_SMALL { return "FAIL_BUFFER_TOO_SMALL" }
82 if v == NX_SYN_FAIL_DEPENDENCY_MISSING { return "FAIL_DEPENDENCY_MISSING" }
83 if v == NX_SYN_FAIL_SOURCE_SAMPLE_MISSING { return "FAIL_SOURCE_SAMPLE_MISSING" }
84 return "UNKNOWN_VERDICT"
85}
86
87// ===== Granular synth params struct ===============================
88//
89// Per [[feedback-nishilang-16-arg-function-limit]]: bundle grain-cloud
90// configuration in a struct. Defaults set for prey-vocalization use case;
91// pest deterrence + calming audio override per use case.
92
93struct NxSynGranularParams {
94 grain_duration_ms_min: i64
95 grain_duration_ms_max: i64
96 grain_position_jitter_pct: i64 // 0..100, randomization of source-sample read position
97 grain_pitch_jitter_cents: i64 // 0..1200, ± randomization in cents
98 grain_amplitude_jitter_pct: i64 // 0..100
99 grain_overlap_pct: i64 // 0..200 (>100 = denser cloud)
100 breath_cycle_hz_x10: i64 // tenth-Hz, e.g., 4 = 0.4 Hz (typical prey breath)
101 breath_amplitude_depth_pct: i64 // 0..100
102 source_sample_hash_ptr: *u8
103 source_sample_hash_len: i64
104}
105
106// ===== Top-level entry stubs ======================================
107
108// nx_synthesis_generate_stimulus -- generate a characterization stimulus.
109// Used by nx_transducer_characterizer to drive the swept-sine / MLS /
110// pink noise / step / pressure-ramp / etc. against the transducer.
111
112func nx_synthesis_generate_stimulus(stimulus: i64, sample_rate_hz: i64,
113 freq_lo_hz: i64, freq_hi_hz: i64,
114 duration_ms: i64,
115 out_buf_ptr: *u8, out_buf_cap: i64) -> i64 {
116 if stimulus < NX_TXR_STIM_LOG_SWEPT_SINE { return NX_SYN_FAIL_BAD_STIMULUS }
117 if stimulus > NX_TXR_STIM_PRESSURE_RAMP { return NX_SYN_FAIL_BAD_STIMULUS }
118 if sample_rate_hz <= 0 { return NX_SYN_FAIL_BAD_STIMULUS }
119 if freq_lo_hz < 0 { return NX_SYN_FAIL_BAD_STIMULUS }
120 if freq_hi_hz <= freq_lo_hz { return NX_SYN_FAIL_BAD_STIMULUS }
121 if duration_ms <= 0 { return NX_SYN_FAIL_BAD_STIMULUS }
122 if out_buf_cap <= 0 { return NX_SYN_FAIL_BUFFER_TOO_SMALL }
123 // PARTIAL_WIRED: stimulus-specific generators queued.
124 return NX_SYN_FAIL_DEPENDENCY_MISSING
125}
126
127// nx_synthesis_generate_prey -- generate prey-spec audio for a target
128// species via granular synth + breath-driven RNG. Source sample loaded
129// from nx_provenance_curve_store (sample-kind entry) by hash.
130
131func nx_synthesis_generate_prey(target_profile: i64,
132 params_ptr: *NxSynGranularParams,
133 sample_rate_hz: i64, duration_ms: i64,
134 out_buf_ptr: *u8, out_buf_cap: i64) -> i64 {
135 if nx_perceptual_profile_is_valid(target_profile) == 0 { return NX_SYN_FAIL_BAD_PROFILE }
136 if sample_rate_hz <= 0 { return NX_SYN_FAIL_BAD_STIMULUS }
137 if duration_ms <= 0 { return NX_SYN_FAIL_BAD_STIMULUS }
138 if out_buf_cap <= 0 { return NX_SYN_FAIL_BUFFER_TOO_SMALL }
139 return NX_SYN_FAIL_DEPENDENCY_MISSING
140}
141
142// nx_synthesis_default_granular_params_for_profile -- substrate-recommended
143// defaults per species. Vizsla upland-bird prey has different grain shape
144// than terrier vermin prey; substrate ships sensible defaults.
145
146func nx_synthesis_default_granular_params_for_profile(profile: i64,
147 out_params_ptr: *NxSynGranularParams) -> i64 {
148 if nx_perceptual_profile_is_valid(profile) == 0 { return 0 }
149 // PARTIAL_WIRED: per-profile default lookup queued.
150 // Future: NX_PERCEPT_DOG_VIZSLA → upland-bird wing-flutter grain shape;
151 // NX_PERCEPT_DOG_TERRIER → vermin ultrasonic squeak grain shape; etc.
152 return 0
153}
154
155// nx_synthesis_generate_test_pattern -- visual transducer characterization.
156// Pattern type encoded in `stimulus` param (NX_TXR_STIM_TEST_PATTERN).
157
158func nx_synthesis_generate_test_pattern(width_px: i64, height_px: i64,
159 channels: i64, bit_depth: i64,
160 pattern_seed: i64,
161 out_buf_ptr: *u8, out_buf_cap: i64) -> i64 {
162 if width_px <= 0 { return NX_SYN_FAIL_BAD_STIMULUS }
163 if height_px <= 0 { return NX_SYN_FAIL_BAD_STIMULUS }
164 if channels <= 0 { return NX_SYN_FAIL_BAD_STIMULUS }
165 if channels > 4 { return NX_SYN_FAIL_BAD_STIMULUS } // RGBA max for now
166 if bit_depth != 8 && bit_depth != 10 && bit_depth != 12 && bit_depth != 16 {
167 return NX_SYN_FAIL_BAD_STIMULUS
168 }
169 if out_buf_cap <= 0 { return NX_SYN_FAIL_BUFFER_TOO_SMALL }
170 return NX_SYN_FAIL_DEPENDENCY_MISSING
171}
172
173// nx_synthesis_get_last_verdict -- inspector.
174
175func nx_synthesis_get_last_verdict() -> i64 {
176 return NX_SYN_FAIL_DEPENDENCY_MISSING
177}