Special Values Cookbook

This subsection of the guide is a focused, example-driven reference for Nitpick's special-value surface as it stands at the close of the v0.31.9.x sub-cycle (Phase 3 of the v0.31.x cycle, runtime-taint arc).

A special value is a typed inhabitant whose meaning is "the absence or the impossibility of the ordinary value": Nitpick recognises four of them, and each pairs with a specific type shape.

The four special values

Special value	Pairs with	Meaning	Cookbook chapter
`NIL`	`Optional<T>`, `NIL`-shaped slots	"value-side absence"	nil-and-null.md
`NULL`	`Pointer<T>` (`T->`)	"pointer-side absence"	nil-and-null.md
`ERR`	`tbb8` / `tbb16` / `tbb32` / `tbb64`	"arithmetic failure sentinel"	tbb-err.md
`unknown`	any binding (via taint)	"value was never determined"	unknown-and-ok.md

Each is enforced at compile time by the type checker; mixing them across type kinds is a hard error with a "did you mean the other one?" hint (D-15 in META/NITPICK/ROADMAP/0.31/AUDIT_v0.31.2.0.md).

Chapters

Immutability — fixed vs const — the Nitpick-side immutability qualifier (fixed) and the extern-only const qualifier; ARIA-044; comptime-fold interaction.
NIL and NULL — value-side vs pointer-side absence; assignment rules at both the var-decl site and at statement-level =.
tbb and ERR — the tbb sentinel bit pattern, sticky semantics on arithmetic / comparison / bitwise ops, and the D-16a "no bool ERR" convention.
unknown and ok(...) — the unknown literal, how Symbol::mayBeUnknown taints a binding, when you must wrap with ok(val), and ARIA-045.
Result<T> and fail — the implicit Result<T> wrap on every body-bearing Nitpick function, pass val vs fail(code), the .is_error / .value / .error_code accessors, and the D-20 "value reads as NIL on failure" rule.
pick exhaustiveness for special values — how the exhaustiveness checker treats Optional NIL, Pointer NULL, tbb ERR, and unknown-tainted selectors; the wildcard (*) escape hatch.
Runtime taint and T?unknown — how the is unknown boolean test, the callee-summary path, and the declared T?unknown return-flow marker interact at runtime. Landed across v0.31.9.1–v0.31.9.5.

Each chapter is short and self-contained.

Conventions used in these chapters

Examples are minimal func:main programs that compile and run with npkc.
"Nitpick-side" means "code in a .npk / .npk source file"; "C ABI surface" means "inside an extern \"lib\" { ... } block".
Diagnostics are quoted as the compiler emits them, with the ARIA-NNN code where applicable.
Where bug regressions are referenced, the fixture number is given in parentheses, e.g. (bug419).

Validation status (v0.31.9.6)

Compiler CTest non-K: PASS.
K core tests: 161/161 PASS.
K proofs: 10/10 PASS.
Phase-3 bug regressions: bug379 … bug515.
Diagnostics burned in Phase 3: ARIA-044, ARIA-045, ARIA-046, ARIA-056. Next free is ARIA-057.

Scope and non-scope

In scope as of Phase 3 + v0.31.9.x sub-cycle:

fixed Nitpick-side, const extern-only.
fixed on struct fields with mixed-mutability struct semantics (landed in v0.31.9.3, ARIA-056) — see ../types/fixed_field.md.
NIL / NULL / ERR / unknown taxonomy with hard-error cross-assignment.
ok(...) unwrap requirement for tainted bindings.
is unknown / == unknown first-class boolean test form (D-18, landed in v0.31.9.1).
T?unknown declared return-flow marker (D-17a, landed in v0.31.9.4) — see runtime_taint.md.
Result<T> shape for every body-bearing Nitpick function, including the NIL-shaped form func:f = NIL(...) { ... };.
pick exhaustiveness coverage for all four special values.

Not yet in scope (deferred to a future cycle):

Chained .is_error / .value reads directly off a Result<T>-returning call expression (DEF-CHAIN-RESULT — workaround is to bind the call to an intermediate first).