@cosmicdrift/kumiko-framework 0.82.0 → 0.83.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.82.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.83.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/server-error-logging.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { z } from "zod";
+import { createRegistry, defineFeature } from "../../engine";
+import { TestUsers } from "../../stack";
+import { ensureTemporalPolyfill } from "../../time";
+import { buildServer } from "../server";
+
+// Self-ensure Temporal rather than rely on the suite-level preload: the check
+// runs `bun test` from packages/framework where the root preload path doesn't
+// resolve, so buildHandlerContext would otherwise throw before our handler runs
+// and the logged cause would be the polyfill error, not the thrown one.
+await ensureTemporalPolyfill();
+
+const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
+
+const boomFeature = defineFeature("boom", (r) => {
+  r.queryHandler(
+    "explode",
+    z.object({}),
+    async () => {
+      throw new Error("disk on fire");
+    },
+    { access: { openToAll: true } },
+  );
+});
+
+const { app, jwt } = buildServer({
+  registry: createRegistry([boomFeature]),
+  context: {},
+  jwtSecret: JWT_SECRET,
+});
+
+async function auth(): Promise<Record<string, string>> {
+  const token = await jwt.sign(TestUsers.admin);
+  return { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+}
+
+// Find the `[api] handler failed` line our logServerFault emits (createFallback
+// Logger console-falls-back to `console.error("[api] handler failed", data)`).
+// Match on the namespaced message so unrelated console noise can't false-fire.
+function apiFaultLog(calls: unknown[][]): string | undefined {
+  const hit = calls.find(
+    (args) => typeof args[0] === "string" && args[0].includes("[api] handler failed"),
+  );
+  return hit ? JSON.stringify(hit) : undefined;
+}
+
+describe("HTTP layer logs unexpected 5xx faults", () => {
+  test("a throwing query 500s AND the cause stack reaches the log", async () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "error").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      const res = await app.request("/api/query", {
+        method: "POST",
+        headers: await auth(),
+        body: JSON.stringify({ type: "boom:query:explode", payload: {} }),
+      });
+      expect(res.status).toBe(500);
+      const logged = apiFaultLog(calls);
+      expect(logged).toBeDefined();
+      expect(logged).toContain("boom:query:explode"); // which handler 500'd
+      expect(logged).toContain("disk on fire"); // the cause — the line that was missing in prod
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("an expected 404 does NOT log a server fault (no 4xx noise)", async () => {
+    const calls: unknown[][] = [];
+    const spy = spyOn(console, "error").mockImplementation((...args) => {
+      calls.push(args);
+    });
+    try {
+      const res = await app.request("/api/query", {
+        method: "POST",
+        headers: await auth(),
+        body: JSON.stringify({ type: "nope:query:nothing", payload: {} }),
+      });
+      expect(res.status).toBe(404);
+      expect(apiFaultLog(calls)).toBeUndefined();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/src/api/routes.ts

@@ -7,6 +7,7 @@ import {
   toKumikoError,
   ValidationError,
 } from "../errors";
+import { createFallbackLogger } from "../logging";
 import type { Dispatcher } from "../pipeline/dispatcher";
 import { stringifyJson } from "../utils/safe-json";
 import { Routes } from "./api-constants";
@@ -23,11 +24,11 @@ export function createApiRoutes(dispatcher: Dispatcher) {
     try {
       const result = await dispatcher.write(body.type, body.payload, user, body.requestId);
       if (!result.isSuccess) {
-        return writeErrorResponse(c, reraiseAsKumikoError(result.error));
+        return writeErrorResponse(c, reraiseAsKumikoError(result.error), body.type);
       }
       return jsonResponse(c, result);
     } catch (e) {
-      return writeErrorResponse(c, toKumiko(e));
+      return writeErrorResponse(c, toKumiko(e), body.type);
     }
   });
 
@@ -62,6 +63,9 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       if (!result.isSuccess) {
         const err = reraiseAsKumikoError(result.error);
         const requestId = requestContext.get()?.requestId;
+        const failedType =
+          result.failedIndex != null ? body.commands[result.failedIndex]?.type : undefined;
+        logServerFault(err, requestId, failedType);
         const { error } = serializeError(err, requestId);
         // Keep failedIndex + results alongside the error envelope so callers
         // can tell which command in the batch failed and inspect the partial
@@ -91,7 +95,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       const result = await dispatcher.query(body.type, body.payload, user);
       return jsonResponse(c, { data: result });
     } catch (e) {
-      return queryErrorResponse(c, toKumiko(e));
+      return queryErrorResponse(c, toKumiko(e), body.type);
     }
   });
 
@@ -103,7 +107,7 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       await dispatcher.command(body.type, body.payload, user);
       return c.json({ ok: true }, 202);
     } catch (e) {
-      return queryErrorResponse(c, toKumiko(e));
+      return queryErrorResponse(c, toKumiko(e), body.type);
     }
   });
 
@@ -116,21 +120,43 @@ function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode =
 
 const toKumiko = toKumikoError;
 
+// Unexpected server faults (5xx) carry their diagnostic stack only on the
+// in-process error — serializeError strips cause/details from the wire body.
+// Without this a wrapped throw (InternalError{cause}) returns a 500 with zero
+// log lines, leaving ops nothing to debug (the bug this guards). 4xx are
+// expected client outcomes and stay unlogged. `type` is the only handler
+// discriminator — every request hits the same /api/{query,command} path.
+function logServerFault(err: KumikoError, requestId: string | undefined, type?: string): void {
+  if (err.httpStatus < 500) {
+    // skip: 4xx are expected client outcomes (not-found, validation, denied) — logging them is noise
+    return;
+  }
+  const cause = err.cause;
+  createFallbackLogger("api").error("handler failed", {
+    requestId,
+    type,
+    code: err.code,
+    message: err.message,
+    cause: cause instanceof Error ? cause.message : cause,
+    stack: cause instanceof Error ? cause.stack : err.stack,
+  });
+}
+
 // For /write + /batch: keep the isSuccess flag so clients can flip on a single
 // boolean (mirrors the success shape). The actual error body is the
 // error-contract payload nested under .error.
-function writeErrorResponse(c: Context, err: KumikoError, statusOverride?: number) {
+function writeErrorResponse(c: Context, err: KumikoError, type?: string) {
   const requestId = requestContext.get()?.requestId;
+  logServerFault(err, requestId, type);
   const { error } = serializeError(err, requestId);
-  const status = (statusOverride ?? err.httpStatus) as ContentfulStatusCode; // @cast-boundary engine-payload
-  return c.json({ isSuccess: false, error }, status);
+  return c.json({ isSuccess: false, error }, err.httpStatus as ContentfulStatusCode); // @cast-boundary engine-payload
 }
 
 // For /query + /command: no isSuccess on success (just { data } / {ok}), so we
 // keep the same lean shape on failure — only the `error` key.
-function queryErrorResponse(c: Context, err: KumikoError, statusOverride?: number) {
+function queryErrorResponse(c: Context, err: KumikoError, type?: string) {
   const requestId = requestContext.get()?.requestId;
+  logServerFault(err, requestId, type);
   const body = serializeError(err, requestId);
-  const status = (statusOverride ?? err.httpStatus) as ContentfulStatusCode; // @cast-boundary engine-payload
-  return c.json(body, status);
+  return c.json(body, err.httpStatus as ContentfulStatusCode); // @cast-boundary engine-payload
 }

package/src/engine/extensions/user-data.ts

@@ -34,6 +34,20 @@ type UserId = string;
  */
 export type UserDataDeleteStrategy = "delete" | "anonymize";
 
+/**
+ * Effective tenant-occupancy model for THIS tenant during a forget run, set by
+ * the forget orchestrator. `"single-user"` means the tenant has exactly one
+ * member (the user being forgotten) — so a tenant-scoped contributor MAY erase
+ * the tenant's data as that user's personal data. `"multi-user"` (the safe
+ * default) means tenant-scoped rows are shared and must NOT be erased per-user.
+ *
+ * The orchestrator derives this from the app-level `tenantModel` config AND a
+ * runtime sole-member check, so a stray invite that makes the config's
+ * `"single-user"` claim false at runtime never causes a co-member's data to be
+ * deleted. Absent → treat as `"multi-user"`.
+ */
+export type TenantUserModel = "single-user" | "multi-user";
+
 /**
  * Context-Snapshot der dem Hook übergeben wird. Sprint 2 erweitert
  * das ggf. um cancel-/timeout-Marker; aktuell minimaler Schnitt.
@@ -70,6 +84,12 @@ export interface UserDataHookCtx {
   readonly buildStorageProvider?: (
     tenantId: TenantId,
   ) => Promise<UserDataStorageProvider | undefined>;
+  /**
+   * Effective tenant-occupancy model for this tenant — see {@link TenantUserModel}.
+   * A tenant-scoped contributor reads this to decide whether per-user erasure may
+   * touch tenant-scoped rows. Absent → treat as `"multi-user"` (no erasure).
+   */
+  readonly tenantModel?: TenantUserModel;
 }
 
 /**

package/src/engine/index.ts

@@ -80,6 +80,7 @@ export {
   EXT_USER_DATA_ORDER,
 } from "./extension-names";
 export type {
+  TenantUserModel,
   UserDataDeleteHook,
   UserDataDeleteStrategy,
   UserDataExportHook,