nx_perceptual_dataset.nx source
↩ module page · 194 lines · 9900 B
1// nx_perceptual_dataset.nx -- paired (signal, species, behavioral metric) store.
2//
3// module: nishi-core.perception.perceptual_dataset
4// depends: nishi-core.perception.profile + nishi-core.perception.provenance_curve_store +
5// nishi-core.io.syscalls
6// disk_kb: 5
7// capability: PERCEPTION
8// wired_status: PARTIAL_WIRED
9//
10// MISSING_CAPABILITIES:
11// - ENTRY_SERIALIZATION (JSONL append-only log + indexed read)
12// - PROVENANCE_LINK_CHAIN (per-entry hash chain back to source signal +
13// calibration + species profile)
14// - LICENSE_TAG_VALIDATION (CC0 / CC-BY / family-private filter at write)
15// - QUERY_BY_PROFILE (return all entries for a given species/breed profile)
16// - QUERY_BY_BEHAVIOR_RANGE (return entries where engagement metric falls
17// within bounds; needed by nx_perceptual_judge training)
18//
19// license_tier: PUBLIC_NISHI_SUBSTRATE
20// genealogy_id: feedback-multi-species-perceptual-substrate-not-anthropocentric_2026 +
21// feedback-substrate-primitives-meta-not-one-off_2026 +
22// reference-ingest-citation-and-license-discipline +
23// macaulay_library_cornell_lab +
24// xeno_canto_community
25//
26// Per cardinal [[feedback-multi-species-perceptual-substrate-not-anthropocentric]]:
27// THIS primitive stores paired (signal, species, behavioral-engagement)
28// tuples that train nx_perceptual_judge to predict whether a given signal
29// would be classified as "real" by a given species' perceptual system.
30//
31// Customer Zero entries: founder's Vizslas during the NISHI_DOG_PERCEPTUAL_TEST
32// behavioral A/B sessions. Each trial produces one entry:
33// - signal_hash: content-hash of the rendered .wav stimulus
34// - species_profile: e.g., NX_PERCEPT_DOG_VIZSLA
35// - stimulus_condition: TV_QUALITY / PREY_SPEC / PREY_SPEC_PLUS_SCENT / SILENCE_CONTROL
36// - behavioral_metrics: orientation_latency_ms, approach_distance_cm,
37// time_on_speaker_s, ear_position_score, tail_position_score,
38// head_cock_count, vocalization_flag
39// - provenance_chain: hash of the rig calibration curve + source sample
40// license + session metadata
41
42import "nx_syscalls.nx"
43import "nx_perceptual_profile.nx"
44import "nx_provenance_curve_store.nx"
45
46// ===== Entry kind sealed enum =====================================
47
48const NX_PDS_ENTRY_TRIAL: i64 = 1 // behavioral trial result
49const NX_PDS_ENTRY_CALIBRATION: i64 = 2 // rig calibration session
50const NX_PDS_ENTRY_SAMPLE: i64 = 3 // source recording (prey/conspecific)
51const NX_PDS_ENTRY_VALIDATION: i64 = 4 // judge cross-validation result
52const NX_PDS_ENTRY_DRIFT_OBSERVATION: i64 = 5 // drift-monitor finding
53
54func nx_pds_entry_kind_name(k: i64) -> *u8 {
55 if k == NX_PDS_ENTRY_TRIAL { return "TRIAL" }
56 if k == NX_PDS_ENTRY_CALIBRATION { return "CALIBRATION" }
57 if k == NX_PDS_ENTRY_SAMPLE { return "SAMPLE" }
58 if k == NX_PDS_ENTRY_VALIDATION { return "VALIDATION" }
59 if k == NX_PDS_ENTRY_DRIFT_OBSERVATION { return "DRIFT_OBSERVATION" }
60 return "UNKNOWN_ENTRY_KIND"
61}
62
63// ===== Stimulus condition sealed enum =============================
64//
65// What stimulus the subject was exposed to. Used by nx_perceptual_judge
66// to learn the boundary between "real" and "fake" perceptual classes.
67
68const NX_PDS_COND_SILENCE_CONTROL: i64 = 1
69const NX_PDS_COND_TV_QUALITY: i64 = 2 // 44.1 kHz AAC, low-pass at 18 kHz
70const NX_PDS_COND_PREY_SPEC_AUDIO: i64 = 3 // 192 kHz 24-bit, prey-spec rendered
71const NX_PDS_COND_PREY_SPEC_PLUS_SCENT: i64 = 4
72const NX_PDS_COND_REAL_STIMULUS: i64 = 5 // live prey present (gold-standard)
73const NX_PDS_COND_USER_DEFINED: i64 = 6
74
75func nx_pds_cond_name(c: i64) -> *u8 {
76 if c == NX_PDS_COND_SILENCE_CONTROL { return "SILENCE_CONTROL" }
77 if c == NX_PDS_COND_TV_QUALITY { return "TV_QUALITY" }
78 if c == NX_PDS_COND_PREY_SPEC_AUDIO { return "PREY_SPEC_AUDIO" }
79 if c == NX_PDS_COND_PREY_SPEC_PLUS_SCENT { return "PREY_SPEC_PLUS_SCENT" }
80 if c == NX_PDS_COND_REAL_STIMULUS { return "REAL_STIMULUS" }
81 if c == NX_PDS_COND_USER_DEFINED { return "USER_DEFINED" }
82 return "UNKNOWN_CONDITION"
83}
84
85// ===== License tag sealed enum ====================================
86//
87// Per [[reference-ingest-citation-and-license-discipline]] — write
88// refuses entries lacking a license tag to prevent license drift.
89
90const NX_PDS_LICENSE_CC0: i64 = 1
91const NX_PDS_LICENSE_CC_BY_4_0: i64 = 2
92const NX_PDS_LICENSE_US_GOV: i64 = 3 // PD-USGov
93const NX_PDS_LICENSE_OGL: i64 = 4 // UK Open Government
94const NX_PDS_LICENSE_FAMILY_PRIVATE: i64 = 5 // founder's-own-dog data
95const NX_PDS_LICENSE_RESEARCH_INSTITUTION: i64 = 6 // partner-lab data, terms attached
96
97func nx_pds_license_name(l: i64) -> *u8 {
98 if l == NX_PDS_LICENSE_CC0 { return "CC0" }
99 if l == NX_PDS_LICENSE_CC_BY_4_0 { return "CC_BY_4_0" }
100 if l == NX_PDS_LICENSE_US_GOV { return "US_GOV_PUBLIC_DOMAIN" }
101 if l == NX_PDS_LICENSE_OGL { return "UK_OGL" }
102 if l == NX_PDS_LICENSE_FAMILY_PRIVATE { return "FAMILY_PRIVATE" }
103 if l == NX_PDS_LICENSE_RESEARCH_INSTITUTION { return "RESEARCH_INSTITUTION" }
104 return "UNKNOWN_LICENSE"
105}
106
107// ===== Write/read verdicts ========================================
108
109const NX_PDS_OK: i64 = 0
110const NX_PDS_FAIL_BAD_KIND: i64 = 1
111const NX_PDS_FAIL_BAD_PROFILE: i64 = 2
112const NX_PDS_FAIL_LICENSE_MISSING: i64 = 3
113const NX_PDS_FAIL_LICENSE_REFUSED: i64 = 4 // SA / NC / proprietary
114const NX_PDS_FAIL_PROVENANCE_BROKEN: i64 = 5
115const NX_PDS_FAIL_DEPENDENCY_MISSING: i64 = 6 // PARTIAL_WIRED default
116
117func nx_pds_verdict_name(v: i64) -> *u8 {
118 if v == NX_PDS_OK { return "OK" }
119 if v == NX_PDS_FAIL_BAD_KIND { return "FAIL_BAD_KIND" }
120 if v == NX_PDS_FAIL_BAD_PROFILE { return "FAIL_BAD_PROFILE" }
121 if v == NX_PDS_FAIL_LICENSE_MISSING { return "FAIL_LICENSE_MISSING" }
122 if v == NX_PDS_FAIL_LICENSE_REFUSED { return "FAIL_LICENSE_REFUSED" }
123 if v == NX_PDS_FAIL_PROVENANCE_BROKEN { return "FAIL_PROVENANCE_BROKEN" }
124 if v == NX_PDS_FAIL_DEPENDENCY_MISSING { return "FAIL_DEPENDENCY_MISSING" }
125 return "UNKNOWN_VERDICT"
126}
127
128// ===== Behavioral metrics struct (flat fields per nxc2 16-arg cap) ====
129//
130// Per [[feedback-nishilang-16-arg-function-limit]]: bundle metrics in a
131// struct so write_trial doesn't blow the function-signature cap.
132
133struct NxPdsBehavioralMetrics {
134 orientation_latency_ms: i64
135 approach_distance_cm: i64
136 approach_latency_ms: i64
137 time_on_speaker_s_x10: i64 // tenth-seconds (avoid float)
138 ear_position_score: i64 // 0..100, blind-coded or CV
139 tail_position_score: i64
140 head_cock_count: i64
141 vocalization_flag: i64 // 0/1
142 heart_rate_delta_bpm: i64 // tier-2 only; -1 if not measured
143 activity_intensity_x10: i64 // tenth-units; -1 if not measured
144}
145
146// ===== Top-level entry stubs ======================================
147
148// nx_pds_write_trial -- append a behavioral trial entry to the dataset.
149
150func nx_pds_write_trial(signal_hash_ptr: *u8, signal_hash_len: i64,
151 profile: i64, condition: i64,
152 metrics_ptr: *NxPdsBehavioralMetrics,
153 rig_calibration_hash_ptr: *u8, rig_calibration_hash_len: i64,
154 license: i64) -> i64 {
155 if signal_hash_len != 32 { return NX_PDS_FAIL_PROVENANCE_BROKEN }
156 if nx_perceptual_profile_is_valid(profile) == 0 { return NX_PDS_FAIL_BAD_PROFILE }
157 if condition < NX_PDS_COND_SILENCE_CONTROL { return NX_PDS_FAIL_BAD_KIND }
158 if condition > NX_PDS_COND_USER_DEFINED { return NX_PDS_FAIL_BAD_KIND }
159 if rig_calibration_hash_len != 32 { return NX_PDS_FAIL_PROVENANCE_BROKEN }
160 if license < NX_PDS_LICENSE_CC0 { return NX_PDS_FAIL_LICENSE_MISSING }
161 if license > NX_PDS_LICENSE_RESEARCH_INSTITUTION { return NX_PDS_FAIL_LICENSE_MISSING }
162 // PARTIAL_WIRED: JSONL serialization + append + index update queued.
163 return NX_PDS_FAIL_DEPENDENCY_MISSING
164}
165
166// nx_pds_write_sample -- append a source-recording entry (e.g.,
167// pheasant flush from Macaulay Library).
168
169func nx_pds_write_sample(sample_hash_ptr: *u8, sample_hash_len: i64,
170 target_species_profile: i64,
171 source_url_ptr: *u8, source_url_len: i64,
172 license: i64) -> i64 {
173 if sample_hash_len != 32 { return NX_PDS_FAIL_PROVENANCE_BROKEN }
174 if nx_perceptual_profile_is_valid(target_species_profile) == 0 { return NX_PDS_FAIL_BAD_PROFILE }
175 if source_url_len <= 0 { return NX_PDS_FAIL_PROVENANCE_BROKEN }
176 if license < NX_PDS_LICENSE_CC0 { return NX_PDS_FAIL_LICENSE_MISSING }
177 if license > NX_PDS_LICENSE_RESEARCH_INSTITUTION { return NX_PDS_FAIL_LICENSE_MISSING }
178 return NX_PDS_FAIL_DEPENDENCY_MISSING
179}
180
181// nx_pds_query_count_for_profile -- how many trial entries do we have for
182// a given species profile? Used by nx_perceptual_judge to gate promotion
183// from PARTIAL_WIRED to FULLY_WIRED (needs >= N trials per condition).
184
185func nx_pds_query_count_for_profile(profile: i64) -> i64 {
186 if nx_perceptual_profile_is_valid(profile) == 0 { return 0 }
187 return 0
188}
189
190// nx_pds_get_last_verdict -- inspector.
191
192func nx_pds_get_last_verdict() -> i64 {
193 return NX_PDS_FAIL_DEPENDENCY_MISSING
194}