proteum 2.2.0 → 2.2.1

package/AGENTS.md

@@ -32,7 +32,7 @@ cd <worktree path>
 npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 ```
 - After implementing a framework feature or change, do not stop at code edits. Boot both reference apps, exercise the affected flow with Playwright or the smallest real Proteum surface, run the relevant `proteum` diagnostics or perf commands, and confirm there is no meaningful regression in runtime behavior, performance, load size, SEO output, or coding-style expectations before finishing.
-- When starting a long-lived reference app dev server for framework work, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit thread-scoped session file such as `var/run/proteum/dev/framework-<app>-<task>.json`, inspect tracked sessions plus current listeners first, for example with `npx proteum dev list --json` and `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- When starting a long-lived reference app dev server for framework work, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit thread-scoped session file such as `var/run/proteum/dev/framework-<app>-<task>.json`, inspect tracked sessions plus current listeners first, for example with `npx proteum dev list --json` and `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. After the server is ready, print the live server URL as a clickable Markdown link such as `[http://localhost:3100](http://localhost:3100)`.
 - Do not use `--replace-existing` unless you are restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
 - When a reference app uses local `file:` connected projects for the affected flow, boot every connected producer app as well, each on its own free port and thread-scoped session file, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or validating the consumer app.
 - Before retrying a boot on the same app, changing ports, or finishing the task, stop every framework-started dev session with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`.
@@ -51,11 +51,13 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 
 - Validate framework changes against the reference apps:
   - `/Users/gaetan/Desktop/Projets/crosspath/platform`: Standalone app
+  - `/Users/gaetan/Desktop/Projets/crosspath/website`: Standalone app
   - `/Users/gaetan/Desktop/Projets/unique.domains/platform`: Monorepo including the following apps:
     - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/product`
     - `/Users/gaetan/Desktop/Projets/unique.domains/platform/apps/website`
 - Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
 - Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/root/AGENTS.md`, `agents/project/app-root/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
+- Keep the same-system trace contract explicit when request instrumentation changes: `TRACE_*` controls the retained dev trace store plus the trace/perf CLI, dev-only HTTP endpoints, and bottom profiler, while `ENABLE_PROFILER` enables the reduced request-local `request.profiling` snapshot and `request.finished` hook payload without retaining finished requests globally unless dev trace is also enabled.
 - Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the banner. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner.
 - Keep core changes aligned with the explicit controller/page architecture in `agents/project/root/AGENTS.md` and its standalone composition in `agents/project/AGENTS.md`.
 - Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.

package/README.md

@@ -6,6 +6,12 @@ It is built for teams that want explicit server contracts, server-first renderin
 
 Migration guide for older apps: [docs/migrate-from-2.1.3.md](docs/migrate-from-2.1.3.md)
 
+## Sponsor
+
+Proteum is sponsored by [Unique Domains](https://unique.domains/?utm_source=github&utm_medium=referral&utm_campaign=repo_proteum&utm_content=top_sponsor).
+
+[![Unique Domains](docs/assets/unique-domains-chip.png)](https://unique.domains/?utm_source=github&utm_medium=referral&utm_campaign=repo_proteum&utm_content=top_sponsor)
+
 ## Why Proteum
 
 Most full-stack frameworks optimize first for human convenience.
@@ -101,6 +107,7 @@ Optional trace env vars:
 - `TRACE_EVENTS_LIMIT`
 - `TRACE_CAPTURE`
 - `TRACE_PERSIST_ON_ERROR`
+- `ENABLE_PROFILER`
 
 Optional `proteum.config.ts` fields:
 
@@ -464,6 +471,7 @@ Default behavior:
 - payloads are summarized, long strings are truncated, and sensitive fields such as cookies, passwords, and tokens are redacted
 - `TRACE_PERSIST_ON_ERROR` can export crashing requests under `var/traces/`
 - `proteum dev` removes auto-persisted crash traces from `var/traces/` when the dev session stops
+- `ENABLE_PROFILER=true` reuses the same instrumentation path to populate `request.profiling` and the router `request.finished` hook with a reduced request/API/SQL snapshot in any environment, without retaining finished requests in the global trace buffer unless dev trace is also enabled
 
 Trace env example:
 
@@ -473,6 +481,7 @@ export TRACE_REQUESTS_LIMIT=200
 export TRACE_EVENTS_LIMIT=800
 export TRACE_CAPTURE=resolve
 export TRACE_PERSIST_ON_ERROR=true
+export ENABLE_PROFILER=true
 ```
 
 Capture modes:
@@ -500,7 +509,7 @@ Proteum answers those questions with explicit artifacts:
 
 - `identity.config.ts` for app identity
 - `proteum.config.ts` for compiler and connected-project setup
-- `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, app-chosen connected-project config values, and `TRACE_*` env vars for the environment surface
+- `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, app-chosen connected-project config values, `TRACE_*`, and `ENABLE_PROFILER` env vars for the environment surface
 - `server/index.ts` for the explicit root service graph
 - `.proteum/manifest.json` for machine-readable app structure
 - `proteum explain --json` for structured framework introspection
@@ -516,7 +525,7 @@ Proteum answers those questions with explicit artifacts:
 If you are an LLM or automation agent, start here:
 
 1. Read `identity.config.ts` and `proteum.config.ts`.
-2. Read `PORT`, the relevant `ENV_*`, `URL`, `URL_INTERNAL`, any env values referenced by `proteum.config.ts`, and `TRACE_*` env vars, or run `proteum explain env`.
+2. Read `PORT`, the relevant `ENV_*`, `URL`, `URL_INTERNAL`, any env values referenced by `proteum.config.ts`, plus `TRACE_*` and `ENABLE_PROFILER`, or run `proteum explain env`.
 3. Inspect `server/index.ts` and `server/config/*.ts` for the explicit app bootstrap.
 4. Read `.proteum/manifest.json` or run `proteum explain --json`.
 5. Inspect `server/controllers/**` for request entrypoints.

package/agents/project/AGENTS.md

@@ -17,12 +17,14 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
   - Run `npx proteum refresh`.
   - Read and acknowledge the applicable `AGENTS.md` files.
   - Run `npm i`.
-  - Run the dev server with the task-safe elevated-permissions launch workflow from `Task Lifecycle`, and keep it running so user can see the results by himself.
-- If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
+  - Run the dev server with the task-safe elevated-permissions launch workflow from `Task Lifecycle`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link.
+- If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it. After this, everytime you implemented a fix
+    - test, re-run analysis and give a comparizon table of before and after
+    - re-print the complete list of suggested fixes, but strike the ones we already implemented or not necessary anymore
 - If the task is ambiguous, generated, connected, or multi-repo, start with `npx proteum orient <query>` before reading large parts of the codebase.
 - If the user reports an issue, or the agent encounters one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
 - If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
-- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the dev server URL.
+- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the live dev server URL as a clickable Markdown link.
 - If the task needs new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
 - If you changed `schema.prisma`, do not start testing or validation yet. Ask the user to run the following command in the affected worktree directory, replacing the placeholders, and wait for the user to reply exactly `continue` before resuming validation or tests:
   ```
@@ -51,7 +53,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### During Implementation
 
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
-- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
 - For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
@@ -60,7 +62,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### Before Finishing
 
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
-- Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
+- Do not default to project-wide typecheck or `npx proteum check` after every change. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
@@ -96,6 +98,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Root services are public class fields instantiated with `new ServiceClass(this, config, this)`.
 - Typed root-service config lives in `server/config/*.ts` via `Services.config(ServiceClass, { ... })`.
 - Router plugins are instantiated explicitly inside the `Router` config `plugins` object.
+- Router plugins can subscribe to `request` and `request.finished`; `request.profiling` exists before `request` runs and carries the finalized request/API/SQL snapshot by `request.finished`.
 - Root business services live in `server/services/<Feature>/index.ts`.
 - Root-service config lives in `server/config/*.ts` when the service needs config.
 - Business logic lives in classes that extend `Service` and use `this.services`, `this.models`, and `this.app`.
@@ -174,6 +177,7 @@ Verify at the correct layer:
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
 - SSR changes: load the real page and inspect rendered HTML plus browser console.
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
+- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, then update the relevant end-to-end coverage and finish by running the full Playwright suite.
 - Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
 - Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
 - Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
@@ -238,7 +242,7 @@ Proteum reads:
 - `package.json`
 - `identity.config.ts` for app identity via `Application.identity({ ... })`
 - `proteum.config.ts` for compiler setup via `Application.setup({ transpile, connect })`
-- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, and `TRACE_*`
+- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, `TRACE_*`, and `ENABLE_PROFILER`
 - `server/config/*.ts`
 - `server/index.ts`
 - `commands/**/*.ts`
@@ -298,6 +302,6 @@ Prefer scaffold commands before hand-writing boilerplate:
 Edit these only when required, and keep changes minimal and explicit:
 
 - `tsconfig*.json`
-- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
+- `PORT`, `ENV_*`, `URL`, `TRACE_*`, and `ENABLE_PROFILER` env setup
 - Prisma-generated files
 - symbolic links

package/agents/project/app-root/AGENTS.md

@@ -12,5 +12,5 @@ Do not put here: reusable Proteum architecture contracts, shared verification ru
   - Run `npx proteum refresh`.
   - Read and acknowledge the applicable `AGENTS.md` files.
   - Run `npm i`.
-  - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, and keep it running so user can see the results by himself.
-- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the dev server URL.
+  - Run the dev server with the task-safe elevated-permissions launch workflow from the reusable root `AGENTS.md`, keep it running so user can see the results by himself, and print the live server URL as a clickable Markdown link.
+- If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, read the relevant files under `./docs/` first, especially `docs/PERSONAS.md`, `docs/PRODUCT.md`, and `docs/MARKETING.md` when they exist. If a dev server is already running, print the live dev server URL as a clickable Markdown link.

package/agents/project/diagnostics.md

@@ -12,7 +12,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 ## Runtime Diagnostics
 
-- For long-lived dev reproductions, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- For long-lived dev reproductions, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
 - Only the bare `npx proteum build` and bare `npx proteum dev` commands print the welcome banner and active Proteum installation method. Any extra argument or option skips the banner. Only `npx proteum dev` clears the interactive terminal before rendering and reports connected app names plus successful connected `/ping` checks in the ready banner; keep that in mind when capturing or comparing command logs during diagnosis.
 - For ownership or repo discovery questions, start with `npx proteum orient <query>` instead of jumping straight into source searches.

package/agents/project/root/AGENTS.md

@@ -43,7 +43,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### During Implementation
 
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
-- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`.
+- When starting a long-lived dev server for an agent task, always request elevated permissions and run `npx proteum dev` outside the sandbox. Use an explicit task/thread-scoped session file such as `var/run/proteum/dev/agents/<task>.json`, inspect `npx proteum dev list --json` plus current listeners first, for example with `lsof -nP -iTCP -sTCP:LISTEN`, then choose a port that is not currently used before starting `npx proteum dev --session-file <path> --port <port>`. After the server is ready, print the live server URL as a clickable Markdown link.
 - Use `--replace-existing` only when restarting the exact session file started by the current thread/task. Never replace another live session that belongs to a user, another thread, or an unknown owner.
 - If the current app depends on local `file:` connected projects, boot every connected producer app too, each with its own task-scoped session file and free port, and run every one of those `proteum dev` processes with elevated permissions outside the sandbox before starting or verifying the consumer app.
 - For raw browser automation, use `npx proteum verify browser` when it matches the task, or direct Playwright with a disposable profile when lower-level control is required. Bootstrap protected browser state through `npx proteum session`.
@@ -52,7 +52,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 ### Before Finishing
 
 - Before finishing, re-check touched files against root-level `CODING_STYLE.md` and any narrower area `AGENTS.md` that applied to the edit. Re-check against root-level `optimizations.md` only for touched client-side files. Re-check against root-level `diagnostics.md` only if the task involved an issue, diagnosis, runtime reproduction, or verification failure.
-- Do not default to project-wide typecheck, `npx proteum check`, or Playwright after every change. Run them only when the user asks for them, when the changed surface specifically requires them, or when a real issue discovered during verification justifies escalation.
+- Do not default to project-wide typecheck or `npx proteum check` after every change. After implementing a new feature or changing existing feature behavior, always update the end-to-end coverage for that behavior and run the full Playwright test suite before finishing. For docs-only, wording-only, type-only, test-only, generated-output cleanup, or clearly local non-runtime refactors, skip Playwright unless the user explicitly asks for it or verification reveals a real issue.
 - Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, ask the user whether they want a commit message. After providing a commit message or after creating a commit, immediately follow it with this exact prompt and obey it:
   `Explain in short minimalistic and few bullet points what we changed in this thread, like you would do to your grandma. Start with a verb in the past.`
@@ -88,6 +88,7 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Root services are public class fields instantiated with `new ServiceClass(this, config, this)`.
 - Typed root-service config lives in `server/config/*.ts` via `Services.config(ServiceClass, { ... })`.
 - Router plugins are instantiated explicitly inside the `Router` config `plugins` object.
+- Router plugins can subscribe to `request` and `request.finished`; `request.profiling` exists before `request` runs and carries the finalized request/API/SQL snapshot by `request.finished`.
 - Root business services live in `server/services/<Feature>/index.ts`.
 - Root-service config lives in `server/config/*.ts` when the service needs config.
 - Business logic lives in classes that extend `Service` and use `this.services`, `this.models`, and `this.app`.
@@ -166,6 +167,7 @@ Verify at the correct layer:
 - Controller changes: exercise the generated client call or generated `/api/...` endpoint.
 - SSR changes: load the real page and inspect rendered HTML plus browser console.
 - Router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app.
+- New features or feature-behavior changes: use the cheapest trustworthy verification while iterating, then update the relevant end-to-end coverage and finish by running the full Playwright suite.
 - Generated, connected, or ownership-ambiguous changes: start with `npx proteum orient <query>` and prefer `npx proteum verify owner <query>` before broad global checks.
 - Browser-visible issues: prefer `npx proteum verify browser <path>` or the narrowest targeted Playwright pass only after request-level verification is insufficient.
 - Raw browser execution beyond `npx proteum verify browser`: use direct Playwright with a disposable profile, and keep that step for the final verifier agent unless a narrower surface cannot reproduce the issue.
@@ -230,7 +232,7 @@ Proteum reads:
 - `package.json`
 - `identity.config.ts` for app identity via `Application.identity({ ... })`
 - `proteum.config.ts` for compiler setup via `Application.setup({ transpile, connect })`
-- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, and `TRACE_*`
+- `process.env` via `PORT`, `ENV_*`, `URL`, `URL_INTERNAL`, any app-chosen connected-project values referenced by `proteum.config.ts`, `TRACE_*`, and `ENABLE_PROFILER`
 - `server/config/*.ts`
 - `server/index.ts`
 - `commands/**/*.ts`
@@ -290,6 +292,6 @@ Prefer scaffold commands before hand-writing boilerplate:
 Edit these only when required, and keep changes minimal and explicit:
 
 - `tsconfig*.json`
-- `PORT`, `ENV_*`, `URL`, and `TRACE_*` env setup
+- `PORT`, `ENV_*`, `URL`, `TRACE_*`, and `ENABLE_PROFILER` env setup
 - Prisma-generated files
 - symbolic links

package/agents/project/tests/AGENTS.md

@@ -10,9 +10,16 @@ Diagnostics source of truth: root-level `diagnostics.md`.
 - Understand the real user flow and the main feature branches before writing tests.
 - Test the current controller/page runtime model, not legacy `@Route` or `api.fetch(...)` behavior.
 - Verify routing, controllers, SSR, and router plugins against a running app when behavior depends on real request handling.
-- After implementing a browser-visible feature or change, prefer a real browser repro against a running app first. Add targeted Playwright coverage only when the user asks for automated coverage, when a stable regression path needs automation, or when manual/browser verification is insufficient.
+- After implementing a new feature or changing existing feature behavior, update the end-to-end coverage for that behavior and run the full Playwright suite before finishing. Use a real browser repro against a running app during iteration when it is the fastest trustworthy loop.
 - Exercise real URLs, generated controller calls, or real browser flows instead of re-deriving framework internals in tests.
+- Organize end-to-end tests following the Crosspath platform layout under `tests/e2e/**`.
+- Put runnable scenario entrypoints in `tests/e2e/features/**`, `tests/e2e/specs/<domain>/**`, or `tests/e2e/journeys/**` depending on scope.
+- Put page objects and reusable UI surface wrappers in `tests/e2e/pages/**`.
+- Put reusable multi-step user flows in `tests/e2e/workflows/**`.
+- Put test data builders in `tests/e2e/factories/**` and generic helpers in `tests/e2e/utils/**`.
+- Keep helpers out of spec files when they are reusable, and do not create ad hoc flat test files or duplicate support abstractions when an existing page, workflow, factory, or utility already fits.
 - Locate elements with `data-testid`.
 - Add `data-testid` where needed instead of relying on brittle selectors.
+- Keep end-to-end tests clean, well organized, and non-redundant. Prefer extending or reshaping the most relevant existing scenario over duplicating coverage, and remove or consolidate overlap when the suite becomes repetitive.
 - Reuse root catalog files from `/client/catalogs/**`, `/server/catalogs/**`, or `/common/catalogs/**` instead of duplicating catalog constants in tests.
 - For protected dev flows, prefer `npx proteum session <email> --role <role>` over automating login unless the login flow itself is under test.

package/common/dev/requestTrace.ts

@@ -114,6 +114,7 @@ export type TTraceSqlQuery = {
     model?: string;
     operation: string;
     fingerprint?: string;
+    normalizedQuery?: string;
     ownerLabel?: string;
     ownerFilepath?: string;
     serviceLabel?: string;
@@ -169,6 +170,71 @@ export type TRequestTrace = {
     events: TTraceEvent[];
 };
 
+export type TRequestProfilingApiCall = {
+    id: string;
+    origin: TTraceCallOrigin;
+    label: string;
+    method: string;
+    path: string;
+    fetcherId?: string;
+    connectedProjectNamespace?: string;
+    connectedControllerAccessor?: string;
+    ownerLabel?: string;
+    ownerFilepath?: string;
+    serviceLabel?: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    statusCode?: number;
+    errorMessage?: string;
+    requestBodyJson?: unknown;
+    responseBodyJson?: unknown;
+};
+
+export type TRequestProfilingSqlQuery = {
+    id: string;
+    callerCallId?: string;
+    callerFetcherId?: string;
+    callerLabel?: string;
+    callerMethod: string;
+    callerOrigin: TTraceSqlQueryCallerOrigin;
+    callerPath: string;
+    durationMs: number;
+    finishedAt: string;
+    kind: TTraceSqlQueryKind;
+    model?: string;
+    operation: string;
+    fingerprint?: string;
+    normalizedQuery?: string;
+    ownerLabel?: string;
+    ownerFilepath?: string;
+    serviceLabel?: string;
+    connectedNamespace?: string;
+    paramsJson?: unknown;
+    paramsText?: string;
+    query: string;
+    startedAt: string;
+    target?: string;
+};
+
+export type TRequestProfiling = {
+    enabled: boolean;
+    requestId: string;
+    method: string;
+    path: string;
+    url: string;
+    startedAt: string;
+    finishedAt?: string;
+    durationMs?: number;
+    statusCode?: number;
+    user?: string;
+    errorMessage?: string;
+    profilerOrigin?: string;
+    profilerParentRequestId?: string;
+    apiCalls: TRequestProfilingApiCall[];
+    sqlQueries: TRequestProfilingSqlQuery[];
+};
+
 export type TRequestTraceListItem = Omit<TRequestTrace, 'events' | 'calls' | 'sqlQueries'> & {
     eventCount: number;
     callCount: number;

package/common/env/proteumEnv.ts

@@ -36,6 +36,7 @@ export type TProteumEnvConfig = {
     connectedProjects: Record<string, TProteumConnectedProjectEnvConfig>;
     trace: {
         enable: boolean;
+        profilerEnable: boolean;
         requestsLimit: number;
         eventsLimit: number;
         capture: TProteumTraceCapture;
@@ -65,7 +66,7 @@ const isProvidedEnvValue = (value: string | undefined) => typeof value === 'stri
 
 const buildRequiredEnvVariableDefinitions = (_connectedProjects: TConnectedProjectsConfig) => [...baseRequiredProteumEnvVariableDefinitions];
 
-const buildOptionalEnvKeys = (_connectedProjects: TConnectedProjectsConfig) => [] as string[];
+const buildOptionalEnvKeys = (_connectedProjects: TConnectedProjectsConfig) => ['ENABLE_PROFILER'] as string[];
 
 const formatRequiredEnvVariableStatus = (variable: TProteumRequiredEnvVariable) =>
     `- ${variable.key} possibleValues=${variable.possibleValues.join(' | ')} provided=${variable.provided ? 'yes' : 'no'}`;
@@ -269,8 +270,8 @@ export const loadOptionalProteumDotenv = (appDir: string) => {
 };
 
 export const getLoadedProteumEnvVariableKeys = (connectedProjects: TConnectedProjectsConfig = {}) => {
-    const requiredKeys = new Set(buildRequiredEnvVariableDefinitions(connectedProjects).map((definition) => definition.key));
-    const optionalKeys = new Set(buildOptionalEnvKeys(connectedProjects));
+    const requiredKeys = new Set<string>(buildRequiredEnvVariableDefinitions(connectedProjects).map((definition) => definition.key));
+    const optionalKeys = new Set<string>(buildOptionalEnvKeys(connectedProjects));
 
     return Object.keys(process.env)
         .filter(
@@ -338,6 +339,11 @@ export const parseProteumEnvConfig = ({
         value: process.env.TRACE_ENABLE,
         context,
     });
+    const profilerEnable = parseBooleanEnvValue({
+        key: 'ENABLE_PROFILER',
+        value: process.env.ENABLE_PROFILER,
+        context,
+    });
     const tracePersistOnError = parseBooleanEnvValue({
         key: 'TRACE_PERSIST_ON_ERROR',
         value: process.env.TRACE_PERSIST_ON_ERROR,
@@ -387,6 +393,7 @@ export const parseProteumEnvConfig = ({
         connectedProjects: resolvedConnectedProjects,
         trace: {
             enable: traceEnable ?? profile === 'dev',
+            profilerEnable: profilerEnable ?? false,
             requestsLimit:
                 traceRequestsLimit === undefined || traceRequestsLimit === ''
                     ? 200

package/docs/request-tracing.md

@@ -1,13 +1,18 @@
 # Request Tracing
 
-Proteum ships with a dev-only in-memory request trace buffer so routing, controller execution, SSR, API, Prisma SQL, render behavior, and request-time performance can be inspected without attaching a debugger or scattering temporary logs through the runtime.
+Proteum ships with one request-instrumentation system with two runtime shapes:
+
+- retained dev traces for `proteum trace`, `proteum perf`, the dev-only HTTP endpoints, and the bottom profiler
+- reduced request-local profiling for `request.profiling` and the router `request.finished` hook
+
+The same API and SQL instrumentation feeds both shapes. Dev trace keeps the in-memory buffer and event timeline. Reduced profiling keeps only the finalized request/API/SQL snapshot and releases it after the `request.finished` hook runs.
 
 ## Scope
 
-- tracing is available only when the app runs with `profile: dev`
+- retained dev tracing is available only when the app runs with `profile: dev`
 - traces are exposed through `proteum trace`, `proteum perf`, and the dev-only `__proteum/trace` and `__proteum/perf` HTTP endpoints
 - `proteum diagnose` is a separate composite surface that reads the same framework diagnostics plus one matching request trace and buffered server logs; see [diagnostics.md](diagnostics.md)
-- production requests are not traced by this feature
+- `ENABLE_PROFILER=true` enables reduced request-local profiling in any environment, including production
 
 ## Main Commands
 
@@ -77,6 +82,13 @@ Depending on capture mode, traces can include:
 - normalized request errors
 - additive owner, service, cache, and connected-boundary metadata propagated from route/controller resolution into downstream calls and SQL
 
+Reduced request-local profiling keeps the finalized request summary plus API and SQL rows only:
+
+- `request.profiling` exists before the router `request` hook runs
+- `request.profiling.apiCalls` and `request.profiling.sqlQueries` start empty and are populated during request handling
+- the router `request.finished` hook receives that same object after status, duration, API calls, and SQL queries are finalized
+- when only reduced profiling is enabled, finished requests are released immediately after `request.finished` instead of being retained in the global trace buffer
+
 ## SQL Tracing
 
 Prisma query tracing covers both ORM operations and raw queries.
@@ -140,6 +152,7 @@ export TRACE_REQUESTS_LIMIT=200
 export TRACE_EVENTS_LIMIT=800
 export TRACE_CAPTURE=resolve
 export TRACE_PERSIST_ON_ERROR=true
+export ENABLE_PROFILER=true
 ```
 
 Notes:
@@ -150,6 +163,7 @@ Notes:
 - `eventsLimit` defaults to `800`
 - `proteum dev` removes auto-persisted crash traces from `var/traces/` when the dev session stops
 - explicit `proteum trace export` files under `var/traces/exports/` are left in place
+- `ENABLE_PROFILER` reuses the same request instrumentation path but skips the retained global buffer and event timeline when dev trace is otherwise off
 
 ## Memory Model
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.2.0",
+	"version": "2.2.1",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/server/app/container/trace/index.ts

@@ -16,6 +16,9 @@ import {
     type TTraceSqlQueryCallerOrigin,
     type TTraceSqlQueryKind,
     type TTraceSummaryValue,
+    type TRequestProfiling,
+    type TRequestProfilingApiCall,
+    type TRequestProfilingSqlQuery,
     type TRequestTrace,
     type TTraceMemorySnapshot,
     type TRequestTraceListItem,
@@ -24,6 +27,7 @@ import type { TProteumManifest } from '@common/dev/proteumManifest';
 
 export type Config = {
     enable: boolean;
+    profilerEnable: boolean;
     requestsLimit: number;
     eventsLimit: number;
     capture: TTraceCaptureMode;
@@ -32,6 +36,12 @@ export type Config = {
 
 type TTraceInspectable = object | PrimitiveValue | bigint | symbol | null | undefined | (() => void);
 type TTraceDetails = { [key: string]: TTraceInspectable };
+type TSerializeJsonValueOptions = { redactSensitive: boolean };
+type TActiveRequestRecord = {
+    profiling: TRequestProfiling;
+    trace?: TRequestTrace;
+    capture?: TTraceCaptureMode;
+};
 
 const capturePriority: Record<TTraceCaptureMode, number> = { summary: 0, resolve: 1, deep: 2 };
 const sensitiveKeyPattern =
@@ -50,8 +60,13 @@ const isSensitiveKeyPath = (keyPath: string[]) => sensitiveKeyPattern.test(keyPa
 const summarizeString = (value: string) =>
     value.length <= maxStringLength ? value : `${value.slice(0, maxStringLength)}…`;
 
-const serializeJsonValue = (value: unknown, keyPath: string[], seen: WeakSet<object>): unknown => {
-    if (isSensitiveKeyPath(keyPath)) return `[redacted: Sensitive key ${keyPath[keyPath.length - 1] || 'value'}]`;
+const serializeJsonValue = (
+    value: unknown,
+    keyPath: string[],
+    seen: WeakSet<object>,
+    { redactSensitive }: TSerializeJsonValueOptions,
+): unknown => {
+    if (redactSensitive && isSensitiveKeyPath(keyPath)) return `[redacted: Sensitive key ${keyPath[keyPath.length - 1] || 'value'}]`;
     if (value === undefined || value === null) return value;
     if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return value;
     if (typeof value === 'bigint') return `${value.toString()}n`;
@@ -61,11 +76,14 @@ const serializeJsonValue = (value: unknown, keyPath: string[], seen: WeakSet<obj
     if (value instanceof Date) return value.toISOString();
     if (value instanceof Error) return { name: value.name, message: value.message, stack: value.stack };
     if (Buffer.isBuffer(value)) return `[Buffer ${value.byteLength} bytes]`;
-    if (value instanceof Map) return Array.from(value.entries()).map(([entryKey, entryValue], index) =>
-        serializeJsonValue([entryKey, entryValue], [...keyPath, `[${index}]`], seen),
-    );
+    if (value instanceof Map)
+        return Array.from(value.entries()).map(([entryKey, entryValue], index) =>
+            serializeJsonValue([entryKey, entryValue], [...keyPath, `[${index}]`], seen, { redactSensitive }),
+        );
     if (value instanceof Set) {
-        return Array.from(value.values()).map((entryValue, index) => serializeJsonValue(entryValue, [...keyPath, `[${index}]`], seen));
+        return Array.from(value.values()).map((entryValue, index) =>
+            serializeJsonValue(entryValue, [...keyPath, `[${index}]`], seen, { redactSensitive }),
+        );
     }
 
     if (typeof value !== 'object') return String(value);
@@ -74,19 +92,22 @@ const serializeJsonValue = (value: unknown, keyPath: string[], seen: WeakSet<obj
     seen.add(value);
 
     if (Array.isArray(value)) {
-        return value.map((item, index) => serializeJsonValue(item, [...keyPath, `[${index}]`], seen));
+        return value.map((item, index) => serializeJsonValue(item, [...keyPath, `[${index}]`], seen, { redactSensitive }));
     }
 
     const serialized: Record<string, unknown> = {};
     for (const [entryKey, entryValue] of Object.entries(value)) {
-        const nextValue = serializeJsonValue(entryValue, [...keyPath, entryKey], seen);
+        const nextValue = serializeJsonValue(entryValue, [...keyPath, entryKey], seen, { redactSensitive });
         if (nextValue !== undefined) serialized[entryKey] = nextValue;
     }
 
     return serialized;
 };
 
-const serializeCaptureValue = (value: TTraceInspectable, key: string) => serializeJsonValue(value, [key], new WeakSet<object>());
+const serializeCaptureValue = (value: TTraceInspectable, key: string) =>
+    serializeJsonValue(value, [key], new WeakSet<object>(), { redactSensitive: true });
+const serializeRawCaptureValue = (value: TTraceInspectable, key: string) =>
+    serializeJsonValue(value, [key], new WeakSet<object>(), { redactSensitive: false });
 
 const summarizeError = (error: Error): TTraceSummaryValue => ({
     kind: 'error',
@@ -181,7 +202,7 @@ const snapshotMemory = (): TTraceMemorySnapshot => {
 };
 
 export default class Trace {
-    private requests = new Map<string, TRequestTrace>();
+    private requests = new Map<string, TActiveRequestRecord>();
     private order: string[] = [];
     private armedCapture?: TTraceCaptureMode;
     private manifestCache?: {
@@ -202,10 +223,18 @@ export default class Trace {
         private config: Config,
     ) {}
 
-    public isEnabled() {
+    public isDevTraceEnabled() {
         return __DEV__ && this.config.enable && this.container.Environment.profile === 'dev';
     }
 
+    public isProfilingEnabled() {
+        return this.config.profilerEnable;
+    }
+
+    public shouldInstrumentRequests() {
+        return this.isDevTraceEnabled() || this.isProfilingEnabled();
+    }
+
     private getContextChannel() {
         return context.getStore() as ChannelInfos | undefined;
     }
@@ -270,8 +299,8 @@ export default class Trace {
         return undefined;
     }
 
-    private createSqlFingerprint(query: string) {
-        const normalized = query
+    private normalizeSqlQuery(query: string) {
+        return query
             .replace(sqlCommentPattern, ' ')
             .replace(sqlLineCommentPattern, ' ')
             .replace(/'([^']|'')*'/g, '?')
@@ -280,12 +309,43 @@ export default class Trace {
             .replace(/\s+/g, ' ')
             .trim()
             .toUpperCase();
+    }
+
+    private createSqlFingerprint(query: string) {
+        const normalized = this.normalizeSqlQuery(query);
 
         if (!normalized) return undefined;
 
         return createHash('sha1').update(normalized).digest('hex').slice(0, 12);
     }
 
+    private createProfiling(input: {
+        enabled: boolean;
+        id: string;
+        method: string;
+        path: string;
+        url: string;
+        profilerOrigin?: string;
+        profilerParentRequestId?: string;
+    }): TRequestProfiling {
+        return {
+            enabled: input.enabled,
+            requestId: input.id,
+            method: input.method,
+            path: input.path,
+            url: input.url,
+            startedAt: nowIso(),
+            profilerOrigin: input.profilerOrigin,
+            profilerParentRequestId: input.profilerParentRequestId,
+            apiCalls: [],
+            sqlQueries: [],
+        };
+    }
+
+    private getRecord(requestId: string) {
+        return this.requests.get(requestId);
+    }
+
     public armNextRequest(capture: string) {
         if (!isTraceCaptureMode(capture)) {
             throw new Error(`Unsupported trace capture mode "${capture}". Expected one of: ${traceCaptureModes.join(', ')}.`);
@@ -306,46 +366,72 @@ export default class Trace {
         profilerOrigin?: string;
         profilerParentRequestId?: string;
     }) {
-        if (!this.isEnabled()) return;
-
-        const capture = this.armedCapture ?? this.config.capture;
-        this.armedCapture = undefined;
-
-        const trace: TRequestTrace = {
+        const profilingEnabled = this.shouldInstrumentRequests();
+        const profiling = this.createProfiling({
+            enabled: profilingEnabled,
             id: input.id,
             method: input.method,
             path: input.path,
             url: input.url,
-            capture,
-            profilerSessionId: input.profilerSessionId,
             profilerOrigin: input.profilerOrigin,
             profilerParentRequestId: input.profilerParentRequestId,
-            startedAt: nowIso(),
-            droppedEvents: 0,
-            requestDataJson: serializeCaptureValue(input.data, 'requestData'),
-            calls: [],
-            sqlQueries: [],
-            events: [],
-        };
+        });
+        if (!profilingEnabled) return profiling;
+
+        const traceEnabled = this.isDevTraceEnabled();
+        const capture = traceEnabled ? this.armedCapture ?? this.config.capture : undefined;
+        this.armedCapture = undefined;
+
+        const trace =
+            traceEnabled
+                ? ({
+                      id: input.id,
+                      method: input.method,
+                      path: input.path,
+                      url: input.url,
+                      capture: capture as TTraceCaptureMode,
+                      profilerSessionId: input.profilerSessionId,
+                      profilerOrigin: input.profilerOrigin,
+                      profilerParentRequestId: input.profilerParentRequestId,
+                      startedAt: profiling.startedAt,
+                      droppedEvents: 0,
+                      requestDataJson: serializeCaptureValue(input.data, 'requestData'),
+                      calls: [],
+                      sqlQueries: [],
+                      events: [],
+                  } satisfies TRequestTrace)
+                : undefined;
+
+        this.requests.set(input.id, {
+            profiling,
+            trace,
+            capture,
+        });
+        this.activeMeasurements.set(input.id, { cpu: process.cpuUsage(), memory: snapshotMemory() });
 
-        this.requests.set(trace.id, trace);
-        this.activeMeasurements.set(trace.id, { cpu: process.cpuUsage(), memory: snapshotMemory() });
-        this.order.push(trace.id);
-        this.trimRequestBuffer();
+        if (trace) {
+            this.order.push(input.id);
+            this.trimRequestBuffer();
+            this.record(input.id, 'request.start', { method: input.method, path: input.path, url: input.url, headers: input.headers, data: input.data });
+        }
 
-        this.record(trace.id, 'request.start', { method: input.method, path: input.path, url: input.url, headers: input.headers, data: input.data });
+        return profiling;
     }
 
     public setRequestUser(requestId: string, user?: string) {
-        const trace = this.requests.get(requestId);
-        if (!trace) return;
+        const record = this.getRecord(requestId);
+        if (!record) return;
+
+        record.profiling.user = user;
+        if (!record.trace) return;
 
+        const trace = record.trace;
         trace.user = user;
         if (user) this.record(requestId, 'request.user', { user });
     }
 
     public getCapture(requestId: string) {
-        return this.requests.get(requestId)?.capture;
+        return this.getRecord(requestId)?.capture;
     }
 
     public shouldCapture(requestId: string, minimumCapture: TTraceCaptureMode) {
@@ -356,7 +442,8 @@ export default class Trace {
     }
 
     public record(requestId: string, type: TTraceEventType, details: TTraceDetails, minimumCapture: TTraceCaptureMode = 'summary') {
-        const trace = this.requests.get(requestId);
+        const record = this.getRecord(requestId);
+        const trace = record?.trace;
         if (!trace || !this.shouldCapture(requestId, minimumCapture)) return;
 
         if (trace.events.length >= this.config.eventsLimit) {
@@ -376,28 +463,41 @@ export default class Trace {
     }
 
     public finishRequest(requestId: string, output: { statusCode: number; user?: string; errorMessage?: string }) {
-        const trace = this.requests.get(requestId);
-        if (!trace) return;
+        const record = this.getRecord(requestId);
+        if (!record) return;
+
+        const { profiling, trace } = record;
+        if (output.user) profiling.user = output.user;
+        profiling.statusCode = output.statusCode;
+        profiling.errorMessage = output.errorMessage;
 
-        if (output.user) trace.user = output.user;
-        trace.statusCode = output.statusCode;
-        trace.errorMessage = output.errorMessage;
         const measurement = this.activeMeasurements.get(requestId);
         if (measurement) {
-            const cpu = process.cpuUsage(measurement.cpu);
-            trace.performance = {
-                cpu: {
-                    systemMicros: cpu.system,
-                    userMicros: cpu.user,
-                },
-                memory: {
-                    after: snapshotMemory(),
-                    before: measurement.memory,
-                },
-            };
             this.activeMeasurements.delete(requestId);
+
+            if (trace) {
+                const cpu = process.cpuUsage(measurement.cpu);
+                trace.performance = {
+                    cpu: {
+                        systemMicros: cpu.system,
+                        userMicros: cpu.user,
+                    },
+                    memory: {
+                        after: snapshotMemory(),
+                        before: measurement.memory,
+                    },
+                };
+            }
         }
 
+        profiling.finishedAt = nowIso();
+        profiling.durationMs = Math.max(0, Date.parse(profiling.finishedAt) - Date.parse(profiling.startedAt));
+
+        if (!trace) return;
+
+        if (output.user) trace.user = output.user;
+        trace.statusCode = output.statusCode;
+        trace.errorMessage = output.errorMessage;
         this.record(
             requestId,
             'request.finish',
@@ -405,8 +505,8 @@ export default class Trace {
             'summary',
         );
 
-        trace.finishedAt = nowIso();
-        trace.durationMs = Math.max(0, Date.parse(trace.finishedAt) - Date.parse(trace.startedAt));
+        trace.finishedAt = profiling.finishedAt;
+        trace.durationMs = profiling.durationMs;
 
         if (this.config.persistOnError && trace.statusCode >= 500) {
             trace.persistedFilepath = this.exportRequest(requestId);
@@ -433,13 +533,37 @@ export default class Trace {
             requestData?: TTraceInspectable;
         },
     ) {
-        const trace = this.requests.get(requestId);
-        if (!trace) return undefined;
+        const record = this.getRecord(requestId);
+        if (!record) return undefined;
         const channel = this.getContextChannel();
         const inferredServiceLabel = input.serviceLabel || channel?.serviceLabel || this.inferServiceLabelFromStack(new Error().stack);
+        const callIndex = record.profiling.apiCalls.length;
+        const startedAt = nowIso();
+        const callId = `${requestId}:call:${callIndex}`;
+
+        const profilingCall: TRequestProfilingApiCall = {
+            id: callId,
+            origin: input.origin,
+            label: input.label,
+            method: input.method || '',
+            path: input.path || '',
+            fetcherId: input.fetcherId,
+            connectedProjectNamespace: input.connectedProjectNamespace,
+            connectedControllerAccessor: input.connectedControllerAccessor,
+            ownerLabel: input.ownerLabel || channel?.ownerLabel,
+            ownerFilepath: input.ownerFilepath || channel?.ownerFilepath,
+            serviceLabel: inferredServiceLabel,
+            startedAt,
+            requestBodyJson: input.requestData !== undefined ? serializeRawCaptureValue(input.requestData, 'requestData') : undefined,
+        };
+
+        record.profiling.apiCalls.push(profilingCall);
+
+        const trace = record.trace;
+        if (!trace) return callId;
 
         const call: TTraceCall = {
-            id: `${requestId}:call:${trace.calls.length}`,
+            id: callId,
             parentId: input.parentId,
             origin: input.origin,
             label: input.label,
@@ -453,7 +577,7 @@ export default class Trace {
             serviceLabel: inferredServiceLabel,
             cacheKey: input.cacheKey || channel?.cacheKey,
             cachePhase: input.cachePhase || channel?.cachePhase,
-            startedAt: nowIso(),
+            startedAt,
             requestDataKeys: input.requestDataKeys || [],
             requestData: input.requestData !== undefined ? summarizeCaptureValue(input.requestData, trace.capture, 'requestData') : undefined,
             requestDataJson: input.requestData !== undefined ? serializeCaptureValue(input.requestData, 'requestData') : undefined,
@@ -461,7 +585,7 @@ export default class Trace {
         };
 
         trace.calls.push(call);
-        return call.id;
+        return callId;
     }
 
     public finishCall(
@@ -476,12 +600,24 @@ export default class Trace {
     ) {
         if (!callId) return;
 
-        const trace = this.requests.get(requestId);
-        const call = trace?.calls.find((candidate) => candidate.id === callId);
-        if (!trace || !call) return;
+        const record = this.getRecord(requestId);
+        const profilingCall = record?.profiling.apiCalls.find((candidate) => candidate.id === callId);
+        if (!record || !profilingCall) return;
+
+        profilingCall.finishedAt = nowIso();
+        profilingCall.durationMs = Math.max(0, Date.parse(profilingCall.finishedAt) - Date.parse(profilingCall.startedAt));
+        profilingCall.statusCode = output.statusCode;
+        profilingCall.errorMessage = output.errorMessage;
+        profilingCall.responseBodyJson = output.result !== undefined ? serializeRawCaptureValue(output.result, 'result') : undefined;
 
-        call.finishedAt = nowIso();
-        call.durationMs = Math.max(0, Date.parse(call.finishedAt) - Date.parse(call.startedAt));
+        const trace = record.trace;
+        if (!trace) return;
+
+        const call = trace.calls.find((candidate) => candidate.id === callId);
+        if (!call) return;
+
+        call.finishedAt = profilingCall.finishedAt;
+        call.durationMs = profilingCall.durationMs;
         call.statusCode = output.statusCode;
         call.errorMessage = output.errorMessage;
         call.resultKeys = output.resultKeys || [];
@@ -490,7 +626,7 @@ export default class Trace {
     }
 
     public setRequestResult(requestId: string, result: TTraceInspectable) {
-        const trace = this.requests.get(requestId);
+        const trace = this.getRecord(requestId)?.trace;
         if (!trace) return;
 
         trace.resultJson = serializeCaptureValue(result, 'result');
@@ -520,8 +656,8 @@ export default class Trace {
             target?: string;
         },
     ) {
-        const trace = this.requests.get(requestId);
-        if (!trace) return;
+        const record = this.getRecord(requestId);
+        if (!record) return;
         const channel = this.getContextChannel();
 
         const durationMs = Math.max(0, input.durationMs || 0);
@@ -530,10 +666,41 @@ export default class Trace {
         const startedAt =
             Number.isFinite(finishedAtMs) && durationMs > 0 ? new Date(finishedAtMs - durationMs).toISOString() : finishedAt;
         const fingerprint = this.createSqlFingerprint(input.query);
+        const normalizedQuery = this.normalizeSqlQuery(input.query) || undefined;
         const inferredServiceLabel = input.serviceLabel || channel?.serviceLabel || this.inferServiceLabelFromStack(new Error().stack);
 
+        const profilingQuery: TRequestProfilingSqlQuery = {
+            id: `${requestId}:sql:${record.profiling.sqlQueries.length}`,
+            callerCallId: input.callerCallId,
+            callerFetcherId: input.callerFetcherId,
+            callerLabel: input.callerLabel,
+            callerMethod: input.callerMethod || '',
+            callerOrigin: input.callerOrigin || 'request',
+            callerPath: input.callerPath || '',
+            durationMs,
+            finishedAt,
+            kind: input.kind,
+            model: input.model,
+            operation: input.operation,
+            fingerprint,
+            normalizedQuery,
+            ownerLabel: input.ownerLabel || channel?.ownerLabel,
+            ownerFilepath: input.ownerFilepath || channel?.ownerFilepath,
+            serviceLabel: inferredServiceLabel,
+            connectedNamespace: input.connectedNamespace || channel?.connectedNamespace,
+            paramsJson: input.paramsJson,
+            paramsText: input.paramsText,
+            query: input.query.trim(),
+            startedAt,
+            target: input.target,
+        };
+
+        record.profiling.sqlQueries.push(profilingQuery);
+        const trace = record.trace;
+        if (!trace) return;
+
         const sqlQuery: TTraceSqlQuery = {
-            id: `${requestId}:sql:${trace.sqlQueries.length}`,
+            id: profilingQuery.id,
             callerCallId: input.callerCallId,
             callerFetcherId: input.callerFetcherId,
             callerLabel: input.callerLabel,
@@ -546,6 +713,7 @@ export default class Trace {
             model: input.model,
             operation: input.operation,
             fingerprint,
+            normalizedQuery,
             ownerLabel: input.ownerLabel || channel?.ownerLabel,
             ownerFilepath: input.ownerFilepath || channel?.ownerFilepath,
             serviceLabel: inferredServiceLabel,
@@ -564,7 +732,7 @@ export default class Trace {
         return [...this.order]
             .reverse()
             .slice(0, limit)
-            .map((requestId) => this.requests.get(requestId))
+            .map((requestId) => this.getRecord(requestId)?.trace)
             .filter((trace): trace is TRequestTrace => trace !== undefined)
             .map((trace) => ({
                 id: trace.id,
@@ -593,21 +761,25 @@ export default class Trace {
         return [...this.order]
             .reverse()
             .slice(0, Math.max(1, limit))
-            .map((requestId) => this.requests.get(requestId))
+            .map((requestId) => this.getRecord(requestId)?.trace)
             .filter((trace): trace is TRequestTrace => trace !== undefined);
     }
 
     public getLatestRequest() {
         const latestRequestId = this.order[this.order.length - 1];
-        return latestRequestId ? this.requests.get(latestRequestId) : undefined;
+        return latestRequestId ? this.getRecord(latestRequestId)?.trace : undefined;
     }
 
     public getRequest(requestId: string) {
-        return this.requests.get(requestId);
+        return this.getRecord(requestId)?.trace;
+    }
+
+    public getProfiling(requestId: string) {
+        return this.getRecord(requestId)?.profiling;
     }
 
     public exportRequest(requestId: string, filepath?: string) {
-        const trace = this.requests.get(requestId);
+        const trace = this.getRecord(requestId)?.trace;
         if (!trace) throw new Error(`Trace ${requestId} was not found.`);
 
         const outputFilepath =
@@ -622,6 +794,15 @@ export default class Trace {
         return outputFilepath;
     }
 
+    public releaseRequest(requestId: string) {
+        const record = this.getRecord(requestId);
+        if (!record) return;
+        if (record.trace) return;
+
+        this.requests.delete(requestId);
+        this.activeMeasurements.delete(requestId);
+    }
+
     private trimRequestBuffer() {
         const overflow = this.order.length - this.config.requestsLimit;
         if (overflow <= 0) return;

package/server/services/prisma/index.ts

@@ -46,6 +46,12 @@ type TPrismaExtensionOperation = {
     query: (args: unknown) => Promise<unknown>;
 };
 
+declare global {
+    interface BigInt {
+        toJSON: () => number | string;
+    }
+}
+
 /*----------------------------------
 - HELPERS
 ----------------------------------*/
@@ -173,21 +179,18 @@ export default class ModelsManager extends Service<Config, Hooks, Application, A
                 'DATABASE_URL is required before starting the Models service. Prisma 7 no longer auto-loads runtime env files.',
             );
 
-        const shouldTraceQueries = this.app.container.Trace.isEnabled();
-        const prismaClient = shouldTraceQueries
-            ? new PrismaClient({
-                  adapter: createMariaDbAdapter(databaseUrl),
-                  log: [{ emit: 'event', level: 'query' }],
-              })
-            : new PrismaClient({
-                  adapter: createMariaDbAdapter(databaseUrl),
-              });
-
-        if (!shouldTraceQueries) {
-            this.client = prismaClient;
+        if (!this.app.container.Trace.shouldInstrumentRequests()) {
+            this.client = new PrismaClient({
+                adapter: createMariaDbAdapter(databaseUrl),
+            });
             return;
         }
 
+        const prismaClient = new PrismaClient({
+            adapter: createMariaDbAdapter(databaseUrl),
+            log: [{ emit: 'event', level: 'query' }],
+        });
+
         prismaClient.$on('query', (event: TPrismaQueryEvent) => this.traceQuery(event));
 
         this.client = prismaClient.$extends(

package/server/services/router/http/index.ts

@@ -510,7 +510,7 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
     private registerDevTraceRoutes(routes: express.Express) {
         if (!__DEV__ || this.app.env.profile !== 'dev') return;
 
-        if (this.app.container.Trace.isEnabled()) {
+        if (this.app.container.Trace.isDevTraceEnabled()) {
             routes.get('/__proteum/trace/requests', (req, res) => {
                 const rawLimit = Array.isArray(req.query.limit) ? req.query.limit[0] : req.query.limit;
                 const parsedLimit = typeof rawLimit === 'string' ? Number.parseInt(rawLimit, 10) : NaN;

package/server/services/router/index.ts

@@ -132,7 +132,13 @@ export type Config<
 // Set it as a function, so when we instanciate the services, we can callthis.router to pass the router instance in roiuter services
 type TRouterServicesList = { [serviceName: string]: AnyRouterService };
 
-export type Hooks = {};
+export type Hooks = {
+    request: { args: [request: ServerRequest<TServerRouter>] };
+    'request.finished': { args: [request: ServerRequest<TServerRouter>] };
+    resolve: { args: [request: ServerRequest<TServerRouter>] };
+    resolved: { args: [route: TMatchedRoute, request: ServerRequest<TServerRouter>, response: ServerResponse<TServerRouter>] };
+    render: { args: [page: Page<TServerRouter>] };
+};
 
 export type TControllerDefinition = {
     path?: string;
@@ -607,6 +613,32 @@ export default class ServerRouter<
     /*----------------------------------
     - RESOLUTION
     ----------------------------------*/
+    private async finalizeRequest(
+        request: ServerRequest<this>,
+        output: {
+            statusCode: number;
+            user?: string;
+            errorMessage?: string;
+        },
+    ) {
+        this.app.container.Trace.finishRequest(request.id, output);
+
+        try {
+            await this.runHook('request.finished', request);
+        } catch (error) {
+            const typedError =
+                error instanceof Error ? error : new Error(typeof error === 'string' ? error : 'Unknown request.finished hook error');
+
+            try {
+                await this.app.runHook('error', typedError, request);
+            } catch (hookError) {
+                console.error('request.finished hook error', typedError, 'Error hook failure', hookError);
+            }
+        } finally {
+            this.app.container.Trace.releaseRequest(request.id);
+        }
+    }
+
     public async middleware(req: express.Request, res: express.Response) {
         // Create request
         let requestId = uuid();
@@ -629,7 +661,7 @@ export default class ServerRouter<
             this,
         );
 
-        this.app.container.Trace.startRequest({
+        request.profiling = this.app.container.Trace.startRequest({
             id: request.id,
             method: request.method,
             path: request.path,
@@ -640,7 +672,7 @@ export default class ServerRouter<
             profilerOrigin: request.headers[profilerOriginHeader] || undefined,
             profilerParentRequestId: request.headers[profilerParentRequestIdHeader] || undefined,
         });
-        if (this.app.container.Trace.isEnabled()) res.setHeader(profilerTraceRequestIdHeader, request.id);
+        if (this.app.container.Trace.isDevTraceEnabled()) res.setHeader(profilerTraceRequestIdHeader, request.id);
         if (cachedPage) {
             this.app.container.Trace.record(
                 request.id,
@@ -659,7 +691,7 @@ export default class ServerRouter<
             // Bulk API Requests
             if (request.path === '/api' && typeof request.data.fetchers === 'object') {
                 await this.resolveApiBatch(request.data.fetchers, request);
-                this.app.container.Trace.finishRequest(request.id, {
+                await this.finalizeRequest(request, {
                     statusCode: request.res.statusCode || 200,
                     user: request.user?.email,
                 });
@@ -696,7 +728,7 @@ export default class ServerRouter<
                         },
                         'summary',
                     );
-                    this.app.container.Trace.finishRequest(request.id, {
+                    await this.finalizeRequest(request, {
                         statusCode: response.statusCode,
                         user: request.user?.email,
                     });
@@ -715,7 +747,7 @@ export default class ServerRouter<
                     'summary',
                 );
                 res.send(cachedPage.rendered);
-                this.app.container.Trace.finishRequest(request.id, {
+                await this.finalizeRequest(request, {
                     statusCode: response.statusCode,
                     user: request.user?.email,
                 });
@@ -739,19 +771,19 @@ export default class ServerRouter<
                 'summary',
             );
             res.send(response.data);
-            this.app.container.Trace.finishRequest(request.id, {
+            await this.finalizeRequest(request, {
                 statusCode: response.statusCode,
                 user: request.user?.email,
             });
         } else if (response.data !== 'true') {
-            this.app.container.Trace.finishRequest(request.id, {
+            await this.finalizeRequest(request, {
                 statusCode: res.statusCode || response.statusCode,
                 user: request.user?.email,
                 errorMessage: "Can't return data from the controller since response has already been sent via express.",
             });
             throw new Error("Can't return data from the controller since response has already been sent via express.");
         } else {
-            this.app.container.Trace.finishRequest(request.id, {
+            await this.finalizeRequest(request, {
                 statusCode: res.statusCode || response.statusCode,
                 user: request.user?.email,
             });

package/server/services/router/request/index.ts

@@ -10,7 +10,7 @@ import Bowser from 'bowser';
 
 // Core
 import BaseRequest from '@common/router/request';
-import type { TTraceCallOrigin } from '@common/dev/requestTrace';
+import type { TRequestProfiling, TTraceCallOrigin } from '@common/dev/requestTrace';
 
 // Specific
 import type { HttpMethod, HttpHeaders } from '..';
@@ -74,6 +74,7 @@ export default class ServerRequest<TRouter extends TAnyRouter = TAnyRouter> exte
     // Services
     public api: ApiClient;
     public traceCall?: TRequestTraceCallContext;
+    public profiling!: TRequestProfiling;
 
     /*----------------------------------
     - INITIALISATION