fastify 5.12.1 → 5.12.3

package/.pi/self-learning-memory/daily/2026-07-06.md

@@ -1,22 +0,0 @@
-## 15:46 UTC — Task
-
-### What went wrong
-- Interpolated `${{ inputs.package }}` directly into `actions/github-script` JavaScript, allowing malformed input to break or inject code.
-- Fetched npm metadata with the raw package name instead of URL-encoding it.
-- Assumed `data.repository.url` always existed and was a GitHub `.git` URL.
-- Used a brittle repository URL regex that missed scoped/modern GitHub URL formats and failed without a clear error.
-
-### How it was fixed
-- Pass workflow input through `env.NPM_PACKAGE` and read it from `process.env` inside the script.
-- Validate the package name with an npm package-name regex before using it.
-- Use `encodeURIComponent(packageName)` in the npm registry URL.
-- Check `response.ok` and throw explicit errors for failed registry fetches or unsupported repository URLs.
-
-## 16:04 UTC — Task
-
-### What went wrong
-- PR title did not satisfy the repository's conventional title check before opening/updating the PR.
-
-### How it was fixed
-- Renamed PR #6833 to `ci: harden CITGM package workflow input handling` using `gh pr edit`, then watched checks until `pull-request-title-check` passed.
-

package/.pi/self-learning-memory/daily/2026-07-29.md

@@ -1,50 +0,0 @@
-## 19:37 UTC — Task
-
-### What went wrong
-- Continued initiating tool work after the tool-budget warning instead of stopping to assess the existing evidence.
-- Started a test command that was aborted, leaving the primitive-coercion fix unverified.
-- Investigated Ajv internals and custom compiler compatibility without first isolating the exact failing repository behavior.
-- Did not establish regression coverage for missing schemaEnv handling and root primitive coercion before changing direction.
-
-### How it was fixed
-- Honor soft tool-budget and interruption signals immediately; stop browsing and provide a bounded reflection.
-- Run only the single highest-value targeted test before the budget limit, then report if execution is blocked.
-- Reproduce root primitive coercion with the repository’s actual validatorCompiler path rather than relying on Ajv internals alone.
-- Add focused tests covering custom validator compilation, schemaEnv availability, and root primitive coercion.
-
-## 20:03 UTC — Task
-
-### What went wrong
-- Root primitive request values were validated without a parent reference, so Ajv coercion changed only its local value and left request.body as a string.
-- Test command output was misread: Borp ran the broader suite despite a specific file argument, making targeted coverage unclear.
-
-### How it was fixed
-- Pass request and parameter metadata as Ajv parentData/parentDataProperty so root coercions update the original request value.
-- Add a regression test asserting quoted numeric JSON becomes a number in the handler while out-of-range values remain rejected.
-- Verify targeted test execution separately from the full suite to avoid mistaking aggregate counts for focused coverage.
-
-## 20:06 UTC — Task
-
-### What went wrong
-- Ajv was called with a primitive root value without parentData context, so coerced values were not written back to request.body.
-- The regression scenario was initially vulnerable because the handler received string "10" after validation accepted it.
-- The CVSS rating assumed PR:L without repository evidence that authentication is required; many affected routes may be unauthenticated.
-- The impact rating was stated as application-dependent without defining the affected endpoint’s actual confidentiality and integrity consequences.
-
-### How it was fixed
-- Pass parentData and parentDataProperty to Ajv validators so root primitive coercions update the request object.
-- Retain the direct-call path for validators without schemaEnv to avoid changing non-Ajv validator behavior.
-- Add a regression test asserting quoted numeric JSON reaches the handler as number 10.
-- Determine PR from the deployed route’s authentication requirements; use PR:N for unauthenticated endpoints.
-- Base C/I impact on the specific handler and data affected rather than assigning a universal Fastify score.
-
-## 20:09 UTC — Task
-
-### What went wrong
-- Validation coerced a root primitive but failed to preserve the coerced value for the caller.
-- The regression scenario was not covered by existing tests.
-
-### How it was fixed
-- Updated `lib/validation.js` to retain and return coerced root values.
-- Added `test/fix-root-primitive-coercion.test.js` to prevent recurrence.
-

package/.pi/self-learning-memory/daily/2026-08-04.md

@@ -1,41 +0,0 @@
-## 10:59 UTC — Task
-
-### What went wrong
-- Assumed /static/..%2f… 404 meant getPathnameForSend/route miss instead of later send pipeline behavior
-- Did not check that encodeURI() re-encodes residual % as %25 before blaming path guards
-- Conflated reply.callNotFound() JSON ("Route GET:… not found") with an actual find-my-way miss
-- Debugged isolated getPathnameForSend reimplementation before tracing pumpSendToReply → encodeURI(pathnameForSend) → @fastify/send
-- Compared send() on decoded ../ paths (403) to static outcomes without using the exact post-encodeURI string static passes
-
-### How it was fixed
-- Always log/compare the exact pathname string passed into send(), including after encodeURI
-- When statuses differ for "same" path, diff charCodes for % vs %25 double-encoding first
-- Instrument static handler vs router to separate callNotFound from unmatched routes
-- Trace full pipeline: raw.url → getPathnameForSend → dotDot guards → encodeURI → @fastify/send
-- Reproduce with send(root, p) using both raw and encodeURI(p) before changing triage conclusions
-
-## 11:12 UTC — Task
-
-### What went wrong
-- Assumed encodeURI leaves '%' intact on paths like '/..%2ftop-secret.txt', so static 404 vs raw '..' 403 looked inconsistent.
-- Treated encoded traversal and decoded param sinks as the same layer before separating find-my-way dual-decode from @fastify/send root checks.
-- Relied on log/message shape alone (callNotFound 'Route ... not found') to infer static failure mode without probing @fastify/send inputs.
-
-### How it was fixed
-- Empirically print encodeURI output/charCodes: '%' → '%25', so static sees '/..%252ftop-secret.txt' (safe 404) not a '..' segment.
-- Reproduce with @fastify/send directly for raw percent, encodeURI(percent), and decoded '../' to map 403 vs 404 to normalize/root logic.
-- Keep reporter response framed as app-level path.join(param) misuse; cite static/sendFile containment and Express parity, not a core CVE.
-
-## 12:31 UTC — Task
-
-### What went wrong
-- Markdown lint invoked in a way that flooded output with unrelated files (AGENTS.md, .pi memory, response.md) instead of only the two edited docs.
-- Untracked response.md sat in the working tree and could have been staged if git add was too broad.
-- Relied on noisy repo-wide lint signal before confirming MD013 on the actual changed regions.
-
-### How it was fixed
-- Re-run markdownlint scoped strictly to docs/Reference/Request.md and docs/Reference/Routes.md.
-- Stage only those two paths (git add docs/Reference/Request.md docs/Reference/Routes.md); never git add .
-- Manually awk length>80 on changed files to confirm new lines stay ≤80 before commit.
-- Leave response.md untracked and verify git status/diff --stat before commit and PR.
-

package/.pi/self-learning-memory/daily/2026-08-18.md

@@ -1,40 +0,0 @@
-## 19:37 UTC — Task
-
-### What went wrong
-- Assumed the draft advisory meant `origin/main` and `origin/5.x` must remain untouched without first confirming whether the user expected public pushes.
-- Reported that the private branches were complete without clearly distinguishing advisory-fork refs from public `origin` refs, prompting the user to stop and verify deployment status.
-- Combined PR closing with an unsupported workspace-repository comment under `set -e`, causing the entire command to fail before the close could occur.
-- Called the PR “now-empty” even though GitHub still reported it as mergeable with different head and base OIDs.
-- Deleted local security branches before resolving whether the user wanted the commits pushed to public branches, reducing convenient recovery points.
-
-### How it was fixed
-- Before any security-fix push, explicitly ask whether targets are the private advisory fork, public `origin`, or both; treat a draft advisory as a warning, not implicit authorization policy.
-- Always state push destinations and exact resulting refs, e.g. `advisory-ghsa-3m5p/main` changed while `origin/main` remained at `6e95cb9f`.
-- Run workspace-sensitive PR operations separately: attempt the comment, record an expected permission denial, then independently close only if authorized.
-- Describe PR state from verified fields (`CLOSED`, `mergedAt: null`, head/base OIDs) rather than inferring that it is empty.
-- Keep local security branches until the user confirms the intended public/private publication state; delete them only after final authorization and ref verification.
-
-## 19:38 UTC — Task
-
-### What went wrong
-- Initially pushed the security fix only to the private advisory fork, leaving `origin/main` and `origin/5.x` unchanged without first confirming the intended publication target.
-- After pushing remote refs, local `main` remained one commit behind, creating temporary local/remote inconsistency.
-- A GraphQL `addComment` action was attempted despite workspace-repository restrictions; the denial indicates an intentional permission boundary that should not be bypassed.
-
-### How it was fixed
-- Obtained explicit approval before public disclosure, then atomically fast-forwarded `origin/main` to `af079bd4` and `origin/5.x` to `8acfea7e`, verifying both refs with `git ls-remote`.
-- Fast-forwarded local `main` to `origin/main` and confirmed a clean synchronized status.
-- Do not retry forbidden workspace GraphQL actions; use permitted repository operations or ask the user for an authorized alternative before attempting comments or metadata changes.
-
-## 19:46 UTC — Task
-
-### What went wrong
-- Private PR #1 remained open after its head commit had already been placed on private `main`; its mergeability was `UNKNOWN` and it was no longer the correct landing path.
-- Local `main` and temporary security branches were left out of sync after updating the remote branches.
-- Direct public branch updates bypassed the repository’s pull-request-only rules, so ancestry and target refs required explicit validation to avoid unsafe rewrites.
-
-### How it was fixed
-- Closed PR #1 without merging after confirming its head SHA was already the intended private `main` commit.
-- Fetched current `origin/main` and `origin/5.x`, verified each security commit’s parent exactly matched the corresponding remote tip, then used an atomic push.
-- Verified public and private `main`/`5.x` refs matched, fast-forwarded local `main`, deleted temporary security branches, and confirmed a clean synchronized checkout.
-

package/.pi/self-learning-memory/long-term-memory.md

@@ -1,89 +0,0 @@
-# Long-term Memory
-
-Complete history of durable learnings and recurring mistakes.
-Last updated: 2026-08-18T19:46:43.093Z
-
-## All learnings
-- Closed PR #1 without merging after confirming its head SHA was already the intended private `main` commit.
-- Fetched current `origin/main` and `origin/5.x`, verified each security commit’s parent exactly matched the corresponding remote tip, then used an atomic push.
-- Verified public and private `main`/`5.x` refs matched, fast-forwarded local `main`, deleted temporary security branches, and confirmed a clean synchronized checkout.
-- Obtained explicit approval before public disclosure, then atomically fast-forwarded `origin/main` to `af079bd4` and `origin/5.x` to `8acfea7e`, verifying both refs with `git ls-remote`.
-- Fast-forwarded local `main` to `origin/main` and confirmed a clean synchronized status.
-- Do not retry forbidden workspace GraphQL actions; use permitted repository operations or ask the user for an authorized alternative before attempting comments or metadata changes.
-- Before any security-fix push, explicitly ask whether targets are the private advisory fork, public `origin`, or both; treat a draft advisory as a warning, not implicit authorization policy.
-- Always state push destinations and exact resulting refs, e.g. `advisory-ghsa-3m5p/main` changed while `origin/main` remained at `6e95cb9f`.
-- Run workspace-sensitive PR operations separately: attempt the comment, record an expected permission denial, then independently close only if authorized.
-- Describe PR state from verified fields (`CLOSED`, `mergedAt: null`, head/base OIDs) rather than inferring that it is empty.
-- Keep local security branches until the user confirms the intended public/private publication state; delete them only after final authorization and ref verification.
-- Re-run markdownlint scoped strictly to docs/Reference/Request.md and docs/Reference/Routes.md.
-- Stage only those two paths (git add docs/Reference/Request.md docs/Reference/Routes.md); never git add .
-- Manually awk length>80 on changed files to confirm new lines stay ≤80 before commit.
-- Leave response.md untracked and verify git status/diff --stat before commit and PR.
-- Empirically print encodeURI output/charCodes: '%' → '%25', so static sees '/..%252ftop-secret.txt' (safe 404) not a '..' segment.
-- Reproduce with @fastify/send directly for raw percent, encodeURI(percent), and decoded '../' to map 403 vs 404 to normalize/root logic.
-- Keep reporter response framed as app-level path.join(param) misuse; cite static/sendFile containment and Express parity, not a core CVE.
-- Always log/compare the exact pathname string passed into send(), including after encodeURI
-- When statuses differ for "same" path, diff charCodes for % vs %25 double-encoding first
-- Instrument static handler vs router to separate callNotFound from unmatched routes
-- Trace full pipeline: raw.url → getPathnameForSend → dotDot guards → encodeURI → @fastify/send
-- Reproduce with send(root, p) using both raw and encodeURI(p) before changing triage conclusions
-- Updated `lib/validation.js` to retain and return coerced root values.
-- Added `test/fix-root-primitive-coercion.test.js` to prevent recurrence.
-- Pass parentData and parentDataProperty to Ajv validators so root primitive coercions update the request object.
-- Retain the direct-call path for validators without schemaEnv to avoid changing non-Ajv validator behavior.
-- Add a regression test asserting quoted numeric JSON reaches the handler as number 10.
-- Determine PR from the deployed route’s authentication requirements; use PR:N for unauthenticated endpoints.
-- Base C/I impact on the specific handler and data affected rather than assigning a universal Fastify score.
-- Pass request and parameter metadata as Ajv parentData/parentDataProperty so root coercions update the original request value.
-- Add a regression test asserting quoted numeric JSON becomes a number in the handler while out-of-range values remain rejected.
-- Verify targeted test execution separately from the full suite to avoid mistaking aggregate counts for focused coverage.
-- Honor soft tool-budget and interruption signals immediately; stop browsing and provide a bounded reflection.
-- Run only the single highest-value targeted test before the budget limit, then report if execution is blocked.
-- Reproduce root primitive coercion with the repository’s actual validatorCompiler path rather than relying on Ajv internals alone.
-- Add focused tests covering custom validator compilation, schemaEnv availability, and root primitive coercion.
-- Renamed PR #6833 to `ci: harden CITGM package workflow input handling` using `gh pr edit`, then watched checks until `pull-request-title-check` passed.
-- Pass workflow input through `env.NPM_PACKAGE` and read it from `process.env` inside the script.
-- Validate the package name with an npm package-name regex before using it.
-- Use `encodeURIComponent(packageName)` in the npm registry URL.
-- Check `response.ok` and throw explicit errors for failed registry fetches or unsupported repository URLs.
-
-## All watch-outs
-- Private PR #1 remained open after its head commit had already been placed on private `main`; its mergeability was `UNKNOWN` and it was no longer the correct landing path.
-- Local `main` and temporary security branches were left out of sync after updating the remote branches.
-- Direct public branch updates bypassed the repository’s pull-request-only rules, so ancestry and target refs required explicit validation to avoid unsafe rewrites.
-- Initially pushed the security fix only to the private advisory fork, leaving `origin/main` and `origin/5.x` unchanged without first confirming the intended publication target.
-- After pushing remote refs, local `main` remained one commit behind, creating temporary local/remote inconsistency.
-- A GraphQL `addComment` action was attempted despite workspace-repository restrictions; the denial indicates an intentional permission boundary that should not be bypassed.
-- Assumed the draft advisory meant `origin/main` and `origin/5.x` must remain untouched without first confirming whether the user expected public pushes.
-- Reported that the private branches were complete without clearly distinguishing advisory-fork refs from public `origin` refs, prompting the user to stop and verify deployment status.
-- Combined PR closing with an unsupported workspace-repository comment under `set -e`, causing the entire command to fail before the close could occur.
-- Called the PR “now-empty” even though GitHub still reported it as mergeable with different head and base OIDs.
-- Deleted local security branches before resolving whether the user wanted the commits pushed to public branches, reducing convenient recovery points.
-- Markdown lint invoked in a way that flooded output with unrelated files (AGENTS.md, .pi memory, response.md) instead of only the two edited docs.
-- Untracked response.md sat in the working tree and could have been staged if git add was too broad.
-- Relied on noisy repo-wide lint signal before confirming MD013 on the actual changed regions.
-- Assumed encodeURI leaves '%' intact on paths like '/..%2ftop-secret.txt', so static 404 vs raw '..' 403 looked inconsistent.
-- Treated encoded traversal and decoded param sinks as the same layer before separating find-my-way dual-decode from @fastify/send root checks.
-- Relied on log/message shape alone (callNotFound 'Route ... not found') to infer static failure mode without probing @fastify/send inputs.
-- Assumed /static/..%2f… 404 meant getPathnameForSend/route miss instead of later send pipeline behavior
-- Did not check that encodeURI() re-encodes residual % as %25 before blaming path guards
-- Conflated reply.callNotFound() JSON ("Route GET:… not found") with an actual find-my-way miss
-- Debugged isolated getPathnameForSend reimplementation before tracing pumpSendToReply → encodeURI(pathnameForSend) → @fastify/send
-- Compared send() on decoded ../ paths (403) to static outcomes without using the exact post-encodeURI string static passes
-- Validation coerced a root primitive but failed to preserve the coerced value for the caller.
-- The regression scenario was not covered by existing tests.
-- Ajv was called with a primitive root value without parentData context, so coerced values were not written back to request.body.
-- The regression scenario was initially vulnerable because the handler received string "10" after validation accepted it.
-- The CVSS rating assumed PR:L without repository evidence that authentication is required; many affected routes may be unauthenticated.
-- The impact rating was stated as application-dependent without defining the affected endpoint’s actual confidentiality and integrity consequences.
-- Root primitive request values were validated without a parent reference, so Ajv coercion changed only its local value and left request.body as a string.
-- Test command output was misread: Borp ran the broader suite despite a specific file argument, making targeted coverage unclear.
-- Continued initiating tool work after the tool-budget warning instead of stopping to assess the existing evidence.
-- Started a test command that was aborted, leaving the primitive-coercion fix unverified.
-- Investigated Ajv internals and custom compiler compatibility without first isolating the exact failing repository behavior.
-- Did not establish regression coverage for missing schemaEnv handling and root primitive coercion before changing direction.
-- PR title did not satisfy the repository's conventional title check before opening/updating the PR.
-- Interpolated `${{ inputs.package }}` directly into `actions/github-script` JavaScript, allowing malformed input to break or inject code.
-- Fetched npm metadata with the raw package name instead of URL-encoding it.
-- Assumed `data.repository.url` always existed and was a GitHub `.git` URL.
-- Used a brittle repository URL regex that missed scoped/modern GitHub URL formats and failed without a clear error.

package/AGENTS.md

@@ -1,290 +0,0 @@
-# AGENTS.md - Guide for AI Agents Working with Fastify
-
-This document provides information and guidelines for AI agents (such as GitHub Copilot, Cursor, pi, or other AI coding assistants) working with the Fastify codebase.
-
-## Project Overview
-
-Fastify is a high-performance web framework for Node.js focused on:
-- **Speed**: One of the fastest Node.js web frameworks
-- **Extensibility**: Powerful plugin architecture with hooks and decorators
-- **Schema-based**: JSON Schema validation and serialization
-- **Developer experience**: Expressive API with minimal overhead
-- **TypeScript support**: Full type definitions included
-
-**Current Version**: 5.7.1 (main branch)
-**Repository**: https://github.com/fastify/fastify
-
-## Repository Structure
-
-```
-fastify/
-├── docs/                 # Documentation (Guides and Reference)
-│   ├── Guides/          # Tutorials and how-to guides
-│   └── Reference/       # API documentation
-├── examples/            # Example applications and benchmarks
-├── lib/                 # Core library code
-├── test/                # Test files
-├── types/               # TypeScript type definitions
-├── build/               # Build scripts
-├── integration/         # Integration tests
-├── fastify.js           # Main entry point
-├── fastify.d.ts         # Main TypeScript definitions
-└── package.json         # Dependencies and scripts
-```
-
-## Key Files for Agents
-
-### Core Files
-- **`fastify.js`** - Main Fastify class and entry point
-- **`fastify.d.ts`** - TypeScript type definitions (keep these in sync)
-- **`lib/`** - All core functionality:
-  - `route.js` - Route handling
-  - `req-res.js` - Request and Reply objects
-  - `hooks.js` - Lifecycle hooks
-  - `plugin.js` - Plugin system
-  - `validation.js` - Schema validation
-  - `content-type-parser.js` - Body parsing
-  - `logger.js` - Pino logger integration
-
-### Configuration Files
-- **`package.json`** - Scripts, dependencies, and contributors
-- **`eslint.config.js`** - Linting configuration (uses neostandard)
-- **`.markdownlint-cli2.yaml`** - Markdown linting rules
-
-### Documentation Files
-- **`README.md`** - Project overview and quick start
-- **`CONTRIBUTING.md`** - Contribution guidelines
-- **`GOVERNANCE.md`** - Links to organization governance
-- **`SECURITY.md`** - Security policy
-- **`docs/Guides/Contributing.md`** - Detailed contributing guide
-- **`docs/Guides/Style-Guide.md`** - Coding style conventions
-
-## Testing Conventions
-
-### Test Framework
-Fastify uses **Borp** (a custom test runner) for testing.
-
-### Test Structure
-- Tests are in the **`test/`** directory
-- Test files follow the pattern: `test/<module>.test.js`
-- Integration tests are in **`integration/`** directory
-
-### Running Tests
-
-```bash
-# Run all tests
-npm test
-
-# Run unit tests only
-npm run unit
-
-# Run tests with coverage
-npm run coverage
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run TypeScript type tests
-npm run test:typescript
-
-# Run CI tests (minimal)
-npm run test:ci
-```
-
-### Test Requirements
-- **100% line coverage** is required for all changes (enforced by CI)
-- Tests must pass on all supported Node.js versions
-- TypeScript types must be tested (using `tsd`)
-
-## Code Style and Conventions
-
-### Linting
-- Uses **Neostandard** JavaScript style guide
-- ESLint is configured in `eslint.config.js`
-- Run `npm run lint` to check code style
-- Run `npm run lint:fix` to auto-fix issues
-
-### Key Style Rules (from Style-Guide.md)
-- Use `const` and `let`, never `var`
-- Use arrow functions for callbacks
-- Use async/await instead of promises
-- Follow semicolon usage (neostandard enforces this)
-- Use template literals for string interpolation
-- Prefer functional methods (`map`, `filter`, `reduce`) over loops
-- Error-first callback pattern for async operations where needed
-
-### Naming Conventions
-- **Files**: kebab-case (`content-type-parser.js`)
-- **Variables**: camelCase
-- **Constants**: UPPER_SNAKE_CASE
-- **Classes**: PascalCase
-- **Private methods**: prefixed with `_`
-
-## Common Tasks
-
-### Adding a New Feature
-1. Implement the feature in `lib/`
-2. Add tests in `test/`
-3. Update TypeScript types in `fastify.d.ts` or `types/`
-4. Update documentation in `docs/`
-5. Run `npm test` to ensure all tests pass
-6. Run `npm run lint` to check code style
-7. Add changelog entry for release
-
-### Fixing a Bug
-1. Add a failing test case in `test/`
-2. Fix the bug in `lib/`
-3. Ensure all tests pass
-4. Check if TypeScript types need updating
-5. Update documentation if behavior changes
-
-### Working with Plugins
-- See `docs/Guides/Write-Plugin.md` for plugin authoring
-- See `docs/Guides/Plugins-Guide.md` for plugin usage
-- Plugin example: `lib/plugin.js`
-
-## Architecture Highlights
-
-### Core Components
-
-1. **Server (`fastify.js`)**
-   - Main Fastify class
-   - Server initialization and configuration
-   - Plugin system integration (via `avvio`)
-
-2. **Routing (`lib/route.js`)**
-   - Uses `find-my-way` for fast route matching
-   - Route registration and lookup
-   - Shorthand methods (get, post, put, delete, etc.)
-
-3. **Request/Response (`lib/req-res.js`)**
-   - Request object extensions
-   - Reply object with fluent API
-   - Decorator support
-
-4. **Hooks (`lib/hooks.js`)**
-   - Lifecycle hooks (onRequest, preHandler, etc.)
-   - Hook execution order and timing
-
-5. **Validation (`lib/validation.js`)**
-   - JSON Schema validation via AJV
-   - Response serialization
-   - Built-in error serializer
-
-6. **Content Type Parser (`lib/content-type-parser.js`)**
-   - Request body parsing
-   - Custom parser support
-   - JSON and other formats
-
-### Plugin System
-- Plugins are loaded asynchronously via `avvio`
-- Supports encapsulation (scoped plugins)
-- Hooks and decorators can be scoped
-- See `lib/plugin.js` for implementation
-
-## TypeScript Integration
-
-- TypeScript definitions are in `fastify.d.ts` and `types/`
-- Types must be tested with `tsd`
-- Run `npm run test:typescript` to verify types
-- Keep types in sync with JavaScript implementation
-
-## Performance Considerations
-
-Fastify prioritizes performance:
-- **Routes**: Pre-compiled functions for fast matching
-- **Validation**: Compiled JSON Schema validators
-- **Serialization**: Compiled serializers (fast-json-stringify)
-- **Logging**: Low-overhead Pino logger
-- **Caching**: Route context caching with `toad-cache`
-
-When making changes:
-- Profile performance impact for hot paths
-- Use benchmarks in `examples/benchmark/`
-- Run `npm run benchmark` to measure
-
-## Documentation Updates
-
-Documentation is critical for Fastify. When changing behavior:
-
-1. Update relevant docs in `docs/Reference/` for API changes
-2. Update `docs/Guides/` for usage pattern changes
-3. Check for broken links (CI validates this)
-4. Update examples in `examples/` if needed
-5. Run `npm run lint:markdown` to check docs
-
-## Pre-commit Checks
-
-Before submitting changes, ensure:
-
-1. ✅ All tests pass: `npm test`
-2. ✅ 100% coverage: `npm run coverage`
-3. ✅ Linting passes: `npm run lint`
-4. ✅ TypeScript types pass: `npm run test:typescript`
-5. ✅ Markdown linting passes: `npm run lint:markdown`
-6. ✅ Documentation is updated
-7. ✅ Examples still work if affected
-
-## Working with CI
-
-Fastify uses GitHub Actions for CI. Workflows are in `.github/workflows/`:
-- **`ci.yml`** - Main CI pipeline
-- **`package-manager-ci.yml`** - Tests multiple package managers
-- **`website.yml`** - Website deployment
-
-## Agent-Specific Tips
-
-### When Generating Code
-1. Check existing patterns in `lib/` before creating new patterns
-2. Follow the established error handling patterns
-3. Use async/await consistently
-4. Add appropriate hooks if extending lifecycle
-5. Consider TypeScript types from the start
-
-### When Refactoring
-1. Ensure all tests still pass
-2. Don't change public APIs without semver consideration
-3. Update TypeScript definitions if signatures change
-4. Check for deprecation needs
-5. Update documentation for changed behavior
-
-### When Analyzing Issues
-1. Check `test/` for usage examples
-2. Review relevant `docs/Reference/` files
-3. Look at similar implementations in `lib/`
-4. Consider the plugin system and encapsulation
-5. Check hook timing and order
-
-### Common Gotchas
-- **Encapsulation**: Plugins are isolated - decorators don't leak
-- **Hook order**: Hooks run in specific order (see docs/Reference/Hooks.md)
-- **Async boot**: Server starts asynchronously - use `ready()` or `after()`
-- **Error handling**: Use Fastify error classes from `@fastify/error`
-- **Validation**: Schemas are compiled - changes require recompilation
-
-## Key Dependencies
-
-- **`avvio`** - Plugin loading and boot
-- **`find-my-way`** - Fast HTTP router
-- **`fast-json-stringify`** - Response serialization
-- **`pino`** - Logging
-- **`@fastify/ajv-compiler`** - JSON Schema validation
-- **`light-my-request`** - HTTP injection for testing
-
-## Contact and Resources
-
-- **Documentation**: https://fastify.dev/
-- **Discord**: https://discord.gg/fastify
-- **GitHub Issues**: https://github.com/fastify/fastify/issues
-- **GitHub Discussions**: https://github.com/fastify/fastify/discussions
-- **Help**: https://github.com/fastify/help
-
-## Version Information
-
-- **Main branch**: Fastify v5
-- **v4 branch**: https://github.com/fastify/fastify/tree/4.x
-- **LTS Policy**: See `docs/Reference/LTS.md`
-
----
-
-This document is maintained by the Fastify team. For questions or suggestions, please open an issue or discussion.