@betterportal/framework 10.1.56 → 10.1.58

package/lib/adapters/h3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"h3.d.ts","sourceRoot":"","sources":["../../src/adapters/h3.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,KAAK,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxG,OAAO,KAAK,EAAsB,oBAAoB,EAAE,eAAe,EAAwD,MAAM,0BAA0B,CAAC;AAChK,OAAO,KAAK,EAGV,WAAW,EAIX,mBAAmB,EACnB,oBAAoB,EAIrB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,sBAAsB,CAAC;AAErE,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AA0B1B,MAAM,WAAW,4BAA4B;IAC3C,0BAA0B,CAAC,EAAE,CAC3B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,uBAAuB,KAChC,yBAAyB,CAAC;IAC/B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yGAAyG;IACzG,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,GAAG,aAAa,GAAG,SAAS,CAAC;IACnI;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,sBAAsB,EAAE,mBAAmB,CAAC,GAAG,OAAO,sBAAsB,EAAE,mBAAmB,CAAC;IAC1K,qEAAqE;IACrE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC7I;AAQD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,oBAAoB,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AA8HD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAKvE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExG;AA2CD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,oBAAoB,EAC9B,GAAG,EAAE,iBAAiB,EACtB,OAAO,GAAE,4BAAiC,GACzC,IAAI,CAqGN;AA+4CD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,QAAQ,GAAG,SAAS,CAAC;CAChC,GACL,IAAI,CAyCN"}
+{"version":3,"file":"h3.d.ts","sourceRoot":"","sources":["../../src/adapters/h3.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,KAAK,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AACxG,OAAO,KAAK,EAAsB,oBAAoB,EAAE,eAAe,EAAwD,MAAM,0BAA0B,CAAC;AAChK,OAAO,KAAK,EAGV,WAAW,EAIX,mBAAmB,EACnB,oBAAoB,EAIrB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,sBAAsB,CAAC;AAErE,OAAO,EASL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AA0B1B,MAAM,WAAW,4BAA4B;IAC3C,0BAA0B,CAAC,EAAE,CAC3B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,uBAAuB,KAChC,yBAAyB,CAAC;IAC/B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yGAAyG;IACzG,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,GAAG,aAAa,GAAG,SAAS,CAAC;IACnI;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,sBAAsB,EAAE,mBAAmB,CAAC,GAAG,OAAO,sBAAsB,EAAE,mBAAmB,CAAC;IAC1K,qEAAqE;IACrE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC7I;AAQD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,oBAAoB,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AA+KD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAKvE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExG;AA2CD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,oBAAoB,EAC9B,GAAG,EAAE,iBAAiB,EACtB,OAAO,GAAE,4BAAiC,GACzC,IAAI,CAqGN;AAyhDD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE;IACP,MAAM,CAAC,EAAE,MAAM,QAAQ,GAAG,SAAS,CAAC;CAChC,GACL,IAAI,CAuDN"}

package/lib/adapters/h3.js

@@ -1,7 +1,7 @@
 import { createEventStream, getRequestIP, getRequestURL } from "h3";
 import { isStreamHandler } from "../contracts/streaming.js";
 import { driveStream, driveStreamBuffered, ndjsonStreamResponse } from "../runtime/stream.js";
-import { acceptHeaderFromEvent, eventObservability, htmlResponse, jsonResponse } from "../runtime/h3.js";
+import { acceptHeaderFromEvent, annotateCoreHttpOutcome, annotateHttpOutcome, ensureCoreHttpOutcome, eventObservability, htmlResponse, jsonResponse, withCoreHttpOutcome } from "../runtime/h3.js";
 import { buildHostCandidates, hostFromHeaderValue, toHtmlString } from "../runtime/http.js";
 import { parseAcceptHeader, resolveRequestedRepresentation } from "../runtime/media.js";
 import { resolveRenderer } from "../runtime/registry.js";
@@ -44,7 +44,7 @@ function headersFromEvent(event) {
 function parseRouteParams(rawParams, schema) {
     for (const [name, value] of Object.entries(rawParams)) {
         if (!value || value.length > 100) {
-            return jsonResponse({ error: `Invalid path parameter: ${name}` }, 400);
+            return coreJsonResponse({ error: `Invalid path parameter: ${name}` }, 400, "request.params.invalid", `Invalid path parameter: ${name}`, { "bp.request.parameter": name });
         }
     }
     if (!schema)
@@ -53,10 +53,11 @@ function parseRouteParams(rawParams, schema) {
         return schema.parse(rawParams);
     }
     catch (error) {
-        return jsonResponse({
+        const reason = error instanceof Error ? error.message : String(error);
+        return coreJsonResponse({
             error: "Invalid path parameters",
-            detail: error instanceof Error ? error.message : String(error)
-        }, 400);
+            detail: reason
+        }, 400, "request.params.invalid", reason);
     }
 }
 function escapeContentDispositionValue(value) {
@@ -65,6 +66,23 @@ function escapeContentDispositionValue(value) {
 function responseHelper(body = null, init = {}) {
     return new Response(body, init);
 }
+function coreResponse(response, code, reason, attributes) {
+    return withCoreHttpOutcome(response, { code, reason, attributes });
+}
+function coreJsonResponse(body, status, code, reason, attributes, headers) {
+    return coreResponse(jsonResponse(body, status, headers), code, reason, attributes);
+}
+function parseRequestValue(schema, value, code, target) {
+    try {
+        return { value: schema.parse(value) };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            response: coreJsonResponse({ error: `Invalid ${target}`, detail: reason }, 400, code, reason, { "bp.request.validation_target": target })
+        };
+    }
+}
 function fileResponseHelper(body, options = {}) {
     const headers = new Headers(options.headers);
     if (options.contentType && !headers.has("content-type"))
@@ -636,7 +654,11 @@ function rejectUnallowedAppRoute(obs, route, method, extraContext, reason) {
         "bp.tenant.id": extraContext.tenant.id,
         "bp.route_allowlist.reason": reason
     });
-    return jsonResponse({ error: "Route not found" }, 404);
+    return coreJsonResponse({ error: "Route not found" }, 404, "route.not_mounted", reason, {
+        "bp.route.view_id": route.viewId,
+        "bp.route.path": route.path,
+        "bp.route_allowlist.reason": reason
+    });
 }
 async function withRequestObservability(event, route, method, options, handler, extraAttributes = {}) {
     const startedAt = performance.now();
@@ -698,7 +720,7 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
         params: methodRoute?.schemas.params ?? route.schemas.params
     };
     if (!handler) {
-        return jsonResponse({ error: `No handler for ${method} ${route.path}` }, 405);
+        return coreJsonResponse({ error: `No handler for ${method} ${route.path}` }, 405, "route.handler_missing", `No handler for ${method} ${route.path}`);
     }
     // -- Parse inputs -------------------------------------------------
     const url = getRequestURL(event);
@@ -718,7 +740,7 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
             }
             catch (err) {
                 if (err instanceof MultipartTooLargeError) {
-                    return jsonResponse({ error: "Multipart payload too large" }, 413);
+                    return coreJsonResponse({ error: "Multipart payload too large" }, 413, "request.multipart.too_large", err.message);
                 }
                 rawBody = {};
             }
@@ -734,14 +756,30 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
     // RequestSchema is only enforced for methods that carry a body. GET/DELETE/OPTIONS
     // pass rawBody (empty {}) through unparsed so routes with both GET + POST handlers
     // don't fail GET because POST's RequestSchema has required fields.
-    const query = schemas.query ? schemas.query.parse(rawQuery) : rawQuery;
-    const headers = schemas.headers ? schemas.headers.parse(rawHeaders) : rawHeaders;
-    const request = (schemas.request && METHOD_WRITE_BODY.has(method))
-        ? schemas.request.parse(rawBody)
-        : rawBody;
-    const multipart = schemas.multipart
-        ? schemas.multipart.parse(rawMultipart ?? { fields: {}, files: {} })
-        : undefined;
+    const queryResult = schemas.query
+        ? parseRequestValue(schemas.query, rawQuery, "request.query.invalid", "query parameters")
+        : { value: rawQuery };
+    if ("response" in queryResult)
+        return queryResult.response;
+    const query = queryResult.value;
+    const headersResult = schemas.headers
+        ? parseRequestValue(schemas.headers, rawHeaders, "request.headers.invalid", "request headers")
+        : { value: rawHeaders };
+    if ("response" in headersResult)
+        return headersResult.response;
+    const headers = headersResult.value;
+    const requestResult = schemas.request && METHOD_WRITE_BODY.has(method)
+        ? parseRequestValue(schemas.request, rawBody, "request.body.invalid", "request body")
+        : { value: rawBody };
+    if ("response" in requestResult)
+        return requestResult.response;
+    const request = requestResult.value;
+    const multipartResult = schemas.multipart
+        ? parseRequestValue(schemas.multipart, rawMultipart ?? { fields: {}, files: {} }, "request.multipart.invalid", "multipart request")
+        : { value: undefined };
+    if ("response" in multipartResult)
+        return multipartResult.response;
+    const multipart = multipartResult.value;
     // Path params - H3 populates event.context.params for `:paramName` routes
     const rawParams = event.context?.params ?? {};
     const params = parseRouteParams(rawParams, schemas.params);
@@ -749,7 +787,7 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
         return params;
     const extraContext = await resolveRequiredHandlerContext(event, routerOptions, route);
     if (!extraContext) {
-        return jsonResponse({ error: "BetterPortal tenant/app context required" }, 400);
+        return coreJsonResponse({ error: "BetterPortal tenant/app context required" }, 400, "route.context_unresolved", "BetterPortal tenant/app context required");
     }
     const routeAllowlistAcceptHeader = acceptHeaderFromEvent(event);
     const routeAllowance = appAllowsRoute(extraContext.app, route, method, url, routeAllowlistAcceptHeader);
@@ -776,7 +814,7 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
     const authResolved = await loadAuthContext(event, route, routerOptions, obs);
     const authResult = await resolveRequestAuth(apiAuth, event, authResolved, route, method, obs);
     if (authResult.error) {
-        return renderAuthError(route, event, authResult.status, authResult.error, authResult.requiredPermissions, earlyRenderContext(authResult.status));
+        return renderAuthError(route, event, authResult.status, authResult.code ?? "auth.unclassified", authResult.error, authResult.requiredPermissions, earlyRenderContext(authResult.status));
     }
     // -- Tenant/app activation check (validateTenantApp hook -> 426) -----
     const tenantApp = readTenantAppFromEvent(event);
@@ -819,6 +857,7 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
         bpHeaders,
         responseHeaders: event.res.headers,
         setStatus: (status) => { event.res.status = status; },
+        diagnostic: (diagnostic) => annotateHttpOutcome(event, diagnostic),
         serviceId: routerOptions.serviceId,
         routeUrl,
         uiRouteUrl,
@@ -836,19 +875,19 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
             applyBpHeadersToEvent(event, bpHeaders);
             return streamed;
         }
-        rawData = await withSpan(obs, "bp.route.handler", {
+        rawData = await withCoreFailure(event, "handler.exception", () => withSpan(obs, "bp.route.handler", {
             "bp.route.view_id": route.viewId,
             "bp.route.path": route.path,
             "http.request.method": method,
             "bp.route.stream_buffered": true
-        }, () => driveStreamBuffered(handler, ctx));
+        }, () => driveStreamBuffered(handler, ctx)));
     }
     else {
-        rawData = await withSpan(obs, "bp.route.handler", {
+        rawData = await withCoreFailure(event, "handler.exception", () => withSpan(obs, "bp.route.handler", {
             "bp.route.view_id": route.viewId,
             "bp.route.path": route.path,
             "http.request.method": method
-        }, () => handler(ctx));
+        }, () => handler(ctx)));
     }
     // -- Emit BP-managed headers -------------------------------------
     applyBpHeadersToEvent(event, bpHeaders);
@@ -857,6 +896,12 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
     }
     // -- Status decision ---------------------------------------------
     const handlerStatus = event.res.status && event.res.status !== 0 ? event.res.status : 200;
+    if (handlerStatus < 200 || handlerStatus >= 400) {
+        ensureCoreHttpOutcome(event, {
+            code: "response.status_unclassified",
+            reason: `Handler returned HTTP ${handlerStatus} without an explicit diagnostic`
+        });
+    }
     // -- Content negotiation ------------------------------------------
     const acceptHeader = acceptHeaderFromEvent(event);
     const representation = resolveRequestedRepresentation(acceptHeader);
@@ -881,9 +926,17 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
     // -- Validate response against schema (all representations) ------
     // Skipped when status indicates no body is expected.
     if (!schemas.response) {
-        return jsonResponse({ error: `Route "${route.viewId}" has no ResponseSchema and did not return a raw Response` }, 500);
+        const reason = `Route "${route.viewId}" has no ResponseSchema and did not return a raw Response`;
+        return coreJsonResponse({ error: reason }, 500, "response.schema_missing", reason);
+    }
+    let data;
+    try {
+        data = schemas.response.parse(rawData);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return coreJsonResponse({ error: "Response schema validation failed", detail: reason }, 500, "response.schema_invalid", reason);
     }
-    const data = schemas.response.parse(rawData);
     // NDJSON only exists for streaming views; those were handled before
     // negotiation, so reaching here means the view does not stream.
     if (representation.kind === "ndjson") {
@@ -891,7 +944,7 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
             "http.request.accept": acceptHeader ?? "",
             "bp.representation.kind": representation.kind
         });
-        return jsonResponse({ error: "NDJSON streaming is not supported by this view" }, 406);
+        return coreJsonResponse({ error: "NDJSON streaming is not supported by this view" }, 406, "representation.ndjson_not_supported", "NDJSON streaming is not supported by this view");
     }
     // JSON - already validated above, no redundant parse
     if (representation.kind === "json") {
@@ -903,7 +956,7 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
             "http.request.accept": acceptHeader ?? "",
             "bp.representation.kind": representation.kind
         });
-        return jsonResponse({ error: "Renderer could not be resolved from the app shell" }, 406);
+        return coreJsonResponse({ error: "Renderer could not be resolved from the app shell" }, 406, "representation.renderer_unresolved", "Renderer could not be resolved from the app shell");
     }
     // Determine the renderer kind requested
     const fragmentKey = url.searchParams.get("_f") ?? fragmentFromAcceptHeader(acceptHeader);
@@ -915,17 +968,27 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
     if (handlerStatus !== 200) {
         const statusRenderer = resolveStatusRenderer(route, renderer, handlerStatus, requestedKind, requestedKey, method);
         if (statusRenderer) {
-            const html = await withSpan(obs, "bp.view.render", {
+            if (handlerStatus < 200 || handlerStatus >= 400) {
+                ensureCoreHttpOutcome(event, {
+                    code: "response.status_unclassified",
+                    reason: `Handler returned HTTP ${handlerStatus} without an explicit diagnostic`
+                });
+            }
+            const html = await withCoreFailure(event, "render.status_failed", () => withSpan(obs, "bp.view.render", {
                 "bp.route.view_id": route.viewId,
                 "bp.view.renderer": renderer,
                 "bp.view.kind": requestedKind,
                 "bp.view.status": handlerStatus
-            }, () => statusRenderer.render(data, renderContext));
+            }, () => statusRenderer.render(data, renderContext)));
             return htmlResponse(rewriteServiceRouteTokens(toHtmlString(html), ctx.routeUrl, obs), handlerStatus, htmlContentType("status", route.chrome));
         }
         // No specific renderer found.
         if (!shouldFallThroughToDefaultRenderer(handlerStatus)) {
             // 4xx/5xx without a specific renderer -> empty body with status.
+            ensureCoreHttpOutcome(event, {
+                code: "response.status_unclassified",
+                reason: `Handler returned HTTP ${handlerStatus} without an explicit diagnostic`
+            });
             return new Response(null, { status: handlerStatus });
         }
         // 2xx without specific -> fall through to default renderer, but keep handlerStatus.
@@ -940,16 +1003,16 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
                 "bp.view.kind": "fragment",
                 "bp.view.key": fragmentKey
             });
-            return jsonResponse({
+            return coreJsonResponse({
                 error: `No fragment renderer found for fragment="${fragmentKey}" in renderer "${renderer}"`
-            }, 406);
+            }, 406, "representation.fragment_not_found", `Fragment renderer "${fragmentKey}" was not found`);
         }
-        const html = await withSpan(obs, "bp.view.render", {
+        const html = await withCoreFailure(event, "render.fragment_failed", () => withSpan(obs, "bp.view.render", {
             "bp.route.view_id": route.viewId,
             "bp.view.renderer": renderer,
             "bp.view.kind": "fragment",
             "bp.view.key": fragmentKey
-        }, () => resolved.renderer.render(data, renderContext));
+        }, () => resolved.renderer.render(data, renderContext)));
         return htmlResponse(rewriteServiceRouteTokens(toHtmlString(html), ctx.routeUrl, obs), handlerStatus, htmlContentType("fragment", route.chrome));
     }
     // Component request via `_c` query param
@@ -962,16 +1025,16 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
                 "bp.view.kind": "component",
                 "bp.view.key": componentId
             });
-            return jsonResponse({
+            return coreJsonResponse({
                 error: `No component renderer found for _c="${componentId}" in renderer "${renderer}"`
-            }, 406);
+            }, 406, "representation.component_not_found", `Component renderer "${componentId}" was not found`);
         }
-        const html = await withSpan(obs, "bp.view.render", {
+        const html = await withCoreFailure(event, "render.component_failed", () => withSpan(obs, "bp.view.render", {
             "bp.route.view_id": route.viewId,
             "bp.view.renderer": renderer,
             "bp.view.kind": "component",
             "bp.view.key": componentId
-        }, () => resolved.renderer.render(data, renderContext));
+        }, () => resolved.renderer.render(data, renderContext)));
         return htmlResponse(rewriteServiceRouteTokens(toHtmlString(html), ctx.routeUrl, obs), handlerStatus, htmlContentType("fragment", route.chrome));
     }
     // Page request - only page renderers allowed
@@ -982,15 +1045,15 @@ async function handleRouteRequest(registryRoutes, dependencyAliases, route, meth
             "bp.view.renderer": renderer,
             "bp.view.kind": "page"
         });
-        return jsonResponse({
+        return coreJsonResponse({
             error: `No page renderer found for renderer "${renderer}"`
-        }, 406);
+        }, 406, "representation.page_not_found", `Page renderer "${renderer}" was not found`);
     }
-    const html = await withSpan(obs, "bp.view.render", {
+    const html = await withCoreFailure(event, "render.page_failed", () => withSpan(obs, "bp.view.render", {
         "bp.route.view_id": route.viewId,
         "bp.view.renderer": renderer,
         "bp.view.kind": "page"
-    }, () => resolved.renderer.render(data, renderContext));
+    }, () => resolved.renderer.render(data, renderContext)));
     const mode = representation.mode ?? "page";
     return htmlResponse(rewriteServiceRouteTokens(toHtmlString(html), ctx.routeUrl, obs), handlerStatus, htmlContentType(mode, route.chrome));
 }
@@ -1025,11 +1088,11 @@ async function handleStreamRepresentation(route, handler, ctx, event, url, metho
         params: ctx.params,
         query: ctx.query
     };
-    const html = await withSpan(obs, "bp.view.render", {
+    const html = await withCoreFailure(event, "render.stream_shell_failed", () => withSpan(obs, "bp.view.render", {
         "bp.route.view_id": route.viewId,
         "bp.view.renderer": renderer,
         "bp.view.kind": "stream-shell"
-    }, () => streamSet.renderShell(shellCtx));
+    }, () => streamSet.renderShell(shellCtx)));
     return htmlResponse(rewriteServiceRouteTokens(toHtmlString(html), ctx.routeUrl, obs), 200, htmlContentType("fragment", route.chrome));
 }
 /**
@@ -1057,11 +1120,11 @@ async function handleStreamSse(registryRoutes, dependencyAliases, route, handler
     const authResolved = await loadAuthContext(event, route, routerOptions, obs);
     const authResult = await resolveRequestAuth(route.auth, event, authResolved, route, "GET", obs);
     if (authResult.error) {
-        return jsonResponse({ error: authResult.error, status: authResult.status }, authResult.status);
+        return coreJsonResponse({ error: authResult.error, status: authResult.status }, authResult.status, authResult.code ?? "auth.unclassified", authResult.error);
     }
     const extraContext = await resolveRequiredHandlerContext(event, routerOptions, route);
     if (!extraContext) {
-        return jsonResponse({ error: "BetterPortal tenant/app context required" }, 400);
+        return coreJsonResponse({ error: "BetterPortal tenant/app context required" }, 400, "stream.context_unresolved", "BetterPortal tenant/app context required");
     }
     const ctx = {
         params,
@@ -1078,6 +1141,7 @@ async function handleStreamSse(registryRoutes, dependencyAliases, route, handler
         serviceId: routerOptions.serviceId,
         routeUrl: createServiceRouteUrlBuilder(registryRoutes, extraContext, dependencyAliases, routerOptions.serviceId),
         uiRouteUrl: createUiRouteUrlBuilder(event, extraContext, dependencyAliases, routerOptions.serviceId),
+        diagnostic: (diagnostic) => annotateHttpOutcome(event, diagnostic),
         response: responseHelper,
         file: fileResponseHelper,
         ...(obs ? { obs } : {})
@@ -1158,18 +1222,18 @@ async function resolveRequestAuth(apiAuth, event, authContext, route, method, ob
                 : undefined;
     if (!primary || !callerMode) {
         if (required)
-            return { status: 401, error: "Authentication required" };
+            return { status: 401, error: "Authentication required", code: "auth.required" };
         return { status: 200 };
     }
     const allowedCallers = apiAuth.callers ?? ["user"];
     if (!allowedCallers.includes(callerMode)) {
         if (required)
-            return { status: 403, error: `${callerMode} callers are not allowed` };
+            return { status: 403, error: `${callerMode} callers are not allowed`, code: "auth.caller_not_allowed" };
         return { status: 200 };
     }
     if (!authContext) {
         if (required)
-            return { status: 503, error: "Auth context unavailable" };
+            return { status: 503, error: "Auth context unavailable", code: "auth.context_unavailable" };
         return { status: 200 };
     }
     if (callerMode === "user") {
@@ -1179,14 +1243,14 @@ async function resolveRequestAuth(apiAuth, event, authContext, route, method, ob
     const tenantId = event.req.headers.get("x-bp-tenant-id");
     const appId = event.req.headers.get("x-bp-app-id");
     if (!sourceServiceId || !tenantId || !appId) {
-        return { status: 401, error: "Service, tenant, and app headers are required for S2S calls" };
+        return { status: 401, error: "Service, tenant, and app headers are required for S2S calls", code: "s2s.headers_missing" };
     }
     if (tenantId !== authContext.tenantId || appId !== authContext.appId) {
-        return { status: 401, error: "S2S headers do not match the resolved tenant/app" };
+        return { status: 401, error: "S2S headers do not match the resolved tenant/app", code: "s2s.context_mismatch" };
     }
     if (!authContext.serviceVerifier) {
         if (required)
-            return { status: 503, error: "Service auth context unavailable" };
+            return { status: 503, error: "Service auth context unavailable", code: "s2s.verifier_unavailable" };
         return { status: 200 };
     }
     const verifyService = async (token, mode) => {
@@ -1204,7 +1268,11 @@ async function resolveRequestAuth(apiAuth, event, authContext, route, method, ob
         catch (err) {
             obs?.logger.warn("Service token verification failed: {msg}", { msg: err.message });
             const status = err.status === 403 ? 403 : 401;
-            return { status, error: status === 403 ? "Service access denied" : "Invalid service token" };
+            return {
+                status,
+                error: status === 403 ? "Service access denied" : "Invalid service token",
+                code: status === 403 ? "s2s.access_denied" : "s2s.token_invalid"
+            };
         }
     };
     if (callerMode === "service") {
@@ -1214,11 +1282,17 @@ async function resolveRequestAuth(apiAuth, event, authContext, route, method, ob
         return { status: 200, serviceCaller, callerMode };
     }
     if (!secondary || isServiceToken(primary)) {
-        return { status: 401, error: "Delegated calls require a BP user token and a service token" };
+        return {
+            status: 401,
+            error: "Delegated calls require a BP user token and a service token",
+            code: "s2s.delegated_token_invalid"
+        };
     }
     const userResult = await resolveUserRequestAuth(primary, apiAuth, authContext, obs);
     if (userResult.error || !userResult.user)
-        return userResult.error ? userResult : { status: 401, error: "Valid BP user token required" };
+        return userResult.error
+            ? userResult
+            : { status: 401, error: "Valid BP user token required", code: "s2s.delegated_token_invalid" };
     const serviceCaller = await verifyService(secondary, "delegated");
     if ("status" in serviceCaller)
         return required ? serviceCaller : { status: 200 };
@@ -1229,7 +1303,7 @@ async function resolveUserRequestAuth(bearer, apiAuth, authContext, obs) {
     const verifier = authContext.verifier;
     if (!verifier) {
         if (required)
-            return { status: 503, error: "Auth context unavailable" };
+            return { status: 503, error: "Auth context unavailable", code: "auth.context_unavailable" };
         return { status: 200 };
     }
     let claims;
@@ -1246,7 +1320,7 @@ async function resolveUserRequestAuth(bearer, apiAuth, authContext, obs) {
     catch (err) {
         obs?.logger.warn("JWT verification failed: {msg}", { msg: err.message });
         if (required)
-            return { status: 401, error: "Invalid token" };
+            return { status: 401, error: "Invalid token", code: "auth.token_invalid" };
         return { status: 200 };
     }
     if (claims.tenantId !== authContext.tenantId) {
@@ -1255,7 +1329,7 @@ async function resolveUserRequestAuth(bearer, apiAuth, authContext, obs) {
             t2: authContext.tenantId
         });
         if (required)
-            return { status: 401, error: "Token bound to a different tenant" };
+            return { status: 401, error: "Token bound to a different tenant", code: "auth.token_tenant_mismatch" };
         return { status: 200 };
     }
     if (claims.appId !== authContext.appId) {
@@ -1264,7 +1338,7 @@ async function resolveUserRequestAuth(bearer, apiAuth, authContext, obs) {
             a2: authContext.appId
         });
         if (required)
-            return { status: 401, error: "Token bound to a different app" };
+            return { status: 401, error: "Token bound to a different app", code: "auth.token_app_mismatch" };
         return { status: 200 };
     }
     if (apiAuth.permissions.length > 0) {
@@ -1297,6 +1371,7 @@ async function resolveUserRequestAuth(bearer, apiAuth, authContext, obs) {
                 return {
                     status: 403,
                     error: "Insufficient permissions",
+                    code: "auth.permissions_insufficient",
                     requiredPermissions: apiAuth.permissions
                 };
             }
@@ -1353,7 +1428,7 @@ function formatRequiredPermissions(requiredPermissions = []) {
         .map((requirement) => `${requirement.serviceId} / ${requirement.viewId} / ${requirement.permissions.join("+")}`)
         .join("; ");
 }
-function renderAuthError(route, event, status, message, requiredPermissions = [], context) {
+function renderAuthError(route, event, status, code, message, requiredPermissions = [], context) {
     const renderer = rendererFromEvent(event);
     const acceptHeader = acceptHeaderFromEvent(event);
     const representation = resolveRequestedRepresentation(acceptHeader);
@@ -1371,10 +1446,10 @@ function renderAuthError(route, event, status, message, requiredPermissions = []
         if (statusRenderer && context) {
             try {
                 const html = statusRenderer.render({ error: message, status, requiredPermissions }, context);
-                return new Response(toHtmlString(html), {
+                return coreResponse(new Response(toHtmlString(html), {
                     status,
                     headers: { ...corsHeaders, "content-type": htmlContentType("status", route.chrome) }
-                });
+                }), code, message);
             }
             catch {
                 // fall through to JSON
@@ -1392,12 +1467,24 @@ function renderAuthError(route, event, status, message, requiredPermissions = []
         </div>
       </section>
     `;
-        return new Response(html, {
+        return coreResponse(new Response(html, {
             status,
             headers: { ...corsHeaders, "content-type": renderer ? htmlContentType("status", route.chrome) : "text/html; charset=utf-8" }
+        }), code, message);
+    }
+    return coreJsonResponse({ error: message, status, requiredPermissions }, status, code, message, undefined, corsHeaders);
+}
+async function withCoreFailure(event, code, handler) {
+    try {
+        return await handler();
+    }
+    catch (error) {
+        annotateCoreHttpOutcome(event, {
+            code,
+            reason: (error instanceof Error ? error.message : String(error)).slice(0, 2048)
         });
+        throw error;
     }
-    return jsonResponse({ error: message, status, requiredPermissions }, status, corsHeaders);
 }
 function readTenantAppFromEvent(event) {
     const ctx = event;
@@ -1424,19 +1511,19 @@ function renderUpgradeRequired(route, event, validation, context) {
                     reason: validation.reason,
                     upgradeUrl: validation.upgradeUrl
                 }, context);
-                return htmlResponse(toHtmlString(html), status, htmlContentType("status", route.chrome));
+                return coreResponse(htmlResponse(toHtmlString(html), status, htmlContentType("status", route.chrome)), "route.tenant_app_unavailable", validation.reason ?? "Tenant/app is not available for this service");
             }
             catch {
                 // fall through to JSON
             }
         }
     }
-    return jsonResponse({
+    return coreJsonResponse({
         status,
         error: "Upgrade Required",
         reason: validation.reason,
         upgradeUrl: validation.upgradeUrl
-    }, status, extraHeaders);
+    }, status, "route.tenant_app_unavailable", validation.reason ?? "Upgrade required", undefined, extraHeaders);
 }
 function applyBpHeadersToEvent(event, collector) {
     const { setHeaders, removeHeaders } = collector.emit();
@@ -1481,11 +1568,12 @@ export function registerBpWellKnownRoutes(app, manifest, bpSchema, options = {})
             id = decodeURIComponent(encodedId);
         }
         catch {
-            return jsonResponse({ error: "invalid_resource_id" }, 400);
+            return coreJsonResponse({ error: "invalid_resource_id" }, 400, "discovery.resource_id_invalid", "Developer resource id is not valid URL encoding");
         }
         const resource = manifest.developerResources.find((candidate) => candidate.id === id);
-        if (!resource)
-            return jsonResponse({ error: "resource_not_found" }, 404);
+        if (!resource) {
+            return coreJsonResponse({ error: "resource_not_found" }, 404, "discovery.resource_not_found", `Developer resource "${id}" was not found`);
+        }
         return new Response(resource.content, {
             headers: {
                 "content-type": resource.mediaType,