proteum 2.1.9 → 2.2.0

package/common/dev/performance.ts

@@ -7,6 +7,8 @@ import type {
     TTraceSqlQuery,
     TTraceSummaryValue,
 } from './requestTrace';
+import { buildRequestChain, explainOwner, type TDiagnoseChainItem } from './inspection';
+import type { TProteumManifest } from './proteumManifest';
 
 export const perfGroupByValues = ['path', 'route', 'controller'] as const;
 export const perfWindowPresets = ['1h', '6h', '24h', 'today', 'yesterday'] as const;
@@ -38,11 +40,14 @@ export type TRequestPerfCall = {
 export type TRequestPerfSql = {
     callerLabel: string;
     durationMs: number;
+    fingerprint?: string;
     id: string;
     kind: TTraceSqlQuery['kind'];
+    connectedNamespace?: string;
     model?: string;
     operation: string;
     query: string;
+    serviceLabel?: string;
     target?: string;
 };
 
@@ -53,6 +58,7 @@ export type TRequestPerformance = {
     callDurationMs: number;
     capture: TRequestTrace['capture'];
     controllerLabel: string;
+    chain?: TDiagnoseChainItem[];
     cpuSystemMs?: number;
     cpuTotalMs?: number;
     cpuUserMs?: number;
@@ -321,12 +327,16 @@ const formatCallLabel = (call: TTraceCall) => {
     }
 
     const reference = `${call.method} ${call.path}`.trim();
+    if (call.serviceLabel && call.label && reference) return `${call.serviceLabel} -> ${call.label} (${reference})`;
+    if (call.serviceLabel && reference) return `${call.serviceLabel} -> ${reference}`;
     if (call.label && reference) return `${call.label} (${reference})`;
     return call.label || reference || call.origin;
 };
 
 const formatSqlCallerLabel = (query: TTraceSqlQuery) => {
     const reference = `${query.callerMethod} ${query.callerPath}`.trim();
+    if (query.serviceLabel && query.callerLabel && reference) return `${query.serviceLabel} -> ${query.callerLabel} (${reference})`;
+    if (query.serviceLabel && reference) return `${query.serviceLabel} -> ${reference}`;
     if (query.callerLabel && reference) return `${query.callerLabel} (${reference})`;
     return query.callerLabel || reference || query.operation;
 };
@@ -472,7 +482,7 @@ const summarizeProfiles = (profiles: TRequestPerformance[]): TPerfTopSummary =>
     };
 };
 
-export const buildRequestPerformance = (trace: TRequestTrace): TRequestPerformance => {
+export const buildRequestPerformance = (trace: TRequestTrace, manifest?: TProteumManifest): TRequestPerformance => {
     const performance = trace.performance;
     const cpuUserMs = performance ? performance.cpu.userMicros / 1000 : undefined;
     const cpuSystemMs = performance ? performance.cpu.systemMicros / 1000 : undefined;
@@ -503,6 +513,7 @@ export const buildRequestPerformance = (trace: TRequestTrace): TRequestPerforman
         callDurationMs,
         capture: trace.capture,
         controllerLabel: findControllerLabel(trace),
+        chain: manifest ? buildRequestChain({ manifest, owner: explainOwner(manifest, trace.path), request: trace }) : undefined,
         cpuSystemMs,
         cpuTotalMs,
         cpuUserMs,
@@ -534,11 +545,14 @@ export const buildRequestPerformance = (trace: TRequestTrace): TRequestPerforman
             .map((query) => ({
                 callerLabel: formatSqlCallerLabel(query),
                 durationMs: query.durationMs,
+                fingerprint: query.fingerprint,
                 id: query.id,
                 kind: query.kind,
+                connectedNamespace: query.connectedNamespace,
                 model: query.model,
                 operation: query.operation,
                 query: query.query,
+                serviceLabel: query.serviceLabel,
                 target: query.target,
             })),
         htmlBytes: readNumber(renderEnd?.details.htmlLength),
@@ -582,7 +596,7 @@ export const buildPerfTopResponse = ({
 }): TPerfTopResponse => {
     const selectedGroupBy = perfGroupByValues.includes(groupBy) ? groupBy : 'path';
     const { requests: filteredRequests, window } = selectRequestsInWindow(requests, since);
-    const profiles = filteredRequests.map(buildRequestPerformance);
+    const profiles = filteredRequests.map((trace) => buildRequestPerformance(trace));
     const groups = new Map<string, TRequestPerformance[]>();
 
     for (const profile of profiles) {
@@ -738,7 +752,7 @@ export const buildPerfMemoryResponse = ({
 }): TPerfMemoryResponse => {
     const selectedGroupBy = perfGroupByValues.includes(groupBy) ? groupBy : 'path';
     const { requests: filteredRequests, window } = selectRequestsInWindow(requests, since);
-    const profiles = filteredRequests.map(buildRequestPerformance);
+    const profiles = filteredRequests.map((trace) => buildRequestPerformance(trace));
     const groups = new Map<string, TRequestPerformance[]>();
 
     for (const profile of profiles) {
@@ -793,7 +807,7 @@ export const buildPerfMemoryResponse = ({
     };
 };
 
-export const resolvePerfRequest = (requests: TRequestTrace[], requestOrPath: string) => {
+export const resolvePerfRequest = (requests: TRequestTrace[], requestOrPath: string, manifest?: TProteumManifest) => {
     const normalized = requestOrPath.trim();
     if (!normalized) throw new Error('Perf request id or path is required.');
 
@@ -805,5 +819,5 @@ export const resolvePerfRequest = (requests: TRequestTrace[], requestOrPath: str
         throw new Error(`Could not find a traced request for "${requestOrPath}".`);
     }
 
-    return buildRequestPerformance(request);
+    return buildRequestPerformance(request, manifest);
 };

package/common/dev/profiler.ts

@@ -4,6 +4,7 @@ export const profilerTraceRequestIdHeader = 'x-proteum-trace-request-id';
 export const profilerSessionIdHeader = 'x-proteum-profiler-session-id';
 export const profilerOriginHeader = 'x-proteum-profiler-origin';
 export const profilerParentRequestIdHeader = 'x-proteum-profiler-parent-request-id';
+export const profilerConnectedNamespaceHeader = 'x-proteum-profiler-connected-namespace';
 
 export type TProfilerUiState = 'expanded' | 'minimized' | 'pinned-handle';
 export type TProfilerPanel =

package/common/dev/proteumManifest.ts

@@ -14,6 +14,7 @@ export type TProteumManifestDiagnostic = {
     message: string;
     filepath: string;
     sourceLocation?: TProteumManifestSourceLocation;
+    fixHint?: string;
     relatedFilepaths?: string[];
 };
 
@@ -86,7 +87,7 @@ export type TProteumManifestRoute = {
     invalidOptionKeys: string[];
     reservedOptionKeys: string[];
     optionsRaw?: string;
-    hasSetup: boolean;
+    hasData: boolean;
     chunkId?: string;
     chunkFilepath?: string;
     scope: TProteumManifestScope;
@@ -101,7 +102,7 @@ export type TProteumManifestLayout = {
 };
 
 export type TProteumManifest = {
-    version: 9;
+    version: 10;
     app: {
         root: string;
         coreRoot: string;
@@ -125,8 +126,8 @@ export type TProteumManifest = {
         };
     };
     conventions: {
-        routeSetupOptionKeys: string[];
-        reservedRouteSetupKeys: string[];
+        routeOptionKeys: string[];
+        reservedRouteOptionKeys: string[];
     };
     env: {
         source: string;

package/common/dev/requestTrace.ts

@@ -28,7 +28,6 @@ export const traceEventTypes = [
     'resolve.not-found',
     'controller.start',
     'controller.result',
-    'setup.options',
     'context.create',
     'page.data',
     'ssr.payload',
@@ -36,6 +35,8 @@ export const traceEventTypes = [
     'render.end',
     'response.send',
     'request.finish',
+    'cache.hit',
+    'cache.write',
     'error',
 ] as const;
 
@@ -81,6 +82,11 @@ export type TTraceCall = {
     fetcherId?: string;
     connectedProjectNamespace?: string;
     connectedControllerAccessor?: string;
+    ownerLabel?: string;
+    ownerFilepath?: string;
+    serviceLabel?: string;
+    cacheKey?: string;
+    cachePhase?: string;
     startedAt: string;
     finishedAt?: string;
     durationMs?: number;
@@ -107,6 +113,11 @@ export type TTraceSqlQuery = {
     kind: TTraceSqlQueryKind;
     model?: string;
     operation: string;
+    fingerprint?: string;
+    ownerLabel?: string;
+    ownerFilepath?: string;
+    serviceLabel?: string;
+    connectedNamespace?: string;
     paramsJson?: unknown;
     paramsText?: string;
     query: string;

package/common/router/contracts.ts

@@ -3,24 +3,21 @@
 ----------------------------------*/
 
 // Core
-import type { TFrontRenderer, TPageSetup } from './response/page';
+import type { TFrontRenderer, TPageDataProvider } from './response/page';
 import type { TRouteOptions } from '.';
 
 /*----------------------------------
 - PUBLIC API
 ----------------------------------*/
 
-// Supported `Router.page(...)` registration signatures shared by client and compiler code.
+// Supported `Router.page(...)` registration signature shared by client and compiler code.
 export type TRegisterPageArgs<TProvidedData extends {} = {}, TPageOptions extends {} = TRouteOptions> =
-    | [path: string, renderer: TFrontRenderer<TProvidedData>]
-    | [path: string, setup: TPageSetup<TProvidedData>, renderer: TFrontRenderer<TProvidedData>]
-    | [path: string, options: Partial<TPageOptions>, renderer: TFrontRenderer<TProvidedData>]
-    | [
-          path: string,
-          options: Partial<TPageOptions>,
-          setup: TPageSetup<TProvidedData>,
-          renderer: TFrontRenderer<TProvidedData>,
-      ];
+    [
+        path: string,
+        options: Partial<TPageOptions>,
+        data: TPageDataProvider<TProvidedData> | null,
+        renderer: TFrontRenderer<TProvidedData>,
+    ];
 
 // Serialized SSR route description exchanged between build output and runtime.
 export type TSsrUnresolvedRoute<TKey = number | string> = { chunk: string } & (

package/common/router/index.ts

@@ -18,7 +18,7 @@ import type { TAuthCheckInput, TAuthTrackingContext } from '@server/services/aut
 import type { TAppArrowFunction } from '@common/app';
 
 // Specfic
-import type { default as Page, TFrontRenderer, TPageSetup } from './response/page';
+import type { default as Page, TFrontRenderer, TPageDataProvider } from './response/page';
 
 /*----------------------------------
 - TYPES: ROUTES
@@ -40,6 +40,7 @@ type TRouteBase<RouterContext = unknown, TResult = any> = {
 
     // Execute
     schema?: zod.ZodSchema;
+    data?: TPageDataProvider | null;
     controller: TRouteController<RouterContext, TResult>;
     options: TRouteOptions;
 };
@@ -76,7 +77,6 @@ export type TRouteOptions = {
     id?: string;
     filepath?: string;
     sourceLocation?: { line: number; column: number };
-    setup?: TPageSetup;
 
     // Indexing
     bodyId?: string;

package/common/router/pageData.ts

@@ -0,0 +1,72 @@
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+import type { TAnyRoute, TRouteOptions } from '.';
+
+export const routeOptionKeys = [
+    'bodyId',
+    'priority',
+    'preload',
+    'domain',
+    'accept',
+    'raw',
+    'auth',
+    'authTracking',
+    'redirectLogged',
+    'static',
+    'whenStatic',
+    'canonicalParams',
+    'layout',
+    'TESTING',
+    'logging',
+] as const satisfies (keyof TRouteOptions)[];
+
+export const reservedRouteOptionKeys = ['id', 'filepath', 'sourceLocation', 'data'] as const;
+
+const routeOptionKeysSet = new Set<string>(routeOptionKeys);
+const reservedRouteOptionKeysSet = new Set<string>(reservedRouteOptionKeys);
+const reservedPageDataKeys = new Set<string>([
+    ...routeOptionKeys,
+    ...reservedRouteOptionKeys,
+    ...routeOptionKeys.map((key) => `_${key}`),
+    ...reservedRouteOptionKeys.map((key) => `_${key}`),
+]);
+
+const formatRouteTarget = (route: TAnyRoute) => ('code' in route ? String(route.code) : route.path || '(unknown route)');
+
+const formatRouteSource = (route: TAnyRoute) => {
+    const filepath = route.options.filepath || 'unknown file';
+    const line = route.options.sourceLocation?.line;
+    const column = route.options.sourceLocation?.column;
+
+    if (!line) return filepath;
+    if (!column) return `${filepath}:${line}`;
+    return `${filepath}:${line}:${column}`;
+};
+
+export const getRouteOptionKey = (key: string) => {
+    if (reservedRouteOptionKeysSet.has(key)) throw new Error(`"${key}" is a reserved Router.page option key.`);
+
+    return routeOptionKeysSet.has(key) ? (key as keyof TRouteOptions) : null;
+};
+
+export const validatePageDataResult = (route: TAnyRoute, result: unknown) => {
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        throw new Error(
+            `Router.page data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} must return an object. ` +
+                `If the page has no data loader, pass null as the third argument.`,
+        );
+    }
+
+    for (const key of Object.keys(result)) {
+        if (!reservedPageDataKeys.has(key)) continue;
+
+        throw new Error(
+            `Router.page data for ${formatRouteTarget(route)} in ${formatRouteSource(route)} cannot return reserved key "${key}". ` +
+                `Move route behavior into the explicit Router.page(path, options, data, render) options argument.`,
+        );
+    }
+
+    return result as TObjetDonnees;
+};

package/common/router/register.ts

@@ -11,65 +11,29 @@ import type { TRegisterPageArgs } from './contracts';
 
 // types
 import type { TRouteOptions } from '.';
-import type { TFrontRenderer, TPageSetup } from './response/page';
+import type { TPageDataProvider } from './response/page';
 
 /*----------------------------------
 - UTILS
 ----------------------------------*/
 
 export const getRegisterPageArgs = (...args: TRegisterPageArgs<any, TRouteOptions>) => {
-    let path: string;
-    let options: Partial<TRouteOptions> = {};
-    let setup: TPageSetup | undefined;
-    let renderer: TFrontRenderer;
+    const [path, options, data, renderer] = args;
 
-    if (args.length === 2) {
-        [path, renderer] = args;
-    } else if (args.length === 3) {
-        const [pathArg, optionsOrSetupArg, rendererArg] = args;
-        path = pathArg;
-        renderer = rendererArg;
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw new Error(`Router.page(${JSON.stringify(path)}) requires an explicit options object as its second argument.`);
+    }
 
-        if (typeof optionsOrSetupArg === 'function') setup = optionsOrSetupArg;
-        else options = optionsOrSetupArg;
-    } else {
-        const [pathArg, optionsArg, setupArg, rendererArg] = args;
-        path = pathArg;
-        options = optionsArg;
-        setup = setupArg;
-        renderer = rendererArg;
+    if (data !== null && typeof data !== 'function') {
+        throw new Error(
+            `Router.page(${JSON.stringify(path)}) requires a data function or null as its third argument.`,
+        );
     }
 
     // Automatic layout form the nearest _layout folder using static options only.
     const layout = getLayout(path, options);
 
-    return { path, options, setup, renderer, layout };
-};
-
-export const getRegisterPageOptions = (...args: TRegisterPageArgs<any, TRouteOptions>) => {
-    let path: string;
-    let options: Partial<TRouteOptions> = {};
-    let setup: TPageSetup | undefined;
-    let renderer: TFrontRenderer;
-
-    if (args.length === 2) {
-        [path, renderer] = args;
-    } else if (args.length === 3) {
-        const [pathArg, optionsOrSetupArg, rendererArg] = args;
-        path = pathArg;
-        renderer = rendererArg;
-
-        if (typeof optionsOrSetupArg === 'function') setup = optionsOrSetupArg;
-        else options = optionsOrSetupArg;
-    } else {
-        const [pathArg, optionsArg, setupArg, rendererArg] = args;
-        path = pathArg;
-        options = optionsArg;
-        setup = setupArg;
-        renderer = rendererArg;
-    }
-
-    return { path, options, setup, renderer };
+    return { path, options, data: data as TPageDataProvider | null, renderer, layout };
 };
 
 export const buildRegex = (path: string) => {

package/common/router/response/page.ts

@@ -8,27 +8,38 @@ import type { Thing } from 'schema-dts';
 
 // Core libs
 import type { ClientContext } from '@/client/context';
-import { ClientOrServerRouter, TErrorRoute, TPageErrorRoute, TPageRoute, TRoute } from '@common/router';
+import { ClientOrServerRouter, TErrorRoute, TPageErrorRoute, TPageRoute, TRoute, TRouteOptions } from '@common/router';
 import type { TFetcher, TFetcherList } from '@common/router/request/api';
-import { splitRouteSetupResult } from '@common/router/pageSetup';
+import { validatePageDataResult } from '@common/router/pageData';
 
 /*----------------------------------
 - TYPES
 ----------------------------------*/
 
-export type TPageSetupContext = ClientContext;
+export type TPageDataContext = ClientContext;
 
 export type TPageRenderContext = With<ClientContext, 'page'>;
 
+type TPageResponseContext = {
+    route: { options: Partial<TRouteOptions> };
+    request: {
+        url: string;
+        data: TObjetDonnees;
+        api: {
+            fetchSync(fetchers: TFetcherList, alreadyLoadedData: {}): Promise<TObjetDonnees>;
+        };
+    };
+};
+
 export type TResolvedPageData<TProvidedData extends {} = {}> = {
     [Property in keyof TProvidedData]: TProvidedData[Property] extends TFetcher<infer TData>
         ? TData
         : Awaited<TProvidedData[Property]>;
 };
 
-// The function that prepares route config and SSR data before rendering.
-export type TPageSetup<TProvidedData extends {} = {}> = (
-    context: TPageSetupContext & {
+// The function that prepares SSR data before rendering.
+export type TPageDataProvider<TProvidedData extends {} = {}> = (
+    context: TPageDataContext & {
         // URL query parameters
         // TODO: typings
         data: { [key: string]: string | number };
@@ -36,7 +47,7 @@ export type TPageSetup<TProvidedData extends {} = {}> = (
 ) => TProvidedData;
 
 export type TDataProvider<TProvidedData extends {} = TFetcherList> = (
-    context: TPageSetupContext & { data: { [key: string]: PrimitiveValue } },
+    context: TPageDataContext & { data: { [key: string]: PrimitiveValue } },
 ) => TProvidedData;
 
 // The function that renders routes
@@ -68,7 +79,7 @@ const debug = false;
 export default abstract class PageResponse<
     TRouter extends ClientOrServerRouter = ClientOrServerRouter,
     TRouteLike extends TRoute | TErrorRoute = TPageRoute | TPageErrorRoute,
-    TContext extends TPageRenderContext = TPageRenderContext,
+    TContext extends TPageResponseContext = TPageResponseContext,
 > {
     // Metadata
     public chunkId?: string;
@@ -100,18 +111,19 @@ export default abstract class PageResponse<
         this.url = context.request.url;
     }
 
-    private resolveSetup() {
-        const setup = this.route.options.setup;
-        if (!setup) return { options: {}, data: {} };
+    private resolveDataProviderResult() {
+        const dataProvider = 'data' in this.route ? this.route.data : undefined;
+        if (!dataProvider) return {};
 
-        const setupContext = { ...this.context, data: this.context.request.data } as Parameters<typeof setup>[0];
+        const dataContext = { ...this.context, data: this.context.request.data } as unknown as Parameters<
+            typeof dataProvider
+        >[0];
 
-        return splitRouteSetupResult(setup(setupContext) || {});
+        return validatePageDataResult(this.route, dataProvider(dataContext));
     }
 
     private createFetchers() {
-        const { options, data } = this.resolveSetup();
-        this.route.options = { ...this.route.options, ...options };
+        const data = this.resolveDataProviderResult();
         this.chunkId = this.route.options.id;
 
         return data as TFetcherList;
@@ -126,7 +138,7 @@ export default abstract class PageResponse<
             const layoutContext = {
                 ...this.context,
                 data: this.context.request.data,
-            } as Parameters<typeof this.layout.data>[0];
+            } as unknown as Parameters<typeof this.layout.data>[0];
             const fetchers = this.layout.data(layoutContext);
             this.fetchers = { ...this.fetchers, ...fetchers };
         }

package/docs/dev-sessions.md

@@ -1,6 +1,6 @@
 # Dev Sessions
 
-Proteum ships a dev-only auth bootstrap command so agents, Playwright runs, and local debugging can start from an authenticated state without driving the login UI.
+Proteum ships a dev-only auth bootstrap command so `proteum verify browser`, Playwright runs, and local debugging can start from an authenticated state without driving the login UI.
 
 ## When To Use It
 
@@ -37,6 +37,7 @@ Behavior:
 - remote mode talks to an already running `proteum dev` instance
 - the command requires an explicit email and optionally asserts a role before returning the session
 - the command is available only in dev mode
+- browser verification flows should keep browser state app-local and disposable through `proteum verify browser` or direct Playwright instead of reusing a shared temp profile
 
 ## Output Contract
 
@@ -67,20 +68,23 @@ curl -H "$(jq -r '.curlCookieHeader' session.json)" http://localhost:3101/api/Au
 ## Agent Guidance
 
 - Prefer `proteum session` over UI login automation when the goal is to test or debug protected application behavior.
+- Prefer `proteum verify browser` for focused browser-visible verification. When lower-level control is required, use direct Playwright with a disposable profile.
 - Use UI login automation only when the auth UX itself is the feature under test.
 - Pair it with `proteum diagnose` for a fast protected-route summary, `proteum perf request` for a one-request timing breakdown, then use `proteum trace` when you need lower-level request events.
+- Only the final verifier agent should usually run browser flows. Earlier agents should stay on `orient`, `verify owner`, `verify request`, and request-level diagnostics unless browser execution is required.
 
 Typical flow:
 
 ```bash
-proteum trace arm --capture deep --port 3101
+proteum orient /dashboard
 proteum session admin@example.com --role ADMIN --port 3101 --json > session.json
-# add the returned cookie in Playwright, then load the protected page once
-proteum diagnose /dashboard --port 3101
+proteum diagnose /dashboard --hit /dashboard --port 3101
 proteum perf request /dashboard --port 3101
 proteum trace latest --port 3101
 ```
 
+When `proteum verify browser <path>` is available in the target app, it uses the same fresh per-run browser workspace model under `var/proteum/browser/<run-id>` and should be preferred over ad hoc shared Playwright profile reuse.
+
 ## Dev HTTP Endpoint
 
 The CLI uses the same dev-only endpoint exposed by the running app: