@cosmicdrift/kumiko-bundled-features 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/cap-counter/__tests__/enforce-stock-cap.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { enforceStockCap } from "../enforce-cap";
+
+describe("enforceStockCap", () => {
+  test("hardSlot: Grenze ist exakt limit (kein Buffer)", () => {
+    const at = (current: number) => enforceStockCap({ current, limit: 5, profile: "hardSlot" });
+    expect(at(0).state).toBe("ok");
+    expect(at(4).state).toBe("ok");
+    // Tenant hat 5 → die Anlage der 6. wird geblockt (current=5 >= 5).
+    expect(at(5).state).toBe("exceeded");
+    expect(at(6).state).toBe("exceeded");
+  });
+
+  test("storage: 5% Buffer über dem limit", () => {
+    const at = (current: number) => enforceStockCap({ current, limit: 100, profile: "storage" });
+    expect(at(104).state).toBe("ok"); // 104 < 105 (=100×1.05)
+    expect(at(105).state).toBe("exceeded");
+  });
+
+  test("burstable: 20% Buffer", () => {
+    const at = (current: number) => enforceStockCap({ current, limit: 10, profile: "burstable" });
+    expect(at(11).state).toBe("ok"); // 11 < 12 (=10×1.2)
+    expect(at(12).state).toBe("exceeded");
+  });
+
+  test("limit 0 = keine Allowance → jede Anlage exceeded", () => {
+    expect(enforceStockCap({ current: 0, limit: 0, profile: "hardSlot" }).state).toBe("exceeded");
+  });
+
+  test("Result trägt current + limit für die Caller-Fehlermeldung", () => {
+    expect(enforceStockCap({ current: 7, limit: 5, profile: "hardSlot" })).toEqual({
+      state: "exceeded",
+      current: 7,
+      limit: 5,
+    });
+  });
+});

package/src/cap-counter/enforce-cap.ts

@@ -394,3 +394,36 @@ export async function enforceRollingCapAndMaybeNotify(
 
   return result;
 }
+
+// =============================================================================
+// Stock-Cap (Bestand) — live-gezählte Kardinalität gegen Tier-Limit
+// =============================================================================
+
+export type StockCapResult =
+  | { readonly state: "ok"; readonly current: number; readonly limit: number }
+  | { readonly state: "exceeded"; readonly current: number; readonly limit: number };
+
+/**
+ * Stock-Cap: prüft eine vom Caller LIVE gezählte Kardinalität (z.B. Anzahl
+ * existierender Components eines Tenants) gegen ein Tier-Limit.
+ *
+ * Anders als {@link enforceCap}/{@link enforceRollingCap} gibt es KEINEN
+ * gespeicherten Counter: der Caller zählt die Projektion selbst
+ * (`count(*) WHERE tenant_id = …`) und übergibt `current`. Das ist drift-frei
+ * (ein Delete gibt den Slot sofort frei), braucht keine Counter-Tabelle und
+ * kein Increment/Decrement-Bookkeeping. Misst einen Bestand, keinen Fluss.
+ *
+ * Reine Funktion — wirft NICHT und mappt KEINEN HTTP-Status. Ein erreichtes
+ * Stock-Limit heißt „Upgrade nötig", nicht „retry later" (429): der Caller
+ * entscheidet die Reaktion, typisch ein app-eigener 422/`upgrade_required`
+ * mit i18n. Mit `hardSlot` (soft=hard=1.0) ist die Grenze exakt `limit`.
+ */
+export function enforceStockCap(options: {
+  readonly current: number;
+  readonly limit: number;
+  readonly profile: CapToleranceProfileName;
+}): StockCapResult {
+  const hardThreshold = options.limit * CAP_TOLERANCES[options.profile].hard;
+  const state = options.current >= hardThreshold ? "exceeded" : "ok";
+  return { state, current: options.current, limit: options.limit };
+}

package/src/cap-counter/index.ts

@@ -20,7 +20,9 @@ export {
   enforceCapAndMaybeNotify,
   enforceRollingCap,
   enforceRollingCapAndMaybeNotify,
+  enforceStockCap,
   type SoftHitNotifier,
+  type StockCapResult,
 } from "./enforce-cap";
 export { capCounterEntity } from "./entity";
 export { capCounterFeature } from "./feature";