@cosmicdrift/kumiko-framework 0.125.1 → 0.125.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.125.1",
+  "version": "0.125.2",
   "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>",
@@ -189,7 +189,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.125.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.125.2",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -24,6 +24,17 @@ const fileProvider = (name: string) =>
 
 const S3_ENV = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"] as const;
 
+// V2/V3 are hard boot gates now — capture the thrown message so a single case
+// can assert several substrings (feature, entity, article).
+function catchMessage(fn: () => void): string {
+  try {
+    fn();
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+  throw new Error("expected function to throw, but it did not");
+}
+
 describe("validateGdprStoragePersistence (V1)", () => {
   let warnSpy: ReturnType<typeof spyOn>;
   let savedEnv: Array<readonly [string, string | undefined]>;
@@ -84,79 +95,53 @@ describe("validateGdprStoragePersistence (V1)", () => {
 });
 
 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", () => {
+  test("export + delete hooks → no throw", () => {
     const f = defineFeature("my-feature", (r) => {
       r.useExtension(EXT_USER_DATA, "myEntity", { export: exportFn, delete: deleteFn });
     });
-    validateGdprHookCompleteness([f]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprHookCompleteness([f])).not.toThrow();
   });
 
-  test("export hook without delete hook → Art.17 warn", () => {
+  test("export hook without delete hook → Art.17 throw", () => {
     const f = defineFeature("my-feature", (r) => {
       r.useExtension(EXT_USER_DATA, "myEntity", { export: exportFn });
     });
-    validateGdprHookCompleteness([f]);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    const msg = String(warnSpy.mock.calls[0]?.[0]);
+    const msg = catchMessage(() => validateGdprHookCompleteness([f]));
     expect(msg).toContain("my-feature");
     expect(msg).toContain("myEntity");
     expect(msg).toContain("Art.17");
   });
 
-  test("delete hook only (no export) → no warn", () => {
+  test("delete hook only (no export) → no throw", () => {
     const f = defineFeature("my-feature", (r) => {
       r.useExtension(EXT_USER_DATA, "myEntity", { delete: deleteFn });
     });
-    validateGdprHookCompleteness([f]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprHookCompleteness([f])).not.toThrow();
   });
 
-  test("no EXT_USER_DATA hooks at all → no warn", () => {
+  test("no EXT_USER_DATA hooks at all → no throw", () => {
     const f = defineFeature("my-feature", (r) => {
       r.useExtension("fileProvider", "s3");
     });
-    validateGdprHookCompleteness([f]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprHookCompleteness([f])).not.toThrow();
   });
 
-  test("multiple features, one missing delete → one warn per missing hook", () => {
+  test("multiple features, one missing delete → throws naming the offender", () => {
     const good = defineFeature("good", (r) => {
       r.useExtension(EXT_USER_DATA, "entityA", { export: exportFn, delete: deleteFn });
     });
     const bad = defineFeature("bad", (r) => {
       r.useExtension(EXT_USER_DATA, "entityB", { export: exportFn });
     });
-    validateGdprHookCompleteness([good, bad]);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(String(warnSpy.mock.calls[0]?.[0])).toContain("entityB");
+    const msg = catchMessage(() => validateGdprHookCompleteness([good, bad]));
+    expect(msg).toContain("entityB");
   });
 });
 
 describe("validateGdprPiiHookCoverage (V3)", () => {
-  let warnSpy: ReturnType<typeof spyOn>;
-
-  beforeEach(() => {
-    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    warnSpy.mockRestore();
-  });
-
   const exportFn = async () => null;
   const deleteFn = async () => {};
 
@@ -174,30 +159,38 @@ describe("validateGdprPiiHookCoverage (V3)", () => {
       );
     });
 
-  test("user-data-rights not mounted → no warn", () => {
-    validateGdprPiiHookCoverage([piiFeature()]);
-    expect(warnSpy).not.toHaveBeenCalled();
+  test("user-data-rights not mounted → no throw", () => {
+    expect(() => validateGdprPiiHookCoverage([piiFeature()])).not.toThrow();
   });
 
-  test("pii entity without any EXT_USER_DATA hook → warn naming entity and fields", () => {
-    validateGdprPiiHookCoverage([udr(), piiFeature()]);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    const msg = String(warnSpy.mock.calls[0]?.[0]);
+  test("pii entity without any EXT_USER_DATA hook → throws naming entity and fields", () => {
+    const msg = catchMessage(() => validateGdprPiiHookCoverage([udr(), piiFeature()]));
     expect(msg).toContain('"contact"');
     expect(msg).toContain("email");
     expect(msg).toContain("note");
     expect(msg).toContain("Art.17");
   });
 
-  test("pii entity with hook registered by another feature → no warn", () => {
+  test("pii entity with hook registered by another feature → no throw", () => {
     const hooks = defineFeature("crm-user-data", (r) => {
       r.useExtension(EXT_USER_DATA, "contact", { export: exportFn, delete: deleteFn });
     });
-    validateGdprPiiHookCoverage([udr(), piiFeature(), hooks]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprPiiHookCoverage([udr(), piiFeature(), hooks])).not.toThrow();
   });
 
-  test("entity without subject annotations → no warn", () => {
+  test("no-op hook is the intentional escape hatch → no throw", () => {
+    const hooks = defineFeature("crm-user-data", (r) => {
+      // Escape hatch: erasure handled elsewhere (crypto-shredding key-erase),
+      // so the pipeline hook is a deliberate no-op.
+      r.useExtension(EXT_USER_DATA, "contact", {
+        export: async () => null,
+        delete: async () => {},
+      });
+    });
+    expect(() => validateGdprPiiHookCoverage([udr(), piiFeature(), hooks])).not.toThrow();
+  });
+
+  test("entity without subject annotations → no throw", () => {
     const plain = defineFeature("catalog", (r) => {
       r.entity(
         "product",
@@ -206,11 +199,10 @@ describe("validateGdprPiiHookCoverage (V3)", () => {
         }),
       );
     });
-    validateGdprPiiHookCoverage([udr(), plain]);
-    expect(warnSpy).not.toHaveBeenCalled();
+    expect(() => validateGdprPiiHookCoverage([udr(), plain])).not.toThrow();
   });
 
-  test("userOwned field alone counts as user-subject data → warn", () => {
+  test("userOwned field alone counts as user-subject data → throws", () => {
     const f = defineFeature("notes", (r) => {
       r.entity(
         "note",
@@ -222,8 +214,7 @@ describe("validateGdprPiiHookCoverage (V3)", () => {
         }),
       );
     });
-    validateGdprPiiHookCoverage([udr(), f]);
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(String(warnSpy.mock.calls[0]?.[0])).toContain('"note"');
+    const msg = catchMessage(() => validateGdprPiiHookCoverage([udr(), f]));
+    expect(msg).toContain('"note"');
   });
 });

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

@@ -60,10 +60,12 @@ export function validateGdprStoragePersistence(features: readonly FeatureDefinit
   }
 }
 
-// V2: export-without-erase guard. A feature that registers an EXT_USER_DATA
+// V2: export-without-erase gate. 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.
+// never erases it on forget — an Art.17 violation. Hard boot failure: no app
+// should ship a GDPR export path with no erase path. Registry-level signal
+// only; runtime no-ops (a delete hook that silently skips) are not detectable
+// here — those are covered by the export/forget integration tests.
 export function validateGdprHookCompleteness(features: readonly FeatureDefinition[]): void {
   for (const feature of features) {
     for (const usage of feature.extensionUsages) {
@@ -71,21 +73,23 @@ export function validateGdprHookCompleteness(features: readonly FeatureDefinitio
       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.`,
+        throw new Error(
+          `[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 violation). Add a delete hook. If erasure is intentionally handled elsewhere (e.g. crypto-shredding key-erase, parent cascade), register a no-op delete: async () => {} with a comment explaining why.`,
         );
       }
     }
   }
 }
 
-// V3: PII-entity-without-hook guard. V2 checks registered hooks for
+// V3: PII-entity-without-hook gate. V2 checks registered hooks for
 // completeness; V3 catches the entity nobody registered at all — fields
 // annotated as user-subject data (pii / userOwned) yet invisible to the
-// Art.15/20 export and Art.17 forget pipeline. Matching is by entity name
-// across all features (usage.entityName is unqualified); a same-named entity
-// in another feature can mask a gap — accepted for a WARN-level heuristic.
+// Art.15/20 export and Art.17 forget pipeline. Hard boot failure once
+// user-data-rights is mounted: a subject-data entity that skips the pipeline
+// is exactly the "feature built past GDPR" leak this gate exists to stop.
+// Matching is by entity name across all features (usage.entityName is
+// unqualified); a same-named entity in another feature can mask a gap —
+// accepted, as the common case is a distinct entity name.
 export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition[]): void {
   const featureNames = new Set(features.map((f) => f.name));
   if (!featureNames.has("user-data-rights")) {
@@ -110,9 +114,8 @@ export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition
         })
         .map(([name]) => name);
       if (subjectFields.length === 0) continue;
-      // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-      console.warn(
-        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has user-subject fields (${subjectFields.join(", ")}) but no feature registers an EXT_USER_DATA hook for it — the data never appears in Art.15/20 exports and is never erased on forget (Art.17 gap). Register r.useExtension(EXT_USER_DATA, "${entityName}", { export, delete }) in the owning feature or a defaults feature.`,
+      throw new Error(
+        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has user-subject fields (${subjectFields.join(", ")}) but no feature registers an EXT_USER_DATA hook for it — the data never appears in Art.15/20 exports and is never erased on forget (Art.17 gap). Register r.useExtension(EXT_USER_DATA, "${entityName}", { export, delete }) in the owning feature or a defaults feature. If this entity is intentionally out of the pipeline (e.g. crypto-shredding key-erase covers it), register a no-op hook { export: async () => null, delete: async () => {} } with a comment explaining why.`,
       );
     }
   }