@nodefony/framework 10.0.0-beta.3 → 10.0.0-beta.5

package/dist/nodefony/src/FrameworkAdminApi.js

@@ -1,7 +1,7 @@
 import router_default from "../service/router.js";
 import { createPlaygroundEndpoints } from "./PlaygroundAdminApi.js";
-import { parseFilters, parsePageQuery } from "nodefony";
-//#region nodefony/src/FrameworkAdminApi.ts
+import { PageQueryError, parseFilters, parsePageQuery } from "nodefony";
+// nodefony/src/FrameworkAdminApi.ts
 /**
 * Capacités de page d'un endpoint, ÉVALUÉES sous filet.
 *
@@ -29,6 +29,34 @@ function readPageCapabilities(caps) {
 	}
 }
 /**
+* Lit le paramètre `filters` de `routes/page` : un tableau JSON de
+* `{ key, op, value }`. Absent → aucun filtre.
+*
+* @throws PageQueryError (400) si le JSON est cassé ou d'une autre forme — un
+*   filtre ignoré rendrait TOUTES les routes, lues comme son résultat.
+*/
+function parseRouteFilters(raw) {
+	if (!raw) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new PageQueryError(`Invalid "filters": not JSON.`);
+	}
+	if (!Array.isArray(parsed)) throw new PageQueryError(`Invalid "filters": expected a JSON array.`);
+	const entries = parsed;
+	const filters = [];
+	for (const item of entries) {
+		if (typeof item !== "object" || item === null || !("key" in item) || !("op" in item) || typeof item.key !== "string" || typeof item.op !== "string") throw new PageQueryError(`Invalid "filters": each entry needs a string "key" and "op".`);
+		filters.push({
+			key: item.key,
+			op: item.op,
+			value: "value" in item ? item.value : void 0
+		});
+	}
+	return filters;
+}
+/**
 * Producteur `IAdminApi` du module **framework** — exposé sous
 * `/nodefony/framework/api/*`.
 *
@@ -205,13 +233,7 @@ function createFrameworkAdminApi(broker, opts) {
 				});
 				parseFilters(request.query, {}, { accepts: ["filters"] });
 				const search = query.q?.toLowerCase() ?? "";
-				let filters = [];
-				try {
-					const raw = one(request.query.filters);
-					if (raw) filters = JSON.parse(raw);
-				} catch {
-					filters = [];
-				}
+				const filters = parseRouteFilters(one(request.query.filters));
 				let rows = router_default.routes.map(serializeRoute);
 				if (search) rows = rows.filter((r) => matchesSearch(r, search));
 				for (const f of filters) rows = rows.filter((r) => matchOp(cell(r, f.key), f.op, f.value));
@@ -297,5 +319,4 @@ function createFrameworkAdminApi(broker, opts) {
 		adminEndpoints: () => endpoints
 	};
 }
-//#endregion
 export { createFrameworkAdminApi };

package/dist/nodefony/src/KernelAdminApi.js

@@ -2,10 +2,10 @@ import { CORE_PACKAGE, checkOutdated, countModuleDocs, listModuleDocs, listModul
 import { getResolvedPath, navigateSchemaNode, nodeFlags, notEditableReason, recipeFor, validateLeafValue } from "./configMutation.js";
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import { GitService, Syslog, aggregateProvenance, collectDevStatus, collectEnvShortcuts, computeConfigProvenance, defaultAppConfig, extractJsonSchemaDefaults, extractMarkdownSection, flattenConfigSchema, getActiveLogDriver, isFrameworkRepository, listLogDrivers, outlineMarkdown, parseNfEnvOverrides, parseStoreManifest, readResolvedPath, resumeSupervisor, runAppContributions, suspendSupervisor, withResolvedPath } from "nodefony";
+import { GitService, Syslog, aggregateProvenance, collectDevStatus, collectEnvShortcuts, computeConfigProvenance, defaultAppConfig, extractJsonSchemaDefaults, extractMarkdownSection, flattenConfigSchema, getActiveLogDriver, isFrameworkRepository, listLogDrivers, outlineMarkdown, parseNfEnvOverrides, parseStoreManifest, readResolvedPath, redactUrlCredentials, resumeSupervisor, runAppContributions, suspendSupervisor, withResolvedPath } from "nodefony";
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-//#region nodefony/src/KernelAdminApi.ts
+// nodefony/src/KernelAdminApi.ts
 /** Clé du pseudo-module core dans Studio (cf carte "Core" / `resolveCorePath`). */
 const CORE_KEY = "core";
 /** Racine projet — pour ne PAS exposer de chemin absolu (sécu). */
@@ -109,7 +109,7 @@ const SECRET_KEY = /(?:^|[a-z0-9])(secret|password|passwd|passphrase|credential|
 function safeConfig(value, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
 	if (typeof value === "function") return "[Function]";
 	if (typeof value === "bigint") return value.toString();
-	if (typeof value === "string") return stripAbs(value);
+	if (typeof value === "string") return stripAbs(redactUrlCredentials(value));
 	if (value === null || typeof value !== "object") return value;
 	if (depth > 5) return "[depth limit]";
 	if (seen.has(value)) return "[Circular]";
@@ -441,7 +441,6 @@ function createKernelAdminApi(kernel) {
 	const devGuard = () => kernel.environment === "development" || Boolean(kernel.debug);
 	const repoRoot = process.cwd();
 	const relPath = (p) => p?.startsWith(repoRoot) ? p.slice(repoRoot.length).replace(/^[/\\]+/, "") || "." : p ?? null;
-	const redactInfraUrl = (url) => url.replace(/\/\/[^/@]*@/, "//***@");
 	const buildConfigEntries = () => {
 		const modules = kernel.getModules();
 		const entries = [];
@@ -736,8 +735,8 @@ function createKernelAdminApi(kernel) {
 			handler: () => {
 				const infra = kernel.infra;
 				const entriesBySeg = new Map(buildConfigEntries().map((e) => [e.seg, e]));
-				const dbUrl = infra.database ? redactInfraUrl(infra.database.url) : null;
-				const cacheUrl = infra.cache ? redactInfraUrl(infra.cache.url) : null;
+				const dbUrl = infra.database ? redactUrlCredentials(infra.database.url) : null;
+				const cacheUrl = infra.cache ? redactUrlCredentials(infra.cache.url) : null;
 				const storeEndpoint = (res) => {
 					if (res.location) return void 0;
 					if (res.resolved === "redis") return cacheUrl ?? void 0;
@@ -776,8 +775,8 @@ function createKernelAdminApi(kernel) {
 						} : null,
 						cache: infra.cache ? { url: cacheUrl } : null,
 						logs: infra.logs ? {
-							lokiUrl: infra.logs.lokiUrl ? redactInfraUrl(infra.logs.lokiUrl) : null,
-							opensearchUrl: infra.logs.opensearchUrl ? redactInfraUrl(infra.logs.opensearchUrl) : null
+							lokiUrl: infra.logs.lokiUrl ? redactUrlCredentials(infra.logs.lokiUrl) : null,
+							opensearchUrl: infra.logs.opensearchUrl ? redactUrlCredentials(infra.logs.opensearchUrl) : null
 						} : null
 					},
 					stores: kernel.storeResolutions.map((res) => {
@@ -1367,5 +1366,4 @@ function createKernelAdminApi(kernel) {
 		adminEndpoints: () => endpoints
 	};
 }
-//#endregion
 export { createKernelAdminApi, nodefonyPackageCandidates, safeConfig };

package/dist/nodefony/src/PlaygroundAdminApi.js

@@ -1,7 +1,8 @@
 import { extractActionScopes, resolveActionMeta } from "../decorators/routerDecorators.js";
 import router_default from "../service/router.js";
 import AdminApiController from "../controller/AdminApiController.js";
-//#region nodefony/src/PlaygroundAdminApi.ts
+import { standardJsonSchemaOf } from "nodefony";
+// nodefony/src/PlaygroundAdminApi.ts
 /** Normalise `requirements.methods` (string | string[]) → tableau majuscule. */
 function methodsOf(route) {
 	const m = route.requirements.methods ?? route.method;
@@ -15,11 +16,79 @@ function publicDefaults(route) {
 	for (const [k, v] of Object.entries(route.defaults)) if (k !== "controller") out[k] = v;
 	return out;
 }
+/** Source du formulaire pour chaque partie d'un schéma de route. */
+const PART_SOURCE = {
+	params: "param",
+	query: "query",
+	body: "body",
+	headers: "headers"
+};
+/** JSON Schema d'entrée d'un schéma, ou `null` s'il ne sait pas se décrire. */
+function describeSchema(schema) {
+	const converter = standardJsonSchemaOf(schema);
+	if (converter === null) return null;
+	try {
+		return converter.input({ target: "draft-2020-12" });
+	} catch {
+		return null;
+	}
+}
+/** Les champs de premier niveau d'un JSON Schema objet. */
+function propertiesOf(json) {
+	const properties = json?.properties;
+	return typeof properties === "object" && properties !== null ? Object.keys(properties) : [];
+}
+/**
+* Les entrées d'une action à schéma, au format des paramètres décorés, et le
+* contrat décrit partie par partie.
+*/
+function schemaParams(schema, bodyStream) {
+	const params = [];
+	const described = {};
+	for (const part of [
+		"params",
+		"query",
+		"body",
+		"headers"
+	]) {
+		const partSchema = schema[part];
+		if (partSchema === void 0) continue;
+		const json = describeSchema(partSchema);
+		described[part] = json;
+		const source = PART_SOURCE[part];
+		if (part === "body") {
+			params.push({
+				source,
+				key: null,
+				index: 0,
+				stream: false
+			});
+			continue;
+		}
+		for (const key of propertiesOf(json)) params.push({
+			source,
+			key,
+			index: 0,
+			stream: false
+		});
+	}
+	if (bodyStream) params.push({
+		source: "body",
+		key: null,
+		index: 0,
+		stream: true
+	});
+	return {
+		params,
+		described
+	};
+}
 /** Sérialise une route en action playground (métadonnées figées, JSON-safe). */
 function serializeAction(route) {
 	const meta = resolveActionMeta(route);
 	const methods = methodsOf(route);
 	const scopes = route.controller && route.classMethod ? extractActionScopes(route.controller, route.classMethod) : [];
+	const fromSchema = meta.schema !== null ? schemaParams(meta.schema, meta.bodyStream) : null;
 	return {
 		route: route.name,
 		path: route.path ?? null,
@@ -28,12 +97,13 @@ function serializeAction(route) {
 		action: route.classMethod ?? null,
 		variables: [...route.variables],
 		defaults: publicDefaults(route),
-		params: meta.paramsMeta?.map((p) => ({
+		params: fromSchema?.params ?? meta.paramsMeta?.map((p) => ({
 			source: p.source,
 			key: p.key ?? null,
 			index: p.index,
 			stream: p.stream === true
 		})).sort((a, b) => a.index - b.index) ?? [],
+		schema: fromSchema?.described ?? null,
 		guards: {
 			security: meta.security ? { clauses: meta.security.clauses.map((c) => ({
 				anyOf: [...c.anyOf],
@@ -93,5 +163,4 @@ function createPlaygroundEndpoints() {
 		handler: () => buildPlaygroundSnapshot()
 	}];
 }
-//#endregion
 export { buildPlaygroundSnapshot, createPlaygroundEndpoints };

package/dist/nodefony/src/RedisIdempotencyStore.js

@@ -1,5 +1,5 @@
 import { assertPageQuery } from "nodefony";
-//#region nodefony/src/RedisIdempotencyStore.ts
+// nodefony/src/RedisIdempotencyStore.ts
 /** Préfixe namespacé des clés d'idempotence dans Redis. */
 /**
 * Préfixe HISTORIQUE des clés d'idempotence. Utilisé tel quel par une application
@@ -42,6 +42,50 @@ function decodeCursor(cursor) {
 	};
 }
 /**
+* Reconstruit une entrée relue du store, ou `null` si sa forme est inattendue.
+* La valeur vient de Redis, pas de ce processus : une entrée « terminée » sans
+* réponse rejouerait `undefined` comme une réponse HTTP.
+*/
+function toEntry(v) {
+	if (typeof v !== "object" || v === null || !("s" in v) || !("f" in v)) return null;
+	const f = v.f;
+	if (typeof f !== "string") return null;
+	if (v.s === "if") return {
+		s: "if",
+		f
+	};
+	if (v.s !== "d" || !("r" in v)) return null;
+	const r = toResponse(v.r);
+	return r === null ? null : {
+		s: "d",
+		f,
+		r
+	};
+}
+/** Reconstruit une réponse mémorisée, ou `null` si sa forme est inattendue. */
+function toResponse(v) {
+	if (typeof v !== "object" || v === null || !("status" in v)) return null;
+	const status = v.status;
+	if (typeof status !== "number") return null;
+	const body = "body" in v ? v.body : void 0;
+	if (!("headers" in v) || v.headers === void 0) return {
+		status,
+		body
+	};
+	const headers = v.headers;
+	if (typeof headers !== "object" || headers === null) return null;
+	const copy = {};
+	for (const [name, value] of Object.entries(headers)) {
+		if (typeof value !== "string") return null;
+		copy[name] = value;
+	}
+	return {
+		status,
+		headers: copy,
+		body
+	};
+}
+/**
 * Store d'idempotence **Redis** (node-redis v6) — implémentation distribuée
 * d'{@link IIdempotencyStore} pour le cluster (dédup des mutations rejouées
 * PARTAGÉE cross-pod, là où l'impl mémoire par défaut reste affine à un pod).
@@ -183,8 +227,7 @@ var RedisIdempotencyStore = class {
 	#parse(raw) {
 		if (raw === null) return null;
 		try {
-			const v = JSON.parse(raw);
-			return v && (v.s === "if" || v.s === "d") ? v : null;
+			return toEntry(JSON.parse(raw));
 		} catch {
 			return null;
 		}
@@ -250,5 +293,4 @@ var RedisIdempotencyStore = class {
 		if (this.#pending > 0) this.#pending--;
 	}
 };
-//#endregion
 export { RedisIdempotencyStore };

package/dist/nodefony/src/Resolver.js

@@ -1,10 +1,11 @@
 import { guardSingletonState, isDevelopment } from "./singletonGuard.js";
-import { buildParamArgs, computeActionMeta, resolveActionMeta, resolveSessionIntent } from "../decorators/routerDecorators.js";
+import { validateRouteInput } from "./routeSchema.js";
+import { buildParamArgs, computeActionMeta, readInvocationBody, readRouteInput, resolveActionMeta, resolveSessionIntent } from "../decorators/routerDecorators.js";
 import { computeFingerprint, evaluateIdempotency, isMutationMethod, resolveIdempotencyKey, resolveIdentity } from "./idempotency.js";
 import { authenticationShortfall, stepUpChallenge } from "./requireAuthentication.js";
 import { RequestContext, finallyMaybe, identityHint, isArray, isPlainObject, isPromise, nodefonyError, thenMaybe, typeOf } from "nodefony";
 import { Http2Response, HttpResponse, WebsocketResponse } from "@nodefony/http";
-//#region nodefony/src/Resolver.ts
+// nodefony/src/Resolver.ts
 /**
 * Résout une route vers son couple controller/action et exécute l'action —
 * UN Resolver est alloué par requête HTTP (et par connexion WS, réutilisé
@@ -47,7 +48,7 @@ var Resolver = class {
 	/**
 	* Query d'une invocation **par message** (pont WS-RPC `api.request`) — pendant
 	* de `cleanPathOverride` pour le `?…` du path invoqué. Le contexte WS étant
-	* PARTAGÉ par la connexion (sa `queryGet` = celle du handshake), la query
+	* PARTAGÉ par la connexion (sa `query` = celle du handshake), la query
 	* per-invocation vit ici (le Resolver est per-invocation → zéro bleed entre
 	* requêtes concurrentes d'une même socket). `null` (hot path HTTP) = ignoré.
 	* Consommé par `@Query` (`_buildParamArgs`) et copié sur le controller
@@ -75,6 +76,11 @@ var Resolver = class {
 	* administrateurs.
 	*/
 	messageInvocation = false;
+	/**
+	* Les gardes de l'action ont été jugées favorables par {@link authorizeAction}
+	* et ne se rejugent pas à la prochaine exécution — consommé par elle.
+	*/
+	preAuthorized = false;
 	constructor(context) {
 		this.context = context;
 		this.injector = context.container?.get("injector") ?? null;
@@ -84,7 +90,7 @@ var Resolver = class {
 		if (match) {
 			this.variables = match;
 			this.route = route;
-			this.controller = route.controller;
+			this.controller = route.controller ?? null;
 			this.actionName = route.classMethod;
 			this.resolve = true;
 			this.bypassFirewall = this.route.bypassFirewall;
@@ -231,7 +237,7 @@ var Resolver = class {
 	* @returns le controller reçu, pour enchaîner.
 	*/
 	_guardSingleton(controller, ctx) {
-		if (this.controller.scope === "singleton" && isDevelopment(ctx.kernel?.environment)) guardSingletonState(controller, controller.constructor.name);
+		if (this.controller?.scope === "singleton" && isDevelopment(ctx.kernel?.environment)) guardSingletonState(controller, controller.constructor.name);
 		return controller;
 	}
 	/**
@@ -256,9 +262,46 @@ var Resolver = class {
 	*/
 	executeAction(data, reload = false, metaArg) {
 		const meta = metaArg ?? (this.route ? resolveActionMeta(this.route) : computeActionMeta(this.controller, this.actionName));
+		let guarded;
+		if (this.preAuthorized) this.preAuthorized = false;
+		else guarded = this._enforceActionSecurity(meta);
+		const schema = meta.schema;
+		if (schema !== null) {
+			if (guarded !== void 0) return guarded.then(() => this._validateAndInvoke(schema, meta, data, reload));
+			return this._validateAndInvoke(schema, meta, data, reload);
+		}
+		if (guarded !== void 0) return guarded.then(() => this._acquireAndInvoke(meta, data, reload, null));
+		return this._acquireAndInvoke(meta, data, reload, null);
+	}
+	/**
+	* Valide l'entrée d'une action à schéma, puis l'exécute avec cette entrée
+	* pour argument unique. Synchrone tant que le validateur l'est.
+	*
+	* @throws SchemaValidationError (422) quand l'entrée viole le schéma.
+	*/
+	_validateAndInvoke(schema, meta, data, reload) {
+		const validated = validateRouteInput(schema, readRouteInput(this._zipRouteParams(), this.context.request, this.queryOverride ?? void 0, meta.bodyStream));
+		if (validated instanceof Promise) return validated.then((input) => this._acquireAndInvoke(meta, data, reload, input));
+		return this._acquireAndInvoke(meta, data, reload, validated);
+	}
+	/**
+	* Juge les gardes de l'action résolue SANS l'exécuter — appelé par le
+	* pipeline WebSocket AVANT d'accepter le handshake (#596), pour qu'un
+	* connecté sans le rôle reçoive son 403 en statut HTTP au lieu d'une
+	* ouverture suivie d'une fermeture. Un verdict favorable vaut pour la
+	* PROCHAINE exécution (l'action de handshake), qui ne le rejuge pas ; les
+	* messages suivants, eux, sont jugés chacun.
+	*
+	* @returns `undefined` quand l'action n'est pas gardée ; sinon la promesse du
+	*   verdict, rompue par un refus
+	*/
+	authorizeAction() {
+		const meta = this.route ? resolveActionMeta(this.route) : computeActionMeta(this.controller, this.actionName);
 		const guarded = this._enforceActionSecurity(meta);
-		if (guarded !== void 0) return guarded.then(() => this._acquireAndInvoke(meta, data, reload));
-		return this._acquireAndInvoke(meta, data, reload);
+		if (guarded === void 0) return void 0;
+		return guarded.then(() => {
+			this.preAuthorized = true;
+		});
 	}
 	/**
 	* Les gardes d'autorisation d'une action : `@IsGranted`/`@RequireScope`, puis
@@ -296,10 +339,10 @@ var Resolver = class {
 	* c'est la bonne classe, sinon une création —, puis l'action elle-même.
 	* N'attend que la création, et seulement quand elle attend.
 	*/
-	_acquireAndInvoke(meta, data, reload) {
+	_acquireAndInvoke(meta, data, reload, input) {
 		const pinned = this.context.container?.get("controller");
-		if (!pinned || reload || this.controller && !(pinned instanceof this.controller)) return thenMaybe(this.newController(), (controller) => this._invokeAction(controller, meta, data));
-		return this._invokeAction(pinned, meta, data);
+		if (!pinned || reload || this.controller && !(pinned instanceof this.controller)) return thenMaybe(this.newController(), (controller) => this._invokeAction(controller, meta, data, input));
+		return this._invokeAction(pinned, meta, data, input);
 	}
 	/**
 	* Appelle l'action sur l'instance : état de requête (portée `request`
@@ -308,17 +351,15 @@ var Resolver = class {
 	*
 	* @throws de façon SYNCHRONE ce que lève l'action, ou l'absence d'action.
 	*/
-	_invokeAction(controller, meta, data) {
+	_invokeAction(controller, meta, data, input) {
 		if (this.controller?.scope !== "singleton") {
 			controller.setRoute(this.route);
-			if (this.queryOverride !== null) {
-				controller.queryGet = this.queryOverride;
-				controller.query = this.queryOverride;
-			}
+			if (this.queryOverride !== null) controller.query = this.queryOverride;
 		}
 		const methodKey = this.actionName;
 		let args;
-		if (meta.paramsMeta) args = this._buildParamArgs(meta.paramsMeta);
+		if (input !== null) args = [input];
+		else if (meta.paramsMeta) args = this._buildParamArgs(meta.paramsMeta);
 		else if (data) args = [...this.variables, ...data];
 		else args = [...this.variables];
 		this._applyResponseMeta(meta);
@@ -393,7 +434,7 @@ var Resolver = class {
 		const als = RequestContext.get();
 		const httpReq = context.request;
 		const params = this._zipRouteParams();
-		const body = als?.body !== void 0 ? als.body : httpReq?.queryPost ?? null;
+		const body = readInvocationBody(httpReq) ?? null;
 		const store = context.container?.get("idempotencyStore");
 		const verdict = await evaluateIdempotency({
 			store,
@@ -404,7 +445,7 @@ var Resolver = class {
 				params,
 				body
 			]),
-			isWs: Boolean(context.type?.startsWith("websocket")),
+			isWs: context.type === "websocket",
 			required: meta.idempotent?.required ?? true
 		});
 		if (verdict.kind === "reject") throw new nodefonyError(verdict.message, verdict.status);
@@ -538,16 +579,14 @@ var Resolver = class {
 		return idx === -1 ? void 0 : this.variables[idx];
 	}
 	_buildParamArgs(metas) {
-		const httpCtx = this.context;
-		const paramsMap = this._zipRouteParams();
-		const ctx = this.context;
+		const context = this.context;
 		return buildParamArgs(metas, {
-			paramsMap,
-			request: httpCtx.request,
-			response: httpCtx.response,
-			session: ctx.session,
+			paramsMap: this._zipRouteParams(),
+			request: context.request,
+			response: context.response,
+			session: context.session,
 			queryOverride: this.queryOverride ?? void 0,
-			getRequestCookies: (name) => ctx.getRequestCookies(name)
+			getRequestCookies: (name) => context.getRequestCookies(name)
 		});
 	}
 	/**
@@ -630,20 +669,17 @@ var Resolver = class {
 				}
 				switch (this.context.type) {
 					case "http":
-					case "http2":
-					case "http3":
-					case "https": this.context.waitAsync = true;
+						this.context.waitAsync = true;
+						this.unrendered = `une instance de ${(typeof result === "object" && result !== null ? result.constructor.name : void 0) ?? "classe"}`;
 				}
 				return;
 			default: switch (this.context.type) {
 				case "http":
-				case "http2":
-				case "http3":
-				case "https":
 					if (this.context.sended) return;
 					if (this.context.isRedirect) return this.context.send();
 					if (NO_BODY_STATUS.has(this.getResponseStatus())) return this.context.send();
 					this.context.waitAsync = true;
+					this.unrendered = result === null ? "null" : typeof result;
 			}
 		}
 	}
@@ -683,5 +719,4 @@ const NO_BODY_STATUS = /* @__PURE__ */ new Set([
 	205,
 	304
 ]);
-//#endregion
 export { Resolver as default };

package/dist/nodefony/src/ResourceController.js

@@ -1,9 +1,9 @@
 import Controller from "./Controller.js";
 import { assertPageQuery } from "nodefony";
 import { HttpError } from "@nodefony/http";
-//#region nodefony/src/ResourceController.ts
+// nodefony/src/ResourceController.ts
 /**
-* Controller de ressource **souverain** (V4.2 — POC API souveraine, Phase 2) :
+* Controller de ressource **duplex** (V4.2 — une action, deux transports) :
 * la logique métier est écrite UNE fois dans le service de ressource, les
 * actions de la sous-classe ne sont que des portes (REST, WS-RPC `invoke`,
 * GraphQL à venir) qui retournent la **valeur brute** — `returnController`
@@ -22,7 +22,7 @@ import { HttpError } from "@nodefony/http";
 *   sur `this` doit rétrograder : `static scope = "request"`.
 *
 * Sécurité : aucun critère de requête n'est passé AUTOMATIQUEMENT au service
-* (pas de `find(this.queryGet)` implicite) — exposer un filtrage est une
+* (pas de `find(this.query)` implicite) — exposer un filtrage est une
 * décision EXPLICITE de la sous-classe (deny-by-default ; le scope de
 * sécurité des données se branche au niveau service/criteria, P6).
 *
@@ -38,8 +38,12 @@ import { HttpError } from "@nodefony/http";
 *     return this.listResource();
 *   }
 *   \@route("books-get", { path: "/{id}", requirements: { methods: ["GET", "WEBSOCKET"] } })
-*   detail(\@Param("id") id: string) {
-*     return this.getResource(id);
+*   async detail(\@Param("id") id: string) {
+*     // `null` rendu tel quel = « l'action répond elle-même » : la requête
+*     // pendrait jusqu'au délai d'expiration. La porte décide du 404.
+*     const found = await this.getResource(id);
+*     if (!found) throw new HttpError(`Book ${id} not found`, 404);
+*     return found;
 *   }
 * }
 * ```
@@ -117,6 +121,10 @@ var ResourceController = class extends Controller {
 	/**
 	* Lit une entité par id — `null` si absente (la porte décide du 404).
 	*
+	* ⚠️ Ne pas rendre ce `null` tel quel depuis une action : pour le Resolver,
+	* `null` veut dire « l'action répond elle-même », et la requête attend
+	* alors son délai d'expiration. Lever un `HttpError` 404.
+	*
 	* `options.relations` charge les associations dans la foulée. La porte doit
 	* n'y laisser passer que des relations qu'elle a DÉCLARÉES : un `include`
 	* libre laisse le client nommer n'importe quelle association, donc lire des
@@ -144,5 +152,4 @@ var ResourceController = class extends Controller {
 		return Promise.resolve(resource.delete(criteria));
 	}
 };
-//#endregion
 export { ResourceController as default };

package/dist/nodefony/src/Route.js

@@ -1,7 +1,7 @@
 import { escapeRegExp, stripTrailingSlashes, typeOf } from "nodefony";
 import { HttpError, compileDomainPatterns, isDomainAllowed } from "@nodefony/http";
 import { createHash } from "node:crypto";
-//#region nodefony/src/Route.ts
+// nodefony/src/Route.ts
 /**
 * Motif d'un segment variable : `{id}`, `/{slug}?`, `.{format}`, `{id}(\d+)`.
 *
@@ -266,7 +266,7 @@ var Route = class Route {
 				const k = this.variables[i] || "wildcard";
 				param &&= decode(param);
 				const req = this.getRequirement(k);
-				let result = null;
+				let result;
 				if (req) {
 					let compiled = this.varRegexp?.[k];
 					if (!compiled) {
@@ -549,5 +549,4 @@ var Route = class Route {
 		return true;
 	}
 };
-//#endregion
 export { Route as default };

package/dist/nodefony/src/SecurityApiController.js

@@ -1,5 +1,5 @@
 import Controller from "./Controller.js";
-//#region nodefony/src/SecurityApiController.ts
+// nodefony/src/SecurityApiController.ts
 const NO_STORE = { "cache-control": "no-store" };
 /**
 * Base des contrôleurs d'authentification (`/nodefony/security/api/*`) : toute
@@ -20,5 +20,4 @@ var SecurityApiController = class extends Controller {
 		});
 	}
 };
-//#endregion
 export { SecurityApiController as default };

package/dist/nodefony/src/SyslogAdminApi.js

@@ -2,7 +2,7 @@ import { SYSLOG_FILTERS, SYSLOG_SORTABLE } from "./syslogFilters.js";
 import path from "node:path";
 import { Syslog, getActiveLogDriver, getLogDriver, listLogDrivers, parseFilters, parsePageQuery, redactSecrets, setActiveLogDriver } from "nodefony";
 import fsp from "node:fs/promises";
-//#region nodefony/src/SyslogAdminApi.ts
+// nodefony/src/SyslogAdminApi.ts
 /** Plafond d'octets lus en queue de fichier (tail / fenêtre incrémentale). */
 const MAX_TAIL_BYTES = 262144;
 /**
@@ -462,5 +462,4 @@ function createSyslogAdminApi(syslog, options = {}) {
 		adminEndpoints: () => endpoints
 	};
 }
-//#endregion
 export { createSyslogAdminApi };

package/dist/nodefony/src/Template.js

@@ -1,5 +1,5 @@
 import { Service } from "nodefony";
-//#region nodefony/src/Template.ts
+// nodefony/src/Template.ts
 var Template = class extends Service {
 	engine;
 	module;
@@ -11,5 +11,4 @@ var Template = class extends Service {
 		this.cache = module.kernel?.environment === "prod" || module.kernel?.environment === "production";
 	}
 };
-//#endregion
 export { Template as default };

package/dist/nodefony/src/configMutation.js

@@ -1,4 +1,4 @@
-//#region nodefony/src/configMutation.ts
+// nodefony/src/configMutation.ts
 /** Narrowing défensif : `unknown` → nœud JSON Schema (ou `null` si non-objet). */
 function asNode(value) {
 	if (value !== null && typeof value === "object" && !Array.isArray(value)) return value;
@@ -182,5 +182,4 @@ function getResolvedPath(obj, segments) {
 	}
 	return cur;
 }
-//#endregion
 export { getResolvedPath, navigateSchemaNode, nodeFlags, notEditableReason, recipeFor, validateLeafValue };

package/dist/nodefony/src/docsReader.js

@@ -5,7 +5,7 @@ import { promisify } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { execFile, spawn } from "node:child_process";
-//#region nodefony/src/docsReader.ts
+// nodefony/src/docsReader.ts
 const execFileAsync = promisify(execFile);
 /**
 * Racine de l'APPLICATION servie — jamais le dossier courant du process.
@@ -952,5 +952,4 @@ async function readCoreInfo() {
 		dependencies
 	};
 }
-//#endregion
 export { CORE_PACKAGE, checkOutdated, countModuleDocs, listModuleDocs, listModuleSymbols, listTestFiles, listTestGroups, parseFrontmatter, readCoreInfo, readCoverage, readDependencies, readModuleDoc, readSymbolDeclaration, resolveCorePath, runModuleTests, searchModuleDocs, testRunCommand };

package/dist/nodefony/src/idempotency.js

@@ -1,6 +1,6 @@
 import { RequestContext } from "nodefony";
 import { createHash } from "node:crypto";
-//#region nodefony/src/idempotency.ts
+// nodefony/src/idempotency.ts
 /**
 * Logique **pure et partagée** de la porte d'idempotence des mutations, conforme à
 * `draft-ietf-httpapi-idempotency-key-header-06`. Source unique de la sémantique
@@ -126,5 +126,4 @@ async function evaluateIdempotency(opts) {
 		};
 	}
 }
-//#endregion
 export { IDEMPOTENCY_KEY_MAX, computeFingerprint, evaluateIdempotency, isMutationMethod, resolveIdempotencyKey, resolveIdentity };