nx_tier.nx source

1// nx_tier.nx -- substrate-wide tier configuration. 2// 3// Single point of edit for scale-agnostic substrate. Per user 4// directive 2026-05-13: "with the i64 it looks hardcoded everywhere 5// if we really want this dynamic dont we want that to be a changeable 6// value everywhere so it can switch to i128 and i256 etc." 7// 8// Per cardinals: 9// - feedback-numeric-tier-ladder.md (N0..N9 swap) 10// - feedback-scale-agnostic-substrate.md (MCU..HPC swap) 11// - feedback-substrate-additive-not-restrictive.md (declare cost) 12// 13// SEMANTIC ALIASES (not all should swap simultaneously): 14// 15// nx_int -- DEFAULT ARITHMETIC integer. Swappable across the 16// numeric tier ladder. Swap this to i128 to make the 17// entire substrate compute in 128-bit integers. 18// 19// nx_size -- MEMORY-SIZE integer. Always platform-pointer-width. 20// Used for buffer sizes, mmap byte counts, struct 21// sizes. Does NOT swap with nx_int -- changing this 22// would break pointer arithmetic. Stays i64 on RV64. 23// 24// nx_idx -- ARRAY-INDEX integer. Same width as nx_size on 25// flat-memory targets. Distinct alias so future 26// GPU/distributed targets can change indexing without 27// touching arithmetic. 28// 29// nx_byte -- The byte type. Stays u8. Distinct alias so MCU 30// targets that emulate u16-byte memory could rebind. 31// 32// HARDWARE-TIER BUFFER SIZES (declare cost, don't restrict): 33// 34// NX_BUF_TINY -- 64 B (MCU-friendly; stack-safe) 35// NX_BUF_SMALL -- 256 B (MCU heap-friendly) 36// NX_BUF_MEDIUM -- 4096 B (page-size; workstation default) 37// NX_BUF_LARGE -- 64 KiB (server-friendly) 38// NX_BUF_HUGE -- 1 MiB (HPC; assumes virtual memory) 39// 40// Use these instead of `sys_mmap(4096)` etc. so the substrate 41// announces its memory footprint and tier-incompatible code can 42// be flagged by audit. 43// 44// HARDWARE TIER (informational; downstream code may branch): 45// 46// NX_TIER_MCU = 0 -- microcontroller, kilobytes RAM 47// NX_TIER_SOVEREIGN_CHIP = 1 -- custom silicon, ~MB RAM 48// NX_TIER_FAMILY_DEVICE = 2 -- phone/router, ~GB RAM 49// NX_TIER_WORKSTATION = 3 -- laptop/desktop, ~10-100 GB RAM 50// NX_TIER_SERVER = 4 -- server-class, ~TB RAM 51// NX_TIER_HPC = 5 -- cluster, distributed 52// 53// COMPILE-TIME SWAP for nx_int (uncomment exactly one line): 54 55// THIS FILE IS THE SINGLE DEFINITION SITE for substrate-wide types. 56// Per user directive 2026-05-13: only this file (and platform-ABI 57// definition files like nx_syscalls.nx) should declare bare i64. 58// Every other substrate module uses the aliases below. 59 60// ===== arithmetic-tier aliases (swappable per nx_int tier ladder) ===== 61 62type nx_int = i64 // N1 -- default; 9 quintillion, fits all physical scales 63// type nx_int = i32 // N0 -- MCU / embedded 64// type nx_int = i128 // N2 -- queued; needs nx_i128 backend ops 65// type nx_int = i256 // N3 -- shipped (nx_i256.nx); cosmology / crypto 66 67// ===== platform-width aliases (stay at pointer width) ================= 68 69type nx_size = i64 // memory-size / byte-count 70type nx_idx = i64 // array-index 71type nx_byte = u8 // single-byte unit 72 73// ===== POSIX/Linux platform-ABI aliases (mandated 64-bit on RV64) ==== 74// 75// Each is a 64-bit integer by Linux RV64 ABI. Renamed here so substrate 76// code never writes bare `i64` for these semantic types. 77 78type nx_fd = i64 // file descriptor (kernel-mandated width) 79type nx_exit = i64 // exit / status code (main() return) 80type nx_pid = i64 // process id 81type nx_uid = i64 // user id 82type nx_gid = i64 // group id 83type nx_syscall_num = i64 // Linux syscall number 84type nx_off = i64 // file offset (off_t) 85type nx_errno = i64 // errno (negative on syscall failure) 86 87// ===== SEMANTIC TYPE GENEALOGY (added 2026-05-20) ====================== 88// 89// Per cardinal [[feedback-type-genealogy-math-cardinal-not-script]] 90// AND its immediate refinement (same session): every alias collapsing 91// to i64 is "y2k incestuous" -- relabeling, not genealogy. Real 92// semantic types pick the APPROPRIATE underlying width based on 93// the physics of the values they represent: 94// 95// - Small sealed enums (15 outcomes, 18 probe kinds) -> u8 96// - Display pixel coords (~32M max realistic) -> i32 97// - Q10 / Q14 fixed-point (values * 1024 / 16384) -> i32 98// - 32-bit color packs (RGBA8888) -> u32 99// - Q20 fixed-point (values * 1048576) -> i64 100// - Wide color packs (RGBA16161616, PRESERVE_ALL) -> u64 101// - Timestamps (ns / us / ms / cycles) -> i64 (2038 Y2K38) 102// - 64-bit hash digests -> u64 103// - Cryptographic hashes (SHA-256, SHA-512) -> STRUCT (multi-word; queued) 104// - Virtual addresses on 64-bit ISA -> u64 105// 106// Each type is a child of its PHYSICALLY-APPROPRIATE parent 107// (i8/u8/i32/u32/i64/u64), not blanket-i64. This breaks the 108// y2k-incestuous trap where renaming i64 N ways pretends to be 109// type discipline while every value silently shares one width. 110 111// ----- TIME family (all i64; ns/us/ms/cycles legitimately need it) ----- 112// 2038 Y2K38 lurks for 32-bit time_t; i64 is the substrate-honest 113// choice. ms/us/ns + cycles all i64. s_q14 needs only i32 range 114// (val*16384 fits comfortably in i32 for typical second scales) but 115// we stay at i64 to compose cleanly with the i64 time arithmetic 116// across the substrate. 117type nx_ns = i64 // nanoseconds (since boot, monotonic) 118type nx_us = i64 // microseconds (since boot, monotonic) 119type nx_ms = i64 // milliseconds (since epoch, wall) 120type nx_s_q14 = i64 // seconds in Q14 fixed-point 121type nx_cycles = i64 // CPU cycle count 122 123// ----- HASH family (non-cryptographic 64-bit; crypto = STRUCT) ----- 124// FNV-1a / xxhash digest is u64 by spec. SHA-256 / SHA-512 / BLAKE 125// hashes are MULTI-WORD; they're declared as structs in 126// nx_sha256.nx / nx_sha512.nx / nx_blake2b.nx (each carries its own 127// fixed-size byte array; NOT i64). 128type nx_hash64 = u64 // FNV-1a / xxhash / truncated SHA -- 64-bit digest 129 130// ----- ETG family (sealed enums; small value space -> u8) ----- 131// nx_outcome_id sealed enum has 11 values; u8 fits 256 132// nx_probe_kind sealed enum has 18 values; u8 fits 256 133// nx_claim_source sealed enum has 13 values; u8 fits 256 134// nx_silicon_serial is a content-addressed identity HASH; u64. 135type nx_outcome_id = u8 // NX_ETG_OUTCOME_* (11 values; u8 fits) 136type nx_probe_kind = u8 // NX_ETG_PROBE_* (18 values; u8 fits) 137type nx_claim_source = u8 // NX_ETG_CLAIM_* (13 values; u8 fits) 138type nx_silicon_serial = u64 // per-die identity hash (cryptographic-strength width) 139 140// ----- PERF family (sealed enums) ----- 141type nx_pathology_id = u8 // NX_PERF_PATH_* (15 values; u8 fits) 142type nx_flow_state_id = u8 // NX_FLOW_STATE_* (6 values; u8 fits) 143 144// ----- FIXED-POINT family (width chosen by precision*range) ----- 145// Q10: value * 1024. Typical seed values are 0..255 so q10 max is 146// ~261K; i32 holds up to ~2.1B -> plenty of headroom. 147// Q14: value * 16384. Typical max around 16K of seed -> q14 ~ 2.6e8; 148// i32 holds up to 2.1e9 -> headroom for a few decimal seconds. 149// Q20: value * 1048576. Wider precision; needs i64 to avoid wrap. 150type nx_q10 = i32 // val * 1024; ~0.001 precision 151type nx_q14 = i32 // val * 16384; ~6e-5 precision 152type nx_q20 = i64 // val * 1048576; ~1e-6 precision 153 154// ----- GRAPHICS family (display coords + color packs at real widths) ----- 155// Modern displays are well within 32-bit pixel addressing. 156// 8K display = 7680x4320 pixels. i32 holds 2.1B -> plenty. 157// nx_color_rgba8 = 32-bit packed RGBA (the common case) 158// nx_color_rgba16 = 64-bit packed RGBA16161616 (HDR / wide gamut) 159type nx_pixel_x = i32 // screen X in pixels 160type nx_pixel_y = i32 // screen Y in pixels 161type nx_color_rgba8 = u32 // RGBA8888 packed 162type nx_color_rgba16 = u64 // RGBA16161616 packed (HDR / preserve-all) 163 164// ----- PERCEPTUAL family (sealed enum; small value space) ----- 165// nx_perceptual_profile has ~40 declared values up through 166// NX_PERCEPT_PRESERVE_ALL = 9999. Sentinel value 9999 needs i16, 167// not u8. i16 fits -32768..32767 with room for sentinels. 168type nx_perceptual_profile = i16 // NX_PERCEPT_* (~40 values + 9999 sentinel) 169 170// ----- ADDRESS family (virtual addresses on 64-bit ISA) ----- 171// Pointer-width is u64 on all our supported 64-bit targets 172// (RV64 / x86_64 / AArch64 / ppc64le / loongarch64 / mips64 / 173// s390x / RV32 uses u32 -- TODO: tier-conditional). 174type nx_addr = u64 // raw virtual address (caller casts to *u8) 175 176// nx_capability_manifest: 177// variant_class: tier_config 178// variant_id: tier_config_v1_global 179// requires_isa: [rv32i, rv32imac, rv64imac, rv64imacv, x86_64, aarch64, armv7a, cortex_m, avr, xtensa, wasm32] 180// requires_syscalls: [] 181// requires_ram_min_b: 0 // pure-const + typedef module, no runtime cost 182// tier_floor: NX_TIER_MCU 183// tier_ceiling: NX_TIER_HPC 184// cost_model: 185// flops_per_n: 0.0 186// bytes_per_n: 0.0 187// syscalls_per_n: 0.0 188// adversary_class: THREAT_OPPORTUNISTIC 189// 190// Note: This file is the substrate's TIER ENUM SOURCE OF TRUTH. It 191// has no variants by design (it IS the variant_class taxonomy that 192// other primitives' tier_floor / tier_ceiling reference). Manifest 193// declared for hygiene completeness; selector will skip it. 194 195// ---- buffer-size constants (use instead of bare numbers) ------- 196 197const NX_BUF_TINY: nx_size = 64 198const NX_BUF_SMALL: nx_size = 256 199const NX_BUF_MEDIUM: nx_size = 4096 200const NX_BUF_LARGE: nx_size = 65536 201const NX_BUF_HUGE: nx_size = 1048576 202 203// ---- hardware tier sentinels ----------------------------------- 204 205const NX_TIER_MCU: nx_int = 0 206const NX_TIER_SOVEREIGN_CHIP: nx_int = 1 207const NX_TIER_FAMILY_DEVICE: nx_int = 2 208const NX_TIER_WORKSTATION: nx_int = 3 209const NX_TIER_SERVER: nx_int = 4 210const NX_TIER_HPC: nx_int = 5 211 212// ---- numeric tier sentinels (informational) -------------------- 213 214const NX_NUM_N0_I32: nx_int = 0 215const NX_NUM_N1_I64: nx_int = 1 216const NX_NUM_N2_I128: nx_int = 2 217const NX_NUM_N3_I256: nx_int = 3 218const NX_NUM_N4_I512: nx_int = 4 219const NX_NUM_N5_BIGINT: nx_int = 5 220 221// ---- byte-width of substrate types (replace bare `8` / `4`) ---- 222// 223// Use these wherever you need the byte count of a substrate type -- 224// e.g., sys_mmap(N * NX_SIZEOF_NX_SIZE) to allocate N nx_size slots. 225// Swap nx_int's underlying type and ONLY this constant changes. 226 227const NX_SIZEOF_NX_INT: nx_size = 8 // nx_int currently i64 -> 8 bytes 228const NX_SIZEOF_NX_SIZE: nx_size = 8 // nx_size always pointer-width 229const NX_SIZEOF_NX_IDX: nx_size = 8 // nx_idx alias of nx_size 230 231// ---- POSIX stdio file descriptors (replace bare 0/1/2) --------- 232 233const NX_FD_STDIN: nx_fd = 0 234const NX_FD_STDOUT: nx_fd = 1 235const NX_FD_STDERR: nx_fd = 2