nx_realism_score.nx source
↩ module page · 207 lines · 11117 B
1// nx_realism_score.nx -- end-to-end pipeline realism gate ("matches reality").
2//
3// module: nishi-core.perception.realism_score
4// depends: nishi-core.perception.profile + nishi-core.perception.judge +
5// nishi-core.perception.transducer_characterizer + nishi-core.perception.signal_compensator +
6// nishi-core.perception.codec_perceptual_grader + nishi-core.io.syscalls
7// disk_kb: 5
8// capability: PERCEPTION
9// wired_status: PARTIAL_WIRED
10//
11// MISSING_CAPABILITIES:
12// - SOURCE_REAL_CAPTURE_LOAD (load the calibrated reference recording
13// of the actual reality the pipeline is trying to reproduce)
14// - PIPELINE_ROUND_TRIP (source -> capture -> encode -> network -> decode
15// -> render -> physical transducer -> verification mic -> compare)
16// - DELTA_COMPUTE (frequency-domain + temporal-domain + spatial-domain
17// comparison; needs nx_fft + image-domain comparison primitives)
18// - PER_AXIS_REALISM_SCORE (decompose pipeline delta into perceptual axes
19// matching nx_perceptual_judge's 5-axis breakdown)
20// - LATENCY_DIMENSION (separate axis: was the pipeline FAST enough that
21// real-time interactivity preserved? composes with first-byte-of-call
22// latency from voice codec)
23//
24// license_tier: PUBLIC_NISHI_SUBSTRATE
25// genealogy_id: feedback-multi-species-perceptual-substrate-not-anthropocentric_2026 +
26// feedback-substrate-primitives-meta-not-one-off_2026 +
27// feedback-bits-up-exceed-never-match +
28// feedback-honest-perf-verdict-no-aspirational-claims +
29// feedback-end-to-end-bit-traceability-architecture +
30// nx_codec_perceptual_grader
31//
32// User directive 2026-05-20: "make sure our video and audio and all that
33// codecs are truly s class best in the world so they match reality both
34// on a video with a person in our nishifamily.com/video for speed and
35// quality and same for audio."
36//
37// THIS primitive measures whether the FULL pipeline (source capture ->
38// codec encode -> network transit -> codec decode -> compensator
39// pre-correction -> physical transducer -> air -> verification mic)
40// reproduces reality close enough that a declared target profile (e.g.,
41// HUMAN_NORMAL for nishifamily.com/video viewers) would perceive the
42// rendered output as effectively the same as being there.
43//
44// Distinct from nx_codec_perceptual_grader (which only grades the codec
45// in isolation): THIS primitive grades the ENTIRE deployed pipeline
46// including network jitter + transducer imperfection + room acoustics.
47// Same primitive grades nishifamily.com/video for HUMAN_NORMAL AND grades
48// the dog toy for DOG_VIZSLA AND grades a livestock-welfare deployment
49// for CATTLE.
50//
51// "S-class on nishifamily.com/video" becomes a measurable claim:
52// realism_score >= 90/100 against the reference reality capture,
53// across all 6 axes (5 perceptual + latency), for HUMAN_NORMAL profile,
54// reproducibly across N independent measurement sessions.
55
56import "nx_syscalls.nx"
57import "nx_perceptual_profile.nx"
58import "nx_perceptual_judge.nx"
59import "nx_transducer_characterizer.nx"
60import "nx_signal_compensator.nx"
61import "nx_codec_perceptual_grader.nx"
62
63// ===== Pipeline stage sealed enum =================================
64//
65// Names each stage where realism can be lost. Substrate decomposes total
66// realism delta into per-stage attribution so improvement effort goes
67// where it actually matters (not where it feels biggest).
68
69const NX_REAL_STAGE_SOURCE_CAPTURE: i64 = 1 // mic / camera input quality
70const NX_REAL_STAGE_PREPROCESSOR: i64 = 2 // gain / noise-suppression / framing
71const NX_REAL_STAGE_CODEC_ENCODE: i64 = 3 // compression loss
72const NX_REAL_STAGE_PACKETIZER: i64 = 4 // framing for transport
73const NX_REAL_STAGE_NETWORK_TRANSIT: i64 = 5 // jitter / loss / reorder
74const NX_REAL_STAGE_CODEC_DECODE: i64 = 6 // decompression
75const NX_REAL_STAGE_JITTER_BUFFER: i64 = 7 // smoothing
76const NX_REAL_STAGE_COMPENSATOR: i64 = 8 // signal compensator pre-correction
77const NX_REAL_STAGE_TRANSDUCER_RENDER: i64 = 9 // DAC + amp + speaker imperfections
78const NX_REAL_STAGE_ROOM_ACOUSTIC: i64 = 10 // reverb + reflections at listener
79const NX_REAL_STAGE_LISTENER_BIOLOGY: i64 = 11 // species-perceptual-profile gate
80
81func nx_real_stage_name(s: i64) -> *u8 {
82 if s == NX_REAL_STAGE_SOURCE_CAPTURE { return "SOURCE_CAPTURE" }
83 if s == NX_REAL_STAGE_PREPROCESSOR { return "PREPROCESSOR" }
84 if s == NX_REAL_STAGE_CODEC_ENCODE { return "CODEC_ENCODE" }
85 if s == NX_REAL_STAGE_PACKETIZER { return "PACKETIZER" }
86 if s == NX_REAL_STAGE_NETWORK_TRANSIT { return "NETWORK_TRANSIT" }
87 if s == NX_REAL_STAGE_CODEC_DECODE { return "CODEC_DECODE" }
88 if s == NX_REAL_STAGE_JITTER_BUFFER { return "JITTER_BUFFER" }
89 if s == NX_REAL_STAGE_COMPENSATOR { return "COMPENSATOR" }
90 if s == NX_REAL_STAGE_TRANSDUCER_RENDER { return "TRANSDUCER_RENDER" }
91 if s == NX_REAL_STAGE_ROOM_ACOUSTIC { return "ROOM_ACOUSTIC" }
92 if s == NX_REAL_STAGE_LISTENER_BIOLOGY { return "LISTENER_BIOLOGY" }
93 return "UNKNOWN_STAGE"
94}
95
96// ===== Verdicts ===================================================
97
98const NX_REAL_VERDICT_S_CLASS: i64 = 5 // >= 90/100 all axes
99const NX_REAL_VERDICT_A_CLASS: i64 = 4 // >= 80/100 all axes
100const NX_REAL_VERDICT_B_CLASS: i64 = 3 // >= 70/100 all axes
101const NX_REAL_VERDICT_C_CLASS: i64 = 2 // >= 60/100 all axes
102const NX_REAL_VERDICT_D_CLASS: i64 = 1 // below 60 anywhere
103const NX_REAL_VERDICT_F_NO_REFERENCE: i64 = 0 // no calibrated reference reality
104const NX_REAL_VERDICT_DEPENDENCY_MISSING: i64 = -1 // PARTIAL_WIRED default
105
106func nx_real_verdict_name(v: i64) -> *u8 {
107 if v == NX_REAL_VERDICT_S_CLASS { return "S_CLASS" }
108 if v == NX_REAL_VERDICT_A_CLASS { return "A_CLASS" }
109 if v == NX_REAL_VERDICT_B_CLASS { return "B_CLASS" }
110 if v == NX_REAL_VERDICT_C_CLASS { return "C_CLASS" }
111 if v == NX_REAL_VERDICT_D_CLASS { return "D_CLASS" }
112 if v == NX_REAL_VERDICT_F_NO_REFERENCE { return "F_NO_REFERENCE" }
113 if v == NX_REAL_VERDICT_DEPENDENCY_MISSING { return "DEPENDENCY_MISSING" }
114 return "UNKNOWN_VERDICT"
115}
116
117// ===== Realism score card =========================================
118//
119// Per-pipeline-per-profile end-to-end score. Bundled per
120// [[feedback-nishilang-16-arg-function-limit]].
121
122struct NxRealismScoreCard {
123 pipeline_serial_hash_ptr: *u8
124 pipeline_serial_hash_len: i64
125 target_profile: i64 // NX_PERCEPT_*
126 reference_reality_hash_ptr: *u8 // calibrated capture of "what
127 // really being there sounded like"
128 reference_reality_hash_len: i64
129 overall_verdict: i64 // NX_REAL_VERDICT_*
130 freq_preservation_score: i64 // 0..100
131 spatial_realism_score: i64
132 dynamic_range_score: i64
133 periodicity_novelty_score: i64
134 reverb_match_score: i64
135 latency_score: i64 // 0..100; higher = lower latency
136 biggest_loss_stage: i64 // NX_REAL_STAGE_*
137 biggest_loss_magnitude_x100: i64 // tenths of a percent
138}
139
140// ===== Top-level entry stubs ======================================
141
142// nx_realism_score_evaluate_pipeline -- given a pipeline (codec name +
143// transducer chain serial + room characterization) and a calibrated
144// reference reality recording, score the full end-to-end realism
145// against the target profile.
146
147func nx_realism_score_evaluate_pipeline(pipeline_name_ptr: *u8, pipeline_name_len: i64,
148 reference_reality_hash_ptr: *u8,
149 reference_reality_hash_len: i64,
150 target_profile: i64,
151 out_card_ptr: *NxRealismScoreCard) -> i64 {
152 if pipeline_name_len <= 0 { return NX_REAL_VERDICT_F_NO_REFERENCE }
153 if reference_reality_hash_len != 32 { return NX_REAL_VERDICT_F_NO_REFERENCE }
154 if nx_perceptual_profile_is_valid(target_profile) == 0 { return NX_REAL_VERDICT_F_NO_REFERENCE }
155 // PARTIAL_WIRED: pipeline round-trip + delta + judge + stage attribution queued.
156 return NX_REAL_VERDICT_DEPENDENCY_MISSING
157}
158
159// nx_realism_score_attribute_loss_to_stage -- given a score card,
160// return the stage that lost the most realism + the suggested fix.
161// Composes with nx_instrument_diagnostician for named-fix output.
162
163func nx_realism_score_attribute_loss_to_stage(card_ptr: *NxRealismScoreCard,
164 suggested_fix_buf_ptr: *u8,
165 suggested_fix_buf_cap: i64) -> i64 {
166 if suggested_fix_buf_cap <= 0 { return 0 }
167 return 0
168}
169
170// nx_realism_score_meets_s_class_gate -- single boolean: does this
171// pipeline meet the S-class threshold for this target profile? Returns
172// 1 if all 6 axes (5 perceptual + latency) >= 90 AND reproducible across
173// at least N independent sessions stored in nx_perceptual_dataset.
174
175func nx_realism_score_meets_s_class_gate(pipeline_name_ptr: *u8, pipeline_name_len: i64,
176 target_profile: i64,
177 min_sessions_n: i64) -> i64 {
178 if pipeline_name_len <= 0 { return 0 }
179 if nx_perceptual_profile_is_valid(target_profile) == 0 { return 0 }
180 if min_sessions_n < 3 { return 0 } // refuse
181 // claims with
182 // < 3 sessions
183 return 0
184}
185
186// nx_realism_score_register_reference_reality -- caller registers a
187// calibrated "reality capture" -- e.g., the founder's voice recorded
188// in person, in the same room, with calibrated reference gear, as the
189// gold standard nishifamily.com/video tries to reproduce.
190
191func nx_realism_score_register_reference_reality(reality_capture_hash_ptr: *u8,
192 reality_capture_hash_len: i64,
193 scenario_name_ptr: *u8,
194 scenario_name_len: i64,
195 calibration_session_hash_ptr: *u8,
196 calibration_session_hash_len: i64) -> i64 {
197 if reality_capture_hash_len != 32 { return 0 }
198 if scenario_name_len <= 0 { return 0 }
199 if calibration_session_hash_len != 32 { return 0 }
200 return 0
201}
202
203// nx_realism_score_get_last_verdict -- inspector.
204
205func nx_realism_score_get_last_verdict() -> i64 {
206 return NX_REAL_VERDICT_DEPENDENCY_MISSING
207}