@cosmicdrift/kumiko-framework 0.66.0 → 0.67.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.66.0",
+  "version": "0.67.1",
   "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.65.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.67.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/index.ts

@@ -204,6 +204,7 @@ export {
   findTierResolverUsage,
   TENANT_TIER_RESOLVER_EXT,
   type TierResolverPlugin,
+  type TrialGate,
 } from "./tier-resolver-extension";
 // Types
 export type {

package/src/engine/tier-resolver-extension.ts

@@ -41,12 +41,29 @@ export const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
  * **System-context convention:** call mit SYSTEM_TENANT_ID erwartet die union
  * aller tier-features (siehe DispatcherOptions.effectiveFeatures doc-block).
  */
-export type EffectiveFeaturesResolver = (tenantId: TenantId) => ReadonlySet<string>;
+export type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & {
+  /**
+   * Optionaler Live-Trial-Gate, vom dispatcher-feature-gate NUR konsultiert
+   * wenn der synchrone Resolver ein Feature als disabled meldet. Liest das
+   * Signup-Datum des Tenants live (tenant.inserted_at) und returnt true wenn
+   * der Tenant im Trial-Fenster ist UND das Feature zum Trial-Tier gehört.
+   * Async + nicht im Boot-Cache, weil der Trial zeit-abgeleitet ist (ändert
+   * sich zwischen Requests). Nur die 2 Gate-Aufrufstellen awaiten ihn; der
+   * synchrone Hot-Path (ctx.hasFeature, Feature-Set) bleibt unberührt.
+   */
+  readonly trialGate?: TrialGate;
+};
+
+/**
+ * Live-Trial-Gate-Shape. Siehe EffectiveFeaturesResolver.trialGate.
+ */
+export type TrialGate = (tenantId: TenantId, featureName: string) => Promise<boolean>;
 
 /**
  * Plugin-shape für tier-resolver-extension. Plugins implementieren `build`
  * als boot-time factory: kriegen `db` + `registry` (post-stack-setup),
- * laden initial cache aus DB, returnen den synchronen resolver-callback.
+ * laden initial cache aus DB, returnen den synchronen resolver-callback
+ * (optional mit angehängtem `trialGate`).
  */
 export type TierResolverPlugin = {
   readonly build: (deps: {

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -376,6 +376,37 @@ describe("dispatcher feature-gate", () => {
     });
   });
 
+  test("trialGate: disabled feature is allowed on the gate's cold path when trialGate returns true", async () => {
+    // Beweist die Live-Trial-Mechanik: der sync resolver hat das Feature NICHT
+    // im Set (alles disabled), aber checkFeatureEnabled konsultiert den async
+    // trialGate auf dem disabled-Pfad. Deckt beide Aufrufstellen ab (query =
+    // ensureFeatureEnabled, write = checkFeatureEnabled).
+    const registry = createRegistry([toggled()]);
+    let trialOpen = false;
+    const effectiveFeatures = Object.assign(() => new Set<string>(), {
+      trialGate: async (_tenantId: TenantId, feature: string) => trialOpen && feature === "toggled",
+    });
+    const dispatcher = createDispatcher(registry, {}, { effectiveFeatures });
+
+    // Trial zu → 403 (resolver-Set leer, Gate verweigert).
+    await expect(dispatcher.query("toggled:query:widget:list", {}, user)).rejects.toThrow(
+      /feature toggled is disabled/,
+    );
+    const writeClosed = await dispatcher.write("toggled:write:widget:create", { name: "x" }, user);
+    expect(writeClosed.isSuccess).toBe(false);
+    if (!writeClosed.isSuccess) expect(writeClosed.error.code).toBe("feature_disabled");
+
+    // Trial offen → Gate lässt durch, obwohl der Resolver das Feature nicht
+    // führt. Query passiert; Write passiert das Gate (scheitert ggf. später an
+    // fehlender DB, aber NICHT mehr an feature_disabled).
+    trialOpen = true;
+    await expect(dispatcher.query("toggled:query:widget:list", {}, user)).resolves.toEqual({
+      items: [],
+    });
+    const writeOpen = await dispatcher.write("toggled:write:widget:create", { name: "x" }, user);
+    if (!writeOpen.isSuccess) expect(writeOpen.error.code).not.toBe("feature_disabled");
+  });
+
   test("Sprint 8a: per-tenant gating — Tenant A passes, Tenant B gets feature_disabled", async () => {
     // Beweist die Phase-1-Architektur: dispatcher ruft effectiveFeatures
     // mit user.tenantId, resolver kann pro Tenant unterschiedliche Sets

package/src/pipeline/dispatcher.ts

@@ -659,10 +659,10 @@ export function createDispatcher(
   // When `effectiveFeatures` is not wired (tests, apps without feature-toggles
   // loaded), every handler is treated as enabled — the gate is a pure
   // pass-through in that common case.
-  function checkFeatureEnabled(
+  async function checkFeatureEnabled(
     qualifiedHandler: string,
     tenantId: TenantId,
-  ): import("../errors").FeatureDisabledError | undefined {
+  ): Promise<import("../errors").FeatureDisabledError | undefined> {
     if (!effectiveFeatures) return undefined;
     const owner = registry.getHandlerFeature(qualifiedHandler);
     // skip: handler without an owning feature cannot be toggled — shouldn't
@@ -671,11 +671,18 @@ export function createDispatcher(
     if (!owner) return undefined;
     const set = effectiveFeatures(tenantId);
     if (set.has(owner)) return undefined;
+    // Feature is off for the stored tier — give the live trial-gate a last
+    // chance. Time-derived (tenant.inserted_at + window), so it can't live in
+    // the boot-cached sync resolver; consulted only on this already-disabled
+    // cold path, never on the hot enabled path.
+    if (effectiveFeatures.trialGate && (await effectiveFeatures.trialGate(tenantId, owner))) {
+      return undefined;
+    }
     return new FeatureDisabledError(owner, qualifiedHandler);
   }
 
-  function ensureFeatureEnabled(qualifiedHandler: string, tenantId: TenantId): void {
-    const err = checkFeatureEnabled(qualifiedHandler, tenantId);
+  async function ensureFeatureEnabled(qualifiedHandler: string, tenantId: TenantId): Promise<void> {
+    const err = await checkFeatureEnabled(qualifiedHandler, tenantId);
     if (err) throw err;
   }
 
@@ -737,7 +744,7 @@ export function createDispatcher(
     // disabled feature must not consume the rate-limit quota — the call
     // never happened from the feature's perspective. Order is: lookup →
     // feature-gate → rate-limit → access → validation → handler.
-    ensureFeatureEnabled(type, user.tenantId);
+    await ensureFeatureEnabled(type, user.tenantId);
 
     // Rate-limit gate runs BEFORE access-check on purpose: anonymous /
     // unauthorized callers must hit the cap too (otherwise the limit
@@ -1028,7 +1035,7 @@ export function createDispatcher(
 
     // Feature-toggle gate: disabled handlers must short-circuit before any
     // rate-limit/access/validation work — see executeQueryInner comment.
-    const disabledErr = checkFeatureEnabled(type, user.tenantId);
+    const disabledErr = await checkFeatureEnabled(type, user.tenantId);
     if (disabledErr) return writeFailure(disabledErr);
 
     // Rate-limit gate before access (same reasoning as in executeQueryInner).