This directory contains session-based field notes and curated gotchas for the Ruff programming language.

Always read GOTCHAS.md first - it contains the highest-signal, most important pitfalls.

This directory contains field notes from AI agent work sessions on the Ruff programming language.

These notes capture:

• Surprising behavior and gotchas
• Incorrect assumptions that led to bugs
• Design decisions that aren't obvious from code alone
• Debugging techniques that worked
• Lessons learned for future work

This is operational memory, not documentation.

• FIELD_NOTES_SYSTEM.md - Mandatory workflow and template for post-work field notes
• GOTCHAS.md - Start here! Curated list of the most important non-obvious pitfalls
• Session notes below - Raw, chronological records of each work session

• 2026-03-25_06-50_ssg-rayon-in-iterator-aggregation-reduction.md — ✅ COMPLETED: Replaced per-file result-vector buffering in ssg_run_rayon_read_render_write(...) with in-iterator Rayon try_fold/try_reduce aggregation, added partitioned large-batch checksum/failure-surfacing regressions, and documented Rust closure Result type-inference gotcha (E0282/E0283) plus cargo single-test-filter command-shape gotcha.

• 2026-03-19_07-47_ssg-rayon-pool-cache-and-timing-test-stability.md — ✅ COMPLETED: Added cached CPU-bounded Rayon pool reuse for ssg_run_rayon_read_render_write(...), added pool-cache regression coverage, synchronized CHANGELOG/ROADMAP/README, and stabilized a flaky full-suite cumulative-timing assertion by switching to deterministic checksum-growth + non-negative timing contracts.

• 2026-03-18_ssg-bufwriter-render-alloc-elimination.md — ✅ COMPLETED: Eliminated per-file intermediate String allocation in ssg_run_rayon_read_render_write Rayon render+write hot path by replacing String::with_capacity + 3× push_str + std::fs::write with pre-sized BufWriter<File> + 3× write_all + flush. Removes 10,000 per-file ~200–300 byte heap allocations from the hot path in a 10K-file SSG benchmark run. Added 4 regression tests covering exact HTML structure, byte-accurate checksum, write-failure propagation, and Unicode byte-accuracy. Synchronized CHANGELOG/ROADMAP/README.

• 2026-03-18_ssg-rayon-cpu-bounded-pool.md — ✅ COMPLETED: Added ssg_rayon_cpu_cap() helper and capped ThreadPoolBuilder thread count at min(concurrency_limit, available_parallelism).max(1) in ssg_run_rayon_read_render_write. Prevents thread over-subscription when concurrency_limit (e.g. 256 default) far exceeds CPU count. Added 4 regression tests covering floor guarantee, oversized-limit correctness, small-limit correctness, and exact-CPU boundary. Synchronized CHANGELOG/ROADMAP/README.

• 2026-03-17_23-18_ssg-single-pass-rayon-pipeline.md — ✅ COMPLETED: Replaced two-phase Rayon pipeline (Phase 1 reads barrier → Phase 2 render+writes) with a single-pass per-file read+render+write Rayon pipeline in ssg_run_rayon_read_render_write. Eliminates Phase 1→Phase 2 barrier, reduces peak memory (at most K files in RAM at once vs N), and enables read/write overlap. read_ms/render_write_ms now report cumulative per-task CPU sums rather than wall-clock phase durations. Added 4 regression tests for single-pass behavioral contracts. Synchronized CHANGELOG/ROADMAP/README.

• 2026-03-17_18-53_ssg-rayon-parallel-pipeline.md — ✅ COMPLETED: Replaced Tokio FuturesUnordered pipeline in ssg_read_render_and_write_pages(...) with spawn_blocking + Rayon par_iter two-phase pipeline (Phase 1: parallel reads, Phase 2: parallel HTML render + std::fs::write). Removed unused VecDeque import, moved 4 test-only scheduling helpers to #[cfg(test)], added 5 regression tests, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-17_12-35_ssg-single-worker-overlap-prefetch-lane.md — ✅ COMPLETED: Optimized fused SSG single-worker (concurrency_limit=1) path to overlap bounded read/write progression with explicit prefetch gating, added focused policy + index-mapping regressions, and synchronized CHANGELOG/ROADMAP/README updates.

• 2026-03-17_12-19_ssg-single-worker-fast-path.md — ✅ COMPLETED: Added dedicated single-worker (concurrency_limit=1) SSG write-pipeline lanes with preserved checksum/file-count/stage-metric contracts and synchronized CHANGELOG/ROADMAP/README updates.

• 2026-03-17_12-17_ssg-combined-precompute-pass.md — ✅ COMPLETED: Fused SSG output-path + HTML-prefix batch precompute into one helper pass, migrated both SSG write pipelines to it, added helper regressions, and captured warning-hygiene gotcha for test-only legacy helpers.

• 2026-03-16_17-08_bench-ssg-mean-median-drift-warnings.md — ✅ COMPLETED: Added bench-ssg mean/median drift warning signals (7.5% threshold, >=3 measured-run gate), wired CLI measurement-quality warning output, added comprehensive benchmark drift-warning contracts, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-16_16-58_ssg-vectored-write-byte-accounting.md — ✅ COMPLETED: Tightened ssg_write_rendered_html_page(...) to return observed vectored write-byte totals directly, added focused ASCII/UTF-8 writer byte-accounting regression coverage, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-16_16-23_ssg-checksum-write-result-accounting.md — ✅ COMPLETED: Moved SSG checksum accounting to write-result byte counts in ssg_render_and_write_pages(...) and ssg_read_render_and_write_pages(...), added Unicode checksum regression coverage, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-16_16-21_bench-ssg-trend-drift-warnings.md — ✅ COMPLETED: Added bench-ssg trend-drift warning signals (10% threshold, >=3 measured-run gate), wired CLI warning presentation, added comprehensive benchmark warning contract tests, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-15_18-37_bench-ssg-measurement-quality-signals.md — ✅ COMPLETED: Added bench-ssg measurement-quality signals with CV-based variability warnings plus first-to-last measured-run trend reporting, expanded benchmark contract coverage, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-15_17-53_bench-ssg-warmup-series-contracts.md — ✅ COMPLETED: Added bench-ssg --warmup-runs support via shared warmup+measured series orchestration, added comprehensive warmup/measured failure-surfacing contracts, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-15_16-38_ssg-precomputed-prefix-and-test-stability.md — ✅ COMPLETED: Precomputed per-index HTML prefixes for fused streamed SSG write workers, added large-index heading regression coverage, and stabilized a full-suite-only direct writer contract test timing edge.

• 2026-03-15_15-41_bench-ssg-local-resource-contention-interpretation.md — ✅ COMPLETED: Re-ran SSG comparison with stable reduced-script runs, captured before/after medians, and documented local resource contention as a benchmark-interpretation caveat.

• 2026-03-15_14-32_ssg-output-path-precompute-follow-through.md — ✅ COMPLETED: Optimized ssg_render_and_write_pages(...) and ssg_read_render_and_write_pages(...) to precompute/reuse indexed output paths per batch, added output-path + high-volume low-concurrency regression contracts, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-13_16-37_ssg-read-write-streaming-follow-through.md — ✅ COMPLETED: Streamed fused SSG read completions directly into bounded render/write workers (ssg_read_render_and_write_pages) to remove full read-stage buffering, added empty-input + single-worker regression contracts, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-12_10-43_ssg-read-render-write-fusion-follow-through.md — ✅ COMPLETED: Added fused async native SSG read+render+write helper (ssg_read_render_and_write_pages), migrated timed bench-ssg Ruff path to consume helper stage metrics, expanded contract coverage (checksum/file-count + read/write failures), and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-12_05-20_ssg-render-write-pipeline-optimization.md — ✅ COMPLETED: Optimized ssg_render_and_write_pages(...) by removing serial pre-render buffering and rendering inside bounded async write workers, added checksum+empty-input regression contracts, and synchronized CHANGELOG/ROADMAP/README.

• 2026-03-12_04-05_bench-ssg-command-failure-contracts.md — ✅ COMPLETED: Hardened bench-ssg command-level failure contracts with deterministic missing-script preflight errors plus comprehensive harness tests for missing metrics and checksum mismatch; synchronized CHANGELOG/ROADMAP/README.

• 2026-03-12_03-10_bench-ssg-tmp-dir-override.md — ✅ COMPLETED: Added bench-ssg --tmp-dir artifact-root override, propagated shared tmp-root contract through Ruff/Python benchmark scripts via RUFF_BENCH_SSG_TMP_DIR, added tmp-dir override validation coverage, and synchronized CHANGELOG/ROADMAP/README updates.

• 2026-03-12_00-27_ssg-render-write-fusion.md — ✅ COMPLETED: Added fused async native SSG render+write helper (ssg_render_and_write_pages), migrated bench-ssg timed render/write stage to the helper, expanded success/error dispatcher contracts, and documented commit-scope + output-dir contract gotchas.

• 2026-02-17_18-48_io-strict-arity-hardening.md — ✅ COMPLETED: Hardened advanced io_* APIs to enforce strict arity (reject trailing args), added comprehensive module+dispatcher extra-argument rejection coverage, synchronized CHANGELOG/ROADMAP/README, and documented cargo single-filter command-shape plus compatibility-message preservation gotchas.

• 2026-02-16_20-23_release-hardening-strict-arity-follow-through-slices.md — ✅ COMPLETED: Delivered iterative v0.10 P1 strict-arity hardening slices for assertion/testing, conversion+introspection, math, and data-format/base64 APIs with module+dispatcher coverage, synchronized roadmap/changelog/readme updates, and captured fallback-contract preservation + cargo single-filter test-command gotchas.

• 2026-02-16_18-09_optional-static-typing-design-package.md — ✅ COMPLETED: Delivered the v0.10 exploratory optional static typing design package (docs/OPTIONAL_TYPING_DESIGN.md) covering annotation surface, optional runtime type-check contract, typed-JIT boundaries, migration/non-goal decisions, and synchronized roadmap/changelog/readme status.

• 2026-02-16_17-28_release-hardening-array-higher-order-collection-contracts.md — ✅ COMPLETED: Hardened strict-arity contracts for core array and higher-order collection APIs, added comprehensive module+dispatcher contract coverage, synchronized roadmap/changelog/readme, and documented matches! partial-move plus fixture-brittleness gotchas.

• 2026-02-16_16-12_release-hardening-safe-probe-input-exit.md — ✅ COMPLETED: Removed remaining exhaustive declared-builtin dispatch probe gap by safely probing input/exit via deterministic contract-error paths (no blocking/termination), synchronized roadmap/changelog/readme wording, and documented safe-probe vs skip-list gotcha plus patch-anchor recovery workflow.

• 2026-02-16_12-34_release-hardening-db-process-zip-strict-arity-contracts.md — ✅ COMPLETED: Hardened v0.10.0 P1 strict-arity contracts for database (db_*), process (spawn_process, pipe_commands), and archive (zip_*, unzip) APIs; added comprehensive module+dispatcher extra-argument rejection coverage; synchronized roadmap/changelog/readme; documented cargo test single-filter + moved-value assertion gotchas.

• 2026-02-16_11-54_release-hardening-network-strict-arity-contracts.md — ✅ COMPLETED: Hardened v0.10.0 P1 declared TCP/UDP APIs with explicit strict-arity guards, added comprehensive extra-argument rejection contracts, synchronized roadmap/changelog/readme, and documented formatter spillover + positional-arity gotchas.

• 2026-02-16_10-37_release-hardening-filesystem-strict-arity-contracts.md — ✅ COMPLETED: Hardened v0.10.0 P1 core filesystem API strict-arity contracts (reject trailing args), expanded dispatcher contract coverage, synchronized roadmap/changelog/readme, and documented implicit positional-match arity gotcha.

• 2026-02-16_10-15_release-hardening-crypto-strict-arity-contracts.md — ✅ COMPLETED: Hardened v0.10.0 P1 crypto/hash API strict-arity contracts (reject trailing args), expanded native+dispatcher argument-shape coverage, synchronized roadmap/changelog/readme, and documented positional-match arity gotcha.

• 2026-02-16_09-34_release-hardening-async-batch-shared-task-pool-contracts.md — ✅ COMPLETED: Added release-hardening contract coverage for async batch file wrappers (async_read_files, async_write_files) and shared/task-pool APIs (shared_*, set_task_pool_size, get_task_pool_size), synchronized roadmap/changelog/readme, and documented process-global shared-store key-isolation gotchas.

• 2026-02-16_09-42_release-hardening-async-runtime-task-channel-contracts.md — ✅ COMPLETED: Expanded v0.10.0 release-hardening dispatcher + contract coverage for async runtime/task-channel APIs (channel, async sleep/timeout/http/file wrappers, spawn/await/cancel task), synchronized roadmap/changelog/readme, and documented mutable-borrow test-shape + single-consumer task-handle gotchas.

• 2026-02-16_08-05_release-hardening-filesystem-core-contract-follow-through.md — ✅ COMPLETED: Implemented v0.10.0 P1 release-hardening filesystem core API contract follow-through (critical dispatcher coverage + full behavior/argument-shape tests), synchronized roadmap/changelog/readme, and captured shared-handler error-text + array-edit placement gotchas.

• 2026-02-16_00-46_release-hardening-set-queue-stack-contracts.md — ✅ COMPLETED: Expanded release-hardening dispatcher coverage for Set/Queue/Stack constructor+method APIs, added comprehensive behavior/argument-shape contracts, synchronized roadmap/changelog/readme, and documented cargo test single-filter command-shape gotcha.

• 2026-02-16_00-28_release-hardening-env-os-assert-follow-through.md — ✅ COMPLETED: Added release-hardening dispatcher + runtime contracts for env/system, os/path, and assertion/testing builtins; synchronized roadmap/changelog/readme; captured permissive env_bool parsing and Value::Str guard-comparison gotchas.

• 2026-02-15_23-40_release-hardening-contract-slices-continuation.md — ✅ COMPLETED: Continued iterative v0.10 release-hardening coverage for string utility/transform, random-time-date, math, and collection/format builtins; added dispatcher + behavior/fallback contracts; documented Value-comparison, format-placeholder, and async-test triage gotchas.

• 2026-02-15_22-56_release-hardening-follow-through-contract-slices.md — ✅ COMPLETED: Iteratively expanded v0.10 release-hardening contract coverage (async aliases/SSG, advanced HTTP, core aliases, polymorphic len, introspection type/is_*, conversion+bytes), documented repeated patch/formatter gotchas, and synchronized roadmap/changelog/readme per slice.

• 2026-02-15_22-01_release-hardening-load-image-network-dispatch.md — ✅ COMPLETED: Closed remaining v0.10 modular dispatch gaps for load_image and all declared TCP/UDP APIs, added comprehensive dispatcher + runtime contract coverage, and captured formatter spillover + drift-ledger synchronization gotchas.

• 2026-02-15_20-53_set-constructor-dispatch-hardening.md — ✅ COMPLETED: Closed v0.10 release-hardening modular dispatch gap for declared Set(...) constructor, added constructor-shape + dedup contract coverage, and documented drift-ledger synchronization rules.

• 2026-02-15_20-13_crypto-dispatch-hardening.md — ✅ COMPLETED: Closed v0.10 release-hardening modular dispatch gap for declared crypto/hash APIs (SHA/MD5, bcrypt, AES, RSA), added comprehensive native + dispatcher contract coverage, and documented hash-vector verification + migration-ledger synchronization gotchas.

• 2026-02-15_20-03_process-dispatch-hardening.md — ✅ COMPLETED: Closed v0.10 release-hardening modular dispatch gap for process APIs (spawn_process, pipe_commands), added comprehensive native + dispatcher contract coverage, and documented commit-scoping/known-gap synchronization gotchas.

• 2026-02-15_17-13_release-hardening-modular-dispatch-gap-closures.md — ✅ COMPLETED: Closed iterative v0.10 release-hardening modular dispatch gaps for string polymorphic APIs (contains/index_of), advanced io_*, declared HTTP APIs, and declared db_* APIs; added module+dispatcher contract coverage and captured migration-ledger + SQLite-first DB testing gotchas.

• 2026-02-15_16-17_release-hardening-dispatch-gap-slices.md — ✅ COMPLETED: Implemented iterative v0.10 dispatch hardening slices (par_each contract expansion, exhaustive drift guard + safe probe policy, modular migration of system env/args APIs, data-format/encoding APIs, and regex APIs), added targeted regression coverage, and documented migration-ledger testing rules.

• 2026-02-15_09-51_release-hardening-native-dispatch-contract.md — ✅ COMPLETED: Hardened v0.10.0 native dispatcher behavior by replacing silent unknown-native fallback with explicit runtime errors, added dispatcher-level regression coverage for high-risk recently added builtins, and documented dual-target test-output expectations.

• 2026-02-15_11-30_release-hardening-argument-shape-contract.md — ✅ COMPLETED: Implemented v0.10.0 release-hardening API argument-shape contract updates for filesystem aliases (join_path/path_join) and collection size APIs (queue_size/stack_size), added async/filesystem/collections regression coverage, and documented runtime error short-circuit testing gotcha.

• 2026-02-15_09-18_release-hardening-alias-api-contract.md — ✅ COMPLETED: Hardened v0.10.0 API stability by fixing builtin declaration/dispatch drift, restoring missing OS/path + queue/stack API handlers in modular native functions, adding alias/API contract integration coverage, and documenting silent unknown-native fallback risks.

• 2026-02-15_08-36_native-ssg-render-builtin-optimization.md — ✅ COMPLETED: Implemented native bulk SSG page rendering (ssg_render_pages) to offload interpreter render-loop overhead, added comprehensive native-function tests, updated benchmark harness/docs/roadmap, and documented benchmark-variability measurement gotchas.

• 2026-02-14_17-08_spawn-parent-binding-snapshot-concurrency.md — ✅ COMPLETED: Implemented spawn transferable parent-binding snapshots for worker visibility, added integration tests for captured inputs + parent write-back isolation, updated roadmap/changelog/readme, and captured transferability/write-through gotchas.

• 2026-02-14_13-09_shared-thread-safe-value-ops.md — ✅ COMPLETED: Implemented P0 thread-safe shared value operations (shared_set/get/has/delete/add_int) for spawn coordination, added comprehensive integration coverage, updated roadmap/changelog/readme, and captured spawn-isolation + test short-circuit gotchas.

• 2026-02-14_10-10_promise-cache-reuse-and-parallel-map-overhead.md — ✅ COMPLETED: Implemented cache-aware Promise reuse in Promise.all(...)/parallel_map(...), eliminated synthetic Promise wrapping for immediate mapper results, added integration coverage for repeated-await reuse, and captured receiver-consumption gotchas.

• 2026-02-13_23-03_bench-ssg-harness-and-cwd-tmp-gotchas.md — ✅ COMPLETED: Added bench-ssg cross-language async SSG benchmark harness (Ruff + Python), implemented parser/validator + tests, documented roadmap/changelog/readme updates, and captured CWD + workspace-tmp gotchas.

• 2026-02-13_19-45_vm-cooperative-scheduler-rounds.md — ✅ COMPLETED: Implemented cooperative VM scheduler APIs (run_scheduler_round, run_scheduler_until_complete, pending_execution_context_count), added comprehensive scheduler tests (pending/completion/error paths), and documented milestone updates in roadmap/changelog/readme.

• 2026-02-13_19-31_vm-cooperative-await-yield-resume.md — ✅ COMPLETED: Implemented async VM Option 1 milestones for suspendable execution (VmExecutionSnapshot), execution context switching (VmContextId lifecycle/switch APIs), and cooperative Await yield/resume (execute_until_suspend / resume_execution_context) with comprehensive VM coverage and roadmap/docs updates.

• 2026-02-13_18-52_bench-cross-cwd-gotcha.md — ✅ COMPLETED: Reproduced bench-cross failure from non-root working directory, confirmed CWD-relative default path resolution, and documented safe invocation + prevention guidance.

• 2026-02-13_18-31_parallel-map-jit-closures-and-rayon.md — ✅ COMPLETED: Implemented roadmap Option 3 iterator execution upgrades (rayon fast path + VM/JIT bytecode-closure lane for parallel_map/par_map), added targeted coverage, documented trap-prone JIT negative-test constraints, and updated roadmap/changelog/readme.

• 2026-02-12_18-19_promise-all-large-array-optimization.md — ✅ COMPLETED: Implemented P0 Promise.all/await_all large-array optimization by replacing per-promise await-task spawning with bounded in-task polling, added high-volume integration tests, and updated roadmap/changelog/readme status.

• 2026-02-12_16-35-configurable-task-pool-sizing.md — ✅ COMPLETED: Implemented P0 configurable async task pool sizing defaults (set_task_pool_size / get_task_pool_size), wired default batching through promise_all/await_all/parallel_map, added comprehensive unit+integration coverage, and captured test-harness error-path gotchas.

• 2026-02-12_16-17_commit-grouping-and-field-notes-ops.md — ✅ COMPLETED: Isolated a large formatting-heavy working tree into subsystem-scoped commits (benchmarks/examples, interpreter runtime, JIT, CLI/error/tests), validated clean history, and captured new operational gotchas for commit hygiene.

• 2026-02-12_15-33-await-all-batching-and-jwt-provider-fix.md — ✅ COMPLETED: Implemented P0 async quick-win batching (promise_all/await_all with optional concurrency limit), fixed missing await_all builtin registration, added integration coverage, and resolved full-suite JWT failures by pinning jsonwebtoken provider feature (rust_crypto).

• 2026-02-12_14-52_hashmap-fusion-jit-sealing-release.md — ✅ COMPLETED: Hashmap performance fusion + JIT sealing stability + v0.9.0 release prep. Added fused map opcodes in bytecode/compiler/VM, fixed Cranelift sealing regressions in src/jit.rs, validated with full build/tests/benchmarks, and finalized release metadata/tag push.

• 2026-01-27_phase4e-jit-benchmarking.md — ✅ COMPLETED: Phase 4E JIT Performance Benchmarking & Validation (v0.9.0). Added 7 micro-benchmark tests + infrastructure validation test. Created 5 real-world benchmark programs. Validated all Phase 4 subsystems: type profiling (11.5M obs/sec), guard generation (46µs per guard), cache lookups (27M/sec), specialization (57M decisions/sec). Phase 4 now 100% complete! ~3 hours implementation time. 3 commits, 198 tests passing.

• 2026-01-26_vm-exception-handling.md — ✅ COMPLETED: VM Exception Handling Implementation (v0.9.0 Phase 1). Implemented full exception handling in bytecode VM with BeginTry/EndTry/Throw/BeginCatch/EndCatch opcodes. Added exception handler stack for proper unwinding. Critical lesson: chunk restoration during call frame unwinding. Comprehensive test suite (9 scenarios). VM/interpreter parity achieved. ~3 hours implementation time.

• 2026-01-26_interpreter-modularization-phase2.md — ✅ PHASE 2 COMPLETE: Interpreter Modularization. Extracted ControlFlow enum (22 lines) to control_flow.rs and test framework (230 lines) to test_runner.rs. Reduced mod.rs from 14,285 to 14,071 lines (additional -214 lines). Total reduction: -731 lines from original 14,802 (~5%). Documented key decisions: why call_native_function_impl and register_builtins must stay in impl block. Clarified that remaining size is appropriate. Zero warnings, all tests passing.

• 2026-01-26_14-30_interpreter-modularization-gotchas.md — ✅ FIELD NOTES: Interpreter Modularization Phase 1. Captured key gotchas from extracting Value/Environment modules: why 5,700-line function must stay in impl block, circular type dependencies pattern, pub use re-exports, mental models about line counts vs maintainability.

• 2026-01-26_interpreter-modularization-phase1.md — ✅ PHASE 1 COMPLETE: Interpreter Modularization. Extracted Value enum (500 lines) to value.rs and Environment struct (110 lines) to environment.rs. Reduced mod.rs from 14,802 to 14,285 lines. Zero warnings, all tests passing. Comprehensive technical documentation.

• 2026-01-26_interpreter-modularization-foundation.md — ✅ FOUNDATION COMPLETE: Interpreter Modularization v0.9.0 Foundation (~15% of Task #27). Created src/interpreter/ module structure, moved interpreter.rs to interpreter/mod.rs. Created comprehensive docs/ARCHITECTURE.md (595 lines) documenting current structure and refactoring strategy. Updated ROADMAP and CHANGELOG. Next: Extract Value enum and Environment struct. Zero regressions, all code compiles successfully.

• 2026-01-25_testing-framework-foundation.md — 🚧 IN PROGRESS: Built-in Testing Framework Foundation. Implemented syntax support (lexer, AST, parser) and 4 assertion functions (assert_equal/true/false/contains). Test runner and CLI integration remain to be completed (~40% complete, ~4 days remaining).

• 2026-01-25_io-module-implementation.md — ✅ COMPLETED: Standard Library Expansion Milestone 3 (IO Module). Implemented 9 advanced binary I/O functions: io_read_bytes, io_write_bytes, io_append_bytes, io_read_at, io_write_at, io_seek_read, io_file_metadata, io_truncate, io_copy_range. Offset-based file access, comprehensive metadata, zero-copy range operations. Added 20 test cases (37 assertions, 100% pass rate) and 9 real-world examples (271 lines). Production-ready with full documentation. Completes third major stdlib milestone.

• 2026-01-25_vm-performance-optimization.md — ✅ MAJOR MILESTONE: VM Native Function Integration Complete. Extended VM from 3 to 180+ built-in functions via interpreter delegation. Zero code duplication achieved through composition pattern. Created comprehensive test suite and 7 benchmark programs. Discovered VM loop execution bug blocking performance validation. 70% of VM Performance Optimization milestone complete. Production-ready for non-loop code.

• 2026-01-25_os-path-modules.md — ✅ COMPLETED: Standard Library Expansion Milestone 2 (OS and Path modules). Implemented 9 new built-in functions: os_getcwd/chdir/rmdir/environ, path_join/absolute/is_dir/is_file/extension. Added 52 comprehensive tests and 15 detailed examples (615 lines). Discovered type() introspection issue with Error values. Updated CHANGELOG, ROADMAP, README. Production-ready with full documentation.

• 2026-01-25_stdlib-expansion.md — ✅ COMPLETED: Standard Library Expansion Milestone 1 (compression, hashing, process management). Implemented 10 new built-in functions: zip_create/add_file/add_dir/close/unzip, sha256/md5/md5_file, hash_password/verify_password, spawn_process/pipe_commands. Added comprehensive tests (236 lines) and examples (617 lines). Updated CHANGELOG, ROADMAP, README. Production-ready with full documentation.

• 2026-01-25_23-15_arg-parser-implementation.md — ✅ COMPLETED: Argument Parser (arg_parser) for CLI tools. Implemented fluent API for building professional command-line interfaces with flags, options, type validation, help generation. Supports bool/string/int/float types, required/optional, defaults, short/long forms. All tests passing.

• 2026-01-25_22-00_compiler-warnings-cleanup.md — ✅ COMPLETED: Compiler Warnings Cleanup. Reduced clippy warnings from 271 to 30 (89% reduction). Fixed 179 .get(0), 27 needless_borrow, 21 doc comment spacing, 6 redundant closures, 6 unnecessary casts. All 208 tests passing.

• 2026-01-25_20-00_bytecode-compiler-vm-foundation.md — 🚧 IN PROGRESS: Bytecode Compiler & VM Foundation for v0.8.0. Implemented complete OpCode instruction set (60+ instructions), AST-to-bytecode compiler, and stack-based VM. Foundation complete, function calls need refinement. Compiles successfully.

• 2026-01-25_18-00_enhanced-collections-implementation.md — ✅ COMPLETED: Enhanced Collection Methods for v0.8.0. Implemented 20 new array/dict/string methods: chunk, flatten, zip, enumerate, take, skip, windows, invert, update, get_default, pad_left/right, lines, words, str_reverse, slugify, truncate, to_camel/snake/kebab_case. All tests passing.

• 2026-01-25_17-30_result-option-types-COMPLETED.md — ✅ COMPLETED: Result<T, E> and Option types with Ok/Err/Some/None/Try. Fixed critical lexer bug (keywords vs identifiers). All 208 tests pass.

• 2026-01-25_17-00_result-option-types-with-bug.md — Implemented Result<T, E> and Option types with Ok/Err/Some/None/Try, but pattern matching has critical hang bug that needs debugging.

• 2026-01-25_16-00_enhanced-error-messages.md — Implemented enhanced error messages with Levenshtein "Did you mean?" suggestions, help/note context, and multiple error reporting for v0.8.0.

• 2026-01-25_14-30_destructuring-spread-implementation.md — Implemented destructuring patterns and spread operators for v0.8.0. Added Pattern enum, ArrayElement/DictElement enums, updated lexer/parser/interpreter/type-checker. 30 tests created.

1. Before starting work: Read GOTCHAS.md to understand common pitfalls
2. During work: Reference session notes for similar tasks (use grep/search)
3. After completing work: Write new session notes following the template
4. Periodically: Update GOTCHAS.md with high-impact learnings from session notes

• One session = one timestamped markdown file
• Follow template structure strictly (see any session note for reference)
• Be specific: include file paths, function names, exact error messages
• Document "justified behavior" (moments you had to explain why something is OK)
• Update GOTCHAS.md when discovering repeated or high-impact issues