nx_install_plan.nx source
↩ module page · 296 lines · 11317 B
1// nx_install_plan.nx -- selection-pipeline output record.
2//
3// SA-6/SA-7 bridge of NISHI_SELF_ASSEMBLY_ROADMAP.md. Captures
4// (probe-snapshot, calibration-snapshot, policy-snapshot,
5// selected-variant-ids, total-cost, verdict) into one canary-bracketed
6// record. The artifact:
7// - SA-6 feeds this to nx_compile (which compiles only the selected
8// variants), then nx_verify (which smoke-runs each on the target)
9// - SA-7 cryptographically attests this record (install_hash =
10// H(probe_snapshot + calibration_snapshot + policy_snapshot +
11// selection)) so future audits can REPLAY the selector against
12// the recorded inputs and reach bit-identical output
13//
14// The plan is content-addressable by construction: same inputs (same
15// probe + same calibration + same policy + same candidate set) MUST
16// yield the same plan. This is the racing-line claim per
17// [[feedback-end-to-end-bit-traceability-architecture]]: every byte
18// from source -> selection -> install has a ProvenanceLink.
19//
20// V1 scope:
21// - Flat snapshot of probe + calibration + policy key fields
22// - selected_variant_ids stored as *i64 array (caller-owned)
23// - canary bracket for tamper-detect
24// - schema versioning for future field additions
25//
26// Deferred per roadmap:
27// - cryptographic install_hash computation (SA-7; will compose with
28// nx_sha256 + nx_blake2b)
29// - in-toto link metadata serialization (SA-7)
30// - Rekor-class append-only audit log (SA-7)
31// - Multi-substrate co-residence (multiple plans on one host) (SA-7)
32// - Replay-from-plan verifier (SA-7)
33//
34// genealogy_id: in_toto_2018 + slsa_2021 + sigstore_2021 +
35// reproducible_builds_2013 + cardinal_2026-05-19_self_assembly
36// lineage_id: substrate_install_plan_v1
37//
38// nx_capability_manifest:
39// variant_class: install_plan_record
40// variant_id: install_plan_v1
41// requires_isa: [rv64imac, x86_64]
42// requires_syscalls: [mmap, clock_gettime_mono]
43// requires_ram_min_b: 4096
44// tier_floor: NX_TIER_MOBILE
45// tier_ceiling: NX_TIER_HPC
46// cost_model:
47// flops_per_n: 0.0
48// bytes_per_n: 256.0 // NxInstallPlan size + selected_ids array
49// syscalls_per_n: 1.0 // one clock_gettime per capture
50// adversary_class: THREAT_AI_ADVERSARY
51//
52// nx_safety_envelope:
53// intended_use: "Captures selection-pipeline output for SA-7
54// attestation; canary-bracketed; replay-source"
55// sil_target: SIL2
56// evidence: [canary_tagged, snapshots_copied_not_referenced,
57// deterministic_capture_same_inputs]
58// verdict: NOT_YET_EVALUATED
59
60import "nx_syscalls.nx"
61import "nx_probe.nx"
62import "nx_calibrate.nx"
63import "nx_select.nx"
64import "nx_select_joint.nx"
65
66// ===== Canary constants ===========================================
67const NX_PLAN_CANARY_PRE: i64 = 0x4E58504C414E5000 // "NXPLANP\0"
68const NX_PLAN_CANARY_POST: i64 = 0x004E58504C414E45 // "\0NXPLANE"
69
70const NX_PLAN_SCHEMA_VERSION: i64 = 1
71
72// ===== Verdict sealed enum =======================================
73const NX_PLAN_VERDICT_UNKNOWN: i64 = 0
74const NX_PLAN_VERDICT_OK: i64 = 1
75const NX_PLAN_VERDICT_PARTIAL: i64 = 2 // some nodes had NONE_MATCH
76const NX_PLAN_VERDICT_NO_FEASIBLE: i64 = 3 // entire pipeline yielded no feasible
77const NX_PLAN_VERDICT_BAD_INPUT: i64 = 4
78const NX_PLAN_VERDICT_N: i64 = 5
79
80func nx_plan_verdict_is_valid(v: i64) -> i64 {
81 if v < 0 { return 0 }
82 if v >= NX_PLAN_VERDICT_N { return 0 }
83 return 1
84}
85
86// ===== NxInstallPlan =============================================
87//
88// All fields are CAPTURED VALUES (by-copy) so the plan survives even
89// if the source probe / calibration / policy structs are deallocated.
90// Per Cardinal 13 (additive-only), the plan is the durable record;
91// future re-selection produces a NEW plan with the previous one
92// tombstoned via install_hash chaining (SA-7).
93
94struct NxInstallPlan {
95 canary_pre: i64,
96 schema_version: i64,
97 ts_us: i64,
98
99 // ----- probe snapshot -----
100 probe_isa_family: i64,
101 probe_endianness: i64,
102 probe_pointer_width_bits: i64,
103 probe_page_size_bytes: i64,
104 probe_mmap_works: i64,
105 probe_write_works: i64,
106 probe_mono_clock_works: i64,
107
108 // ----- calibration snapshot -----
109 calib_int_alu_ps_per_op: i64,
110 calib_mem_ns_l1: i64,
111 calib_mem_ns_l2: i64,
112 calib_mem_ns_ram: i64,
113 calib_mem_bw_mib_per_s: i64,
114 calib_syscall_ns_gettime: i64,
115 calib_inferred_tier: i64,
116
117 // ----- policy snapshot -----
118 policy_weight_throughput: i64,
119 policy_weight_bytes: i64,
120 policy_weight_syscalls: i64,
121 policy_weight_energy: i64,
122 policy_weight_ram: i64,
123
124 // ----- selection result -----
125 n_selected: i64,
126 total_cost_q10: i64,
127 selection_verdict: i64,
128 // Array of selected variant_id values, length = n_selected.
129 // Owned by the plan (deep-copied at capture time).
130 selected_variant_ids: *i64,
131
132 canary_post: i64,
133}
134
135// ===== Allocation ================================================
136func nx_install_plan_new() -> *NxInstallPlan {
137 let p: *NxInstallPlan = (sys_mmap(256)) as *NxInstallPlan
138 p.canary_pre = NX_PLAN_CANARY_PRE
139 p.canary_post = NX_PLAN_CANARY_POST
140 p.schema_version = NX_PLAN_SCHEMA_VERSION
141 p.ts_us = 0
142 p.probe_isa_family = NX_ISA_UNKNOWN
143 p.probe_endianness = NX_ENDIAN_UNKNOWN
144 p.probe_pointer_width_bits = 0
145 p.probe_page_size_bytes = 0
146 p.probe_mmap_works = 0
147 p.probe_write_works = 0
148 p.probe_mono_clock_works = 0
149 p.calib_int_alu_ps_per_op = 0
150 p.calib_mem_ns_l1 = 0
151 p.calib_mem_ns_l2 = 0
152 p.calib_mem_ns_ram = 0
153 p.calib_mem_bw_mib_per_s = 0
154 p.calib_syscall_ns_gettime = 0
155 p.calib_inferred_tier = NX_TIER_INF_UNKNOWN
156 p.policy_weight_throughput = 0
157 p.policy_weight_bytes = 0
158 p.policy_weight_syscalls = 0
159 p.policy_weight_energy = 0
160 p.policy_weight_ram = 0
161 p.n_selected = 0
162 p.total_cost_q10 = 0
163 p.selection_verdict = NX_PLAN_VERDICT_UNKNOWN
164 p.selected_variant_ids = (0 as i64) as *i64
165 return p
166}
167
168// ===== Capture ===================================================
169//
170// Snapshots all source data into the plan. The caller passes:
171// - probe + calib + policy (read-only, deep-copy into plan)
172// - nodes_ptrs + n_nodes: array of NxJointNode pointers (for
173// variant_id lookup via the picked indices)
174// - selected_indices: *i64 array of n_nodes selected indices
175// - total_cost: aggregate cost computed by the selector
176// - verdict: NX_PLAN_VERDICT_*
177//
178// Returns 0 on success; non-zero on canary tamper or bad input.
179
180func nx_install_plan_capture(
181 plan: *NxInstallPlan,
182 probe: *NxProbeRecord,
183 calib: *NxCalibrationRecord,
184 policy: *NxPolicy,
185 nodes_ptrs: *i64,
186 n_nodes: i64,
187 selected_indices: *i64,
188 total_cost: i64,
189 verdict: i64
190) -> i64 {
191 if (plan as i64) == 0 { return 1 }
192 if plan.canary_pre != NX_PLAN_CANARY_PRE { return 2 }
193 if plan.canary_post != NX_PLAN_CANARY_POST { return 3 }
194 if (probe as i64) == 0 { return 4 }
195 if (calib as i64) == 0 { return 5 }
196 if (policy as i64) == 0 { return 6 }
197 if n_nodes < 0 { return 7 }
198 if nx_plan_verdict_is_valid(verdict) != 1 { return 8 }
199
200 // Timestamp.
201 let ts: *i64 = (sys_mmap(16)) as *i64
202 let rc_ts: i64 = sys_clock_gettime_mono(ts)
203 if rc_ts == 0 {
204 plan.ts_us = (ts[0] * 1000000) + (ts[1] / 1000)
205 }
206
207 // Probe snapshot.
208 plan.probe_isa_family = probe.actual_isa_family
209 plan.probe_endianness = probe.actual_endianness
210 plan.probe_pointer_width_bits = probe.actual_pointer_width_bits
211 plan.probe_page_size_bytes = probe.actual_page_size_bytes
212 plan.probe_mmap_works = probe.actual_mmap_works
213 plan.probe_write_works = probe.actual_write_works
214 plan.probe_mono_clock_works = probe.actual_mono_clock_works
215
216 // Calibration snapshot.
217 plan.calib_int_alu_ps_per_op = calib.int_alu_ps_per_op
218 plan.calib_mem_ns_l1 = calib.mem_ns_per_access_l1
219 plan.calib_mem_ns_l2 = calib.mem_ns_per_access_l2
220 plan.calib_mem_ns_ram = calib.mem_ns_per_access_ram
221 plan.calib_mem_bw_mib_per_s = calib.mem_bw_mib_per_s
222 plan.calib_syscall_ns_gettime = calib.syscall_ns_clock_gettime
223 plan.calib_inferred_tier = calib.inferred_tier
224
225 // Policy snapshot.
226 plan.policy_weight_throughput = policy.weight_throughput
227 plan.policy_weight_bytes = policy.weight_bytes
228 plan.policy_weight_syscalls = policy.weight_syscalls
229 plan.policy_weight_energy = policy.weight_energy
230 plan.policy_weight_ram = policy.weight_ram
231
232 // Selection.
233 plan.n_selected = n_nodes
234 plan.total_cost_q10 = total_cost
235 plan.selection_verdict = verdict
236
237 // Deep-copy selected variant IDs. Look up each picked manifest's
238 // variant_id via the (node, picked_idx) pair so the plan does NOT
239 // hold raw indices (indices are meaningless once candidates
240 // change; variant_id is stable).
241 if n_nodes > 0 {
242 let ids: *i64 = (sys_mmap(n_nodes * 8)) as *i64
243 var i: i64 = 0
244 while i < n_nodes {
245 let pick: i64 = selected_indices[i]
246 if pick < 0 {
247 ids[i] = -1 // sentinel for "no selection at this node"
248 } else {
249 let node_addr: i64 = nodes_ptrs[i]
250 if node_addr == 0 {
251 ids[i] = -1
252 } else {
253 let node: *NxJointNode = node_addr as *NxJointNode
254 let m_addr: i64 = node.manifest_ptrs[pick]
255 if m_addr == 0 {
256 ids[i] = -1
257 } else {
258 let m: *NxManifest = m_addr as *NxManifest
259 ids[i] = m.variant_id
260 }
261 }
262 }
263 i = i + 1
264 }
265 plan.selected_variant_ids = ids
266 } else {
267 plan.selected_variant_ids = (0 as i64) as *i64
268 }
269
270 // Re-verify canaries post-capture.
271 if plan.canary_pre != NX_PLAN_CANARY_PRE { return 9 }
272 if plan.canary_post != NX_PLAN_CANARY_POST { return 10 }
273 return 0
274}
275
276// ===== Validity gate =============================================
277func nx_install_plan_is_valid(plan: *NxInstallPlan) -> i64 {
278 if (plan as i64) == 0 { return 0 }
279 if plan.canary_pre != NX_PLAN_CANARY_PRE { return 0 }
280 if plan.canary_post != NX_PLAN_CANARY_POST { return 0 }
281 if plan.schema_version != NX_PLAN_SCHEMA_VERSION { return 0 }
282 if nx_plan_verdict_is_valid(plan.selection_verdict) != 1 { return 0 }
283 if plan.n_selected < 0 { return 0 }
284 return 1
285}
286
287// ===== Variant ID lookup =========================================
288// Returns variant_id at slot `i`, or -1 if i out of range / plan
289// invalid.
290func nx_install_plan_variant_id_at(plan: *NxInstallPlan, i: i64) -> i64 {
291 if nx_install_plan_is_valid(plan) != 1 { return -1 }
292 if i < 0 { return -1 }
293 if i >= plan.n_selected { return -1 }
294 if (plan.selected_variant_ids as i64) == 0 { return -1 }
295 return plan.selected_variant_ids[i]
296}