nx_codec_perceptual_grader.nx source
↩ module page · 182 lines · 8904 B
1// nx_codec_perceptual_grader.nx -- codec round-trip × perceptual-judge integration.
2//
3// module: nishi-core.perception.codec_perceptual_grader
4// depends: nishi-core.perception.profile + nishi-core.perception.judge +
5// nishi-core.perception.signal_compensator + nishi-core.perception.perceptual_dataset +
6// nishi-core.io.syscalls
7// disk_kb: 5
8// capability: PERCEPTION
9// wired_status: PARTIAL_WIRED
10//
11// MISSING_CAPABILITIES:
12// - CODEC_DISPATCH (route to nx_voice_codec / nx_video_codec encoder
13// + decoder per signal domain; queued, depends on those codec arcs
14// finishing their Phase B residual + entropy coding)
15// - ROUND_TRIP_DELTA_COMPUTE (compare original vs decoded; needs nx_fft
16// for frequency-domain comparison)
17// - PER_PROFILE_AXIS_BREAKDOWN (which perceptual axis the codec lost on
18// for which species; e.g., "fine for HUMAN_NORMAL @ 20 kHz cutoff,
19// LOSE on DOG_VIZSLA at 22-45 kHz band")
20// - GRADER_LETTER_INTEGRATION (compose with nx_codec_grade letter scale
21// F/D/C/B/A/S to produce a per-target-profile letter grade)
22//
23// license_tier: PUBLIC_NISHI_SUBSTRATE
24// genealogy_id: feedback-multi-species-perceptual-substrate-not-anthropocentric_2026 +
25// feedback-substrate-primitives-meta-not-one-off_2026 +
26// feedback-bits-up-exceed-never-match +
27// nx_codec_grade_q10 +
28// nx_voice_codec_v1_q10 +
29// feedback-honest-perf-verdict-no-aspirational-claims
30//
31// Per cardinal [[feedback-multi-species-perceptual-substrate-not-anthropocentric]]:
32// "S-class codec" claims today rest on MOS / PESQ / VMAF -- metrics
33// tuned to HUMAN perceptual masking. A codec can be S-class on those
34// metrics and still fail every non-human listener (dog ignores it; cat
35// ignores it; livestock-welfare monitoring loses the stress signature;
36// conservation acoustic AI loses the species-call content).
37//
38// THIS primitive composes nx_voice_codec / nx_video_codec round-trip
39// with nx_perceptual_judge against a declared target profile to produce
40// a measurable per-species-per-axis grade. "Codec X is S-class for
41// HUMAN_NORMAL but only C for DOG_VIZSLA because it drops 22-45 kHz
42// content the Vizsla perceives" -- that statement becomes machine-checkable.
43//
44// Reuse set:
45// - Grading nx_voice_codec / nx_video_codec against every target
46// perceptual profile (40+ from nx_perceptual_profile.nx)
47// - Pre-deployment gate for nishifamily.com/video stream choice (pick
48// the codec + bitrate that PASSES the human perceptual gate without
49// stripping content other species in the room might perceive)
50// - Continuous integration smoke for codec regression (a codec change
51// that drops grade on any target species is a regression)
52// - Customer-facing "this product preserves real perceptual content
53// for species X" verifiable claim
54
55import "nx_syscalls.nx"
56import "nx_perceptual_profile.nx"
57import "nx_perceptual_judge.nx"
58import "nx_signal_compensator.nx"
59import "nx_perceptual_dataset.nx"
60
61// ===== Grading verdicts (compose with nx_codec_grade letter scale) ===
62
63const NX_CPG_GRADE_F: i64 = 0 // any axis INCONCLUSIVE/PROTOCOL_ERROR
64const NX_CPG_GRADE_D: i64 = 1 // >=2 LOSE rows for target profile
65const NX_CPG_GRADE_C: i64 = 2 // 1 LOSE with named improvement
66const NX_CPG_GRADE_B: i64 = 3 // no LOSE; <=1 UNMEASURED
67const NX_CPG_GRADE_A: i64 = 4 // all measured; >=4 WIN
68const NX_CPG_GRADE_S: i64 = 5 // all measured; >=6 WIN
69 // unanimously across profile's axes
70const NX_CPG_GRADE_DEPENDENCY_MISSING: i64 = 6 // PARTIAL_WIRED default
71
72func nx_cpg_grade_name(g: i64) -> *u8 {
73 if g == NX_CPG_GRADE_F { return "F" }
74 if g == NX_CPG_GRADE_D { return "D" }
75 if g == NX_CPG_GRADE_C { return "C" }
76 if g == NX_CPG_GRADE_B { return "B" }
77 if g == NX_CPG_GRADE_A { return "A" }
78 if g == NX_CPG_GRADE_S { return "S" }
79 if g == NX_CPG_GRADE_DEPENDENCY_MISSING { return "DEPENDENCY_MISSING" }
80 return "UNKNOWN_GRADE"
81}
82
83// ===== Per-axis verdict (matches nx_codec_grade axis verdicts) =====
84
85const NX_CPG_AXIS_WIN: i64 = 1
86const NX_CPG_AXIS_TIE: i64 = 2
87const NX_CPG_AXIS_LOSE: i64 = 3 // codec loses content this profile perceives
88const NX_CPG_AXIS_UNMEASURED: i64 = 4
89const NX_CPG_AXIS_INCONCLUSIVE: i64 = 5
90
91func nx_cpg_axis_verdict_name(v: i64) -> *u8 {
92 if v == NX_CPG_AXIS_WIN { return "WIN" }
93 if v == NX_CPG_AXIS_TIE { return "TIE" }
94 if v == NX_CPG_AXIS_LOSE { return "LOSE" }
95 if v == NX_CPG_AXIS_UNMEASURED { return "UNMEASURED" }
96 if v == NX_CPG_AXIS_INCONCLUSIVE { return "INCONCLUSIVE" }
97 return "UNKNOWN_AXIS_VERDICT"
98}
99
100// ===== Grading result struct ======================================
101//
102// Per-codec-per-profile grade card. Bundled per
103// [[feedback-nishilang-16-arg-function-limit]].
104
105struct NxCpgGradeCard {
106 codec_serial_hash_ptr: *u8
107 codec_serial_hash_len: i64 // identifies which codec+version
108 target_profile: i64 // NX_PERCEPT_*
109 overall_grade: i64 // NX_CPG_GRADE_*
110 freq_preservation_verdict: i64 // NX_CPG_AXIS_*
111 spatial_realism_verdict: i64
112 dynamic_range_verdict: i64
113 periodicity_novelty_verdict: i64
114 reverb_match_verdict: i64
115 bits_lost_in_perceptual_band: i64 // count of bits the codec
116 // discarded from frequencies
117 // / channels the profile perceives
118 first_byte_latency_ms: i64 // latency axis composes
119 auditability_score: i64 // 0..100; closed weights = 0
120}
121
122// ===== Top-level entry stubs ======================================
123
124// nx_cpg_grade_codec_round_trip -- given a codec name + a source sample +
125// a target profile, run the codec encode + decode + compute the
126// per-axis grade card.
127
128func nx_cpg_grade_codec_round_trip(codec_name_ptr: *u8, codec_name_len: i64,
129 source_sample_hash_ptr: *u8, source_sample_hash_len: i64,
130 target_profile: i64,
131 out_card_ptr: *NxCpgGradeCard) -> i64 {
132 if codec_name_len <= 0 { return NX_CPG_GRADE_F }
133 if source_sample_hash_len != 32 { return NX_CPG_GRADE_F }
134 if nx_perceptual_profile_is_valid(target_profile) == 0 { return NX_CPG_GRADE_F }
135 // PARTIAL_WIRED: codec dispatch + round-trip + delta + judge queued.
136 return NX_CPG_GRADE_DEPENDENCY_MISSING
137}
138
139// nx_cpg_grade_codec_against_all_profiles -- batch-grade a codec against
140// every species profile in nx_perceptual_profile. Returns count of
141// profiles where codec achieves grade S; substrate fails CI if a codec
142// regression drops a previously-S profile to below S without an annotated
143// reason.
144
145func nx_cpg_grade_codec_against_all_profiles(codec_name_ptr: *u8, codec_name_len: i64,
146 source_sample_hash_ptr: *u8, source_sample_hash_len: i64,
147 s_class_threshold: i64) -> i64 {
148 if codec_name_len <= 0 { return 0 }
149 if source_sample_hash_len != 32 { return 0 }
150 if s_class_threshold < NX_CPG_GRADE_C { return 0 }
151 return 0
152}
153
154// nx_cpg_grade_get_per_axis_loss_explanation -- for a LOSE verdict on a
155// given axis, return the named improvement (matches nx_codec_grade's
156// LOSE_BY_X pattern). E.g., codec LOSEs freq_preservation on DOG_VIZSLA
157// -> "raise sample rate from 48 kHz to 96 kHz; current cutoff at 22 kHz
158// drops 22-45 kHz band the profile perceives."
159
160func nx_cpg_grade_get_per_axis_loss_explanation(card_ptr: *NxCpgGradeCard,
161 axis_id: i64,
162 explanation_buf_ptr: *u8,
163 explanation_buf_cap: i64) -> i64 {
164 if axis_id < 1 { return 0 }
165 if explanation_buf_cap <= 0 { return 0 }
166 return 0
167}
168
169// nx_cpg_grade_persist_to_dataset -- write the grade card into
170// nx_perceptual_dataset as a VALIDATION entry per
171// [[feedback-end-to-end-bit-traceability-architecture]] so the codec's
172// grade history is preserved as the codec evolves.
173
174func nx_cpg_grade_persist_to_dataset(card_ptr: *NxCpgGradeCard) -> i64 {
175 return 0
176}
177
178// nx_cpg_grade_get_last_verdict -- inspector.
179
180func nx_cpg_grade_get_last_verdict() -> i64 {
181 return NX_CPG_GRADE_DEPENDENCY_MISSING
182}