[diagnostics] add type-trace category + --diagnostics CLI flag

[cs01]

Before

Codegen type-tracking side-effects were opaque. Past refactors toward a sema-driven typed-AST stalled because we didn't know which callers actually read which types, or whether the pre-codegen annotator was even populating the cache with useful data.

After

Compiler supports --diagnostics=type-trace [--diagnostics-out=<path>] on build, run, and ir subcommands. Produces a JSONL stream of every setVariableType / getVariableType / resolveExpressionTypeRich event with compact callsite stacks. Off by default, zero cost when off.

chad ir src/chad-native.ts --diagnostics=type-trace --diagnostics-out=/tmp/t.jsonl
node scripts/analyze-diagnostics.cjs /tmp/t.jsonl

Description

• New src/diagnostics/ module: sink.ts (in-memory buffer + fs.writeFileSync flush on exit), categories.ts (CSV parser + known list), tracers.ts (traceTypeSet/Get/Rich + per-category enable flags)
• CLI flags parsed in chad-node.ts and chad-native.ts, enable sink + category pre-compile
• Wired into base-generator.ts, generator-context.ts, type-inference.ts — each trace call is a one-line early-return when off
• Analyzer at scripts/analyze-diagnostics.cjs groups events by callsite, reports orphan-set ratios, top rich-query sources
• Stage 0 safe: no import aliases, no unsupported fs methods, no C bridge
• ~440 LOC

Motivation

Audit run in a scratch branch revealed that semantic/type-annotator.js already fires 44,301 rich-resolver queries per compile with zero null results — the pre-codegen cache is fully populated. The isStableExprType gate refuses to serve most of it. 64.7% of setVariableType calls are orphans (no subsequent read). These findings reshape the refactor path in #640 — future PRs can cite numbers from this trace instead of guessing. See #640 for the data-driven plan this enables.

[github-actions]

Benchmark Results (Linux x86-64)

Benchmark	C	ChadScript	Go	Node	Place
Cold Start	0.9ms	0.8ms	1.2ms	27.4ms	🥇
Fibonacci	0.814s	0.763s	1.560s	3.203s	🥇
Hash Map Lookup	0.094s	0.064s	0.092s	0.118s	🥇
Binary Trees	1.384s	1.267s	2.760s	1.185s	🥈
File I/O	0.117s	0.090s	0.084s	0.198s	🥈
JSON Parse/Stringify	0.035s	0.051s	0.178s	0.133s	🥈
N-Body Simulation	1.672s	2.123s	2.199s	2.384s	🥈
Regex Match	0.016s	0.005s	0.021s	0.004s	🥈
SQLite	0.052s	0.367s	0.492s	0.418s	🥈
Monte Carlo Pi	0.389s	0.410s	0.405s	2.263s	🥉
Quicksort	0.215s	0.247s	0.213s	0.262s	🥉
Sieve of Eratosthenes	0.016s	0.026s	0.020s	0.038s	🥉
String Manipulation	0.008s	0.019s	0.016s	0.037s	🥉
Matrix Multiply	0.673s	1.006s	0.609s	0.520s	#4

CLI Tool Benchmarks

Benchmark	ChadScript	grep	node	xxd	Place
Hex Dump	0.557s	—	0.994s	0.129s	🥈
Recursive Grep	0.020s	0.010s	0.104s	—	🥈