TSZ Performance Engineering
Use for performance, cache/residency, OOM/timeout/stack-overflow, counters,
benchmark regressions, and timing claims.
Rules
- Read
AGENTS.md, docs/plan/ROADMAP.md, and relevant PR/issues.
- Correctness first. Timing claims matter only for green rows or explicit
runtime/residency blockers.
- Optimize the repeated operation, not a fixture spelling.
- State invariant: cache key, invalidation/reset, request scope, fuel/cycle
behavior, residency bound, or complexity change.
- No checker-local semantic algorithms, display-string heuristics, source-text
shortcuts, name allowlists, or cross-interner
TypeId comparisons.
- Read
references/perf-mistakes.md before adding/widening caches, changing
residency, or claiming speedups.
Evidence
Use narrow, reproducible commands; wrap heavy runs.
python3 scripts/perf/cache-visibility-report.py --json
python3 scripts/perf/visited-clone-report.py --json
python3 scripts/perf/debug-print-report.py --json
python3 scripts/perf/migration_callsite_counts.py --json
python3 scripts/perf/query-perf-counters.py --json <artifact> --baseline <baseline>
scripts/safe-run.sh ./scripts/bench/perf-hotspots.sh --quick --json-file /tmp/hotspots.json
scripts/safe-run.sh ./scripts/bench/bench-vs-tsgo.sh --filter '<row>' --json-file /tmp/bench.json
scripts/bench/measure-tsz.sh --timeout 420 --json-file /tmp/m.json -- --noEmit -p <tsconfig>
Use focused compile guard or cargo nextest run -E 'test(...)' when shortest.
Do not run full conformance, emit, fourslash, or broad project suites locally.
For ad-hoc timing or perf bisects on shared boxes, use
scripts/bench/measure-tsz.sh: it snapshots the binary to an immutable
hash-verified copy (never time the live dist-fast/ path — sibling sessions
overwrite it) and records process CPU time next to wall time, so wall-only
timeouts under CPU contention are reported as unmeasured instead of slow.
See references/perf-mistakes.md and issue #13174.
Cache Checklist
- What semantic question is cached?
- What stable identity is the key? Avoid cross-file
NodeIndex and
cross-interner TypeId.
- Does the key include all behavior modes: relation, variance, freshness,
contextual typing, inference source,
any, target/module/options, request
scope, cycle/fuel, file/session generation?
- Where is reset/invalidation?
- What happens cold/disabled/order-randomized?
- Is size/residency bounded or observable?
PR/comment packet: goal (usually fast) and affected rows, invariant, exact
commands/CI, green row timing only, RSS/failure-class evidence for runtime
blockers, counter deltas, noise/caveats.
1---2name: tsz-performance-engineering3description: Use when planning, implementing, reviewing, or interpreting TSZ performance work, including benchmark regressions, cache/residency changes, timing claims, perf counters, hotspot investigations, OOM/timeout/stack-overflow blockers, or optimization PR evidence.4---56# TSZ Performance Engineering78Use for performance, cache/residency, OOM/timeout/stack-overflow, counters,9benchmark regressions, and timing claims.1011## Rules1213- Read `AGENTS.md`, `docs/plan/ROADMAP.md`, and relevant PR/issues.14- Correctness first. Timing claims matter only for green rows or explicit15 runtime/residency blockers.16- Optimize the repeated operation, not a fixture spelling.17- State invariant: cache key, invalidation/reset, request scope, fuel/cycle18 behavior, residency bound, or complexity change.19- No checker-local semantic algorithms, display-string heuristics, source-text20 shortcuts, name allowlists, or cross-interner `TypeId` comparisons.21- Read `references/perf-mistakes.md` before adding/widening caches, changing22 residency, or claiming speedups.2324## Evidence2526Use narrow, reproducible commands; wrap heavy runs.2728```bash29python3 scripts/perf/cache-visibility-report.py --json30python3 scripts/perf/visited-clone-report.py --json31python3 scripts/perf/debug-print-report.py --json32python3 scripts/perf/migration_callsite_counts.py --json33python3 scripts/perf/query-perf-counters.py --json <artifact> --baseline <baseline>34scripts/safe-run.sh ./scripts/bench/perf-hotspots.sh --quick --json-file /tmp/hotspots.json35scripts/safe-run.sh ./scripts/bench/bench-vs-tsgo.sh --filter '<row>' --json-file /tmp/bench.json36scripts/bench/measure-tsz.sh --timeout 420 --json-file /tmp/m.json -- --noEmit -p <tsconfig>37```3839Use focused compile guard or `cargo nextest run -E 'test(...)'` when shortest.40Do not run full conformance, emit, fourslash, or broad project suites locally.4142For ad-hoc timing or perf bisects on shared boxes, use43`scripts/bench/measure-tsz.sh`: it snapshots the binary to an immutable44hash-verified copy (never time the live `dist-fast/` path — sibling sessions45overwrite it) and records process CPU time next to wall time, so wall-only46timeouts under CPU contention are reported as unmeasured instead of slow.47See `references/perf-mistakes.md` and issue #13174.4849## Cache Checklist5051- What semantic question is cached?52- What stable identity is the key? Avoid cross-file `NodeIndex` and53 cross-interner `TypeId`.54- Does the key include all behavior modes: relation, variance, freshness,55 contextual typing, inference source, `any`, target/module/options, request56 scope, cycle/fuel, file/session generation?57- Where is reset/invalidation?58- What happens cold/disabled/order-randomized?59- Is size/residency bounded or observable?6061PR/comment packet: goal (usually `fast`) and affected rows, invariant, exact62commands/CI, green row timing only, RSS/failure-class evidence for runtime63blockers, counter deltas, noise/caveats.
tsz-org