@cosmicdrift/kumiko-framework 0.82.0 → 0.84.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.82.0",
+  "version": "0.84.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.84.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/__tests__/boot-validator-gdpr-storage.test.ts

@@ -1,9 +1,14 @@
 // V1 — GDPR storage-persistence boot guard. Catches the prod failure class:
 // user-data-rights mounted but exports land in an ephemeral / missing store,
 // and s3-env selected as the GDPR store without its env vars set.
+// V2 — export-without-erase guard. Catches features that register an export
+// hook but no delete hook (Art.17 violation).
 
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
-import { validateGdprStoragePersistence } from "../boot-validator/gdpr-storage";
+import {
+  validateGdprHookCompleteness,
+  validateGdprStoragePersistence,
+} from "../boot-validator/gdpr-storage";
 import { defineFeature } from "../define-feature";
 
 const udr = () => defineFeature("user-data-rights", () => {});
@@ -72,3 +77,66 @@ describe("validateGdprStoragePersistence (V1)", () => {
     expect(warnSpy).not.toHaveBeenCalled();
   });
 });
+
+describe("validateGdprHookCompleteness (V2)", () => {
+  let warnSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  const exportFn = async () => null;
+  const deleteFn = async () => {};
+
+  test("export + delete hooks → no warn", () => {
+    const f = defineFeature("my-feature", (r) => {
+      r.useExtension("userData", "myEntity", { export: exportFn, delete: deleteFn });
+    });
+    validateGdprHookCompleteness([f]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("export hook without delete hook → Art.17 warn", () => {
+    const f = defineFeature("my-feature", (r) => {
+      r.useExtension("userData", "myEntity", { export: exportFn });
+    });
+    validateGdprHookCompleteness([f]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    expect(msg).toContain("my-feature");
+    expect(msg).toContain("myEntity");
+    expect(msg).toContain("Art.17");
+  });
+
+  test("delete hook only (no export) → no warn", () => {
+    const f = defineFeature("my-feature", (r) => {
+      r.useExtension("userData", "myEntity", { delete: deleteFn });
+    });
+    validateGdprHookCompleteness([f]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("no EXT_USER_DATA hooks at all → no warn", () => {
+    const f = defineFeature("my-feature", (r) => {
+      r.useExtension("fileProvider", "s3");
+    });
+    validateGdprHookCompleteness([f]);
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  test("multiple features, one missing delete → one warn per missing hook", () => {
+    const good = defineFeature("good", (r) => {
+      r.useExtension("userData", "entityA", { export: exportFn, delete: deleteFn });
+    });
+    const bad = defineFeature("bad", (r) => {
+      r.useExtension("userData", "entityB", { export: exportFn });
+    });
+    validateGdprHookCompleteness([good, bad]);
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(String(warnSpy.mock.calls[0]?.[0])).toContain("entityB");
+  });
+});

package/src/engine/__tests__/build-config-feature-schema.test.ts

@@ -220,8 +220,7 @@ describe("buildConfigFeatureSchema — machine-role does not leak into screen ac
   test("a key with write ['system','SystemAdmin'] yields a SystemAdmin-only screen (no 'system')", () => {
     const s = buildConfigFeatureSchema(createRegistry([mixedWrite]));
     const screen = s.screens.find((x) => x.id === "mixed-system");
-    if (!screen || screen.type !== "configEdit")
-      throw new Error("no mixed-system configEdit screen");
+    if (screen?.type !== "configEdit") throw new Error("no mixed-system configEdit screen");
     expect(screen.access).toEqual({ roles: ["SystemAdmin"] });
     const roles = screen.access && "roles" in screen.access ? screen.access.roles : [];
     expect(roles).not.toContain("system");

package/src/engine/boot-validator/gdpr-storage.ts

@@ -57,3 +57,23 @@ export function validateGdprStoragePersistence(features: readonly FeatureDefinit
     }
   }
 }
+
+// V2: export-without-erase guard. A feature that registers an EXT_USER_DATA
+// export hook without a matching delete hook exports data under Art.20 but
+// never erases it on forget — an Art.17 violation. Registry-level signal only;
+// runtime no-ops (a delete hook that silently skips) are not detectable here.
+export function validateGdprHookCompleteness(features: readonly FeatureDefinition[]): void {
+  for (const feature of features) {
+    for (const usage of feature.extensionUsages) {
+      if (usage.extensionName !== "userData") continue;
+      const hasExport = typeof usage.options?.["export"] === "function";
+      const hasDelete = typeof usage.options?.["delete"] === "function";
+      if (hasExport && !hasDelete) {
+        // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+        console.warn(
+          `[kumiko:boot] Feature "${feature.name}" exports entity "${usage.entityName}" via EXT_USER_DATA but registers no delete hook — data is included in Art.20 exports but never erased on forget (Art.17 risk). Add a delete hook, or a no-op with a comment explaining why erasure is intentionally skipped.`,
+        );
+      }
+    }
+  }
+}

package/src/engine/boot-validator/index.ts

@@ -25,7 +25,7 @@ import {
   validateReferenceFields,
   validateTransitions,
 } from "./entity-handler";
-import { validateGdprStoragePersistence } from "./gdpr-storage";
+import { validateGdprHookCompleteness, validateGdprStoragePersistence } from "./gdpr-storage";
 import { validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
 import {
@@ -162,6 +162,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
+  validateGdprHookCompleteness(features);
 
   if (hasEncryptedFields && !process.env["ENCRYPTION_KEY"]) {
     throw new Error("ENCRYPTION_KEY environment variable is required (encrypted fields in use)");

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,