Fix deprecated chrono APIs and add syntax documentation (#201)

* Complete Phase 2c: Comprehensive GC Performance Metrics and Telemetry

This commit completes the comprehensive GC performance monitoring system with:

## Performance Metrics System
- `GCMetrics` with 5 detailed metric categories:
  - Collection timing and frequency tracking
  - Memory allocation rate and pattern analysis
  - Block utilisation and fragmentation metrics
  - Emergency collection performance monitoring
  - High-level performance counters and health indicators

## Zero-Overhead Design
- Metrics updates only in debug builds (`#[cfg(debug_assertions)]`)
- On-demand calculation of derived metrics to avoid hot path costs
- Lightweight allocation counter updates for testing and development

## Comprehensive Tracking
- Allocation rates (bytes/objects per second)
- Size class distribution monitoring
- Fragmentation analysis and waste calculation
- GC overhead percentages and health scoring
- Emergency collection success rates and timing

## Testing and Validation
- Unit test `test_gc_performance_metrics` validates metric accuracy
- Integration with existing allocation and collection cycles
- All existing tests continue to pass
- Clean compilation with zero warnings in metrics code

This establishes excellent observability for GC behaviour in production and provides
the foundation for performance-based collection strategy decisions in future phases.

Status: Phase 2c complete - ready for Phase 3 (fragmentation detection)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix allocation hot path performance regression

- Feature-gate allocation counters with gc-telemetry feature flag
- Restore zero-overhead principle for release builds
- Maintain full telemetry capabilities when explicitly enabled
- Verified 8.4% allocation performance improvement vs baseline

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Add gc-telemetry feature flag and apply formatting

- Add proper feature flag definition to Cargo.toml
- Apply cargo fmt formatting fixes
- All clippy checks now pass cleanly
- Ready for final PR

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix deprecated chrono APIs and clean up warnings

- Update chrono FixedOffset::east/west to east_opt/west_opt APIs
- Remove unused mut variable in collect.rs test
- Add docs/syntax-gotchas.md documenting precedence issues

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: gmorpheme

docs/syntax-gotchas.md

@@ -0,0 +1,83 @@
+# Syntax Gotchas
+
+This document records unintuitive consequences of Eucalypt's syntax design decisions that can lead to subtle bugs or confusion. These are documented here until such time as we can implement a linter or improve error messages to catch them more clearly.
+
+## Operator Precedence Issues
+
+### Field Access vs Catenation
+
+**Problem**: The lookup operator (`.`) has higher precedence (90) than catenation (precedence 20), which can lead to unexpected parsing.
+
+**Gotcha**: Writing `objects head.id` is parsed as `objects (head.id)` rather than `(objects head).id`.
+
+**Example**:
+```eu
+# This doesn't work as expected:
+objects: range(0, 5) map({ id: _ })
+result: objects head.id  # Parsed as: objects (head.id)
+
+# Correct syntax requires parentheses:
+result: (objects head).id  # Explicitly groups the field access
+```
+
+**Error Message**: When this occurs, you may see confusing errors like:
+- `cannot return function into case table without default`
+- `bad index 18446744073709551615 into environment` (under memory pressure)
+
+**Solution**: Always use parentheses to group the expression you want to access fields from:
+- Use `(expression).field` instead of `expression target.field`
+- Be explicit about precedence when combining catenation with field access
+
+**Reference**: Operator precedences are defined in `src/core/metadata.rs:165-186`:
+- `lookup` (`.`): precedence 90
+- `cat` (catenation): precedence 20
+
+## Anaphora and Function Syntax
+
+### Lambda Syntax Does Not Exist
+
+**Problem**: Eucalypt does not have lambda expressions like other functional languages.
+
+**Gotcha**: Attempting to write lambda-style syntax will cause syntax errors.
+
+**Invalid Examples**:
+```eu
+# These syntaxes DO NOT exist in Eucalypt:
+map(\x -> x + 1)     # Invalid
+map(|x| x + 1)       # Invalid  
+map(fn(x) => x + 1)  # Invalid
+map(λx.x + 1)        # Invalid
+```
+
+**Correct Approach**: Use anaphora (`_`, `_0`, `_1`, etc.) or define named functions:
+```eu
+# Using anaphora:
+map(_ + 1)
+
+# Using named function:
+add-one(x): x + 1
+map(add-one)
+
+# Using block with anaphora for complex expressions:
+map({ result: _ + 1, doubled: _ * 2 })
+```
+
+**Reference**: See `docs/anaphora-and-lambdas.md` for detailed explanation of anaphora usage.
+
+## Future Improvements
+
+These gotchas highlight areas where the language could benefit from:
+
+1. **Better Error Messages**: More specific error messages when precedence issues occur
+2. **Linting Rules**: Static analysis to catch common precedence mistakes  
+3. **IDE Support**: Syntax highlighting and warnings for ambiguous expressions
+4. **Documentation**: Better examples showing correct precedence usage
+
+## Contributing
+
+When you encounter a new syntax gotcha, please add it to this document with:
+- A clear description of the problem
+- Example of incorrect usage
+- Example of correct usage  
+- The error message(s) that result
+- Reference to relevant code or documentation

src/eval/memory/collect.rs

@@ -264,7 +264,7 @@ pub mod tests {
     pub fn test_per_heap_mark_state_isolation() {
         // Test that each heap has its own independent mark state
         let mut heap1 = Heap::new();
-        let mut heap2 = Heap::new();
+        let heap2 = Heap::new();
         let mut clock = Clock::default();
         clock.switch(ThreadOccupation::Mutator);
 

src/eval/stg/time.rs

@@ -421,13 +421,19 @@ pub mod tests {
     pub fn test_tz_parse() {
         assert_eq!(
             offset_from_tz_str("-02:00").unwrap(),
-            FixedOffset::east(2 * 60 * 60)
+            FixedOffset::east_opt(2 * 60 * 60).unwrap()
         );
         assert_eq!(
             offset_from_tz_str("+02:00").unwrap(),
-            FixedOffset::west(2 * 60 * 60)
+            FixedOffset::west_opt(2 * 60 * 60).unwrap()
+        );
+        assert_eq!(
+            offset_from_tz_str("UTC").unwrap(),
+            FixedOffset::east_opt(0).unwrap()
+        );
+        assert_eq!(
+            offset_from_tz_str("Z").unwrap(),
+            FixedOffset::east_opt(0).unwrap()
         );
-        assert_eq!(offset_from_tz_str("UTC").unwrap(), FixedOffset::east(0));
-        assert_eq!(offset_from_tz_str("Z").unwrap(), FixedOffset::east(0));
     }
 }