@cosmicdrift/kumiko-framework 0.305.0 → 0.306.0

package/src/engine/feature-ast/patterns.ts

@@ -71,7 +71,7 @@ import type {
   AgentHandlerHints,
   ClaimKeyType,
   EscapeHatchDeclaration,
-  RateLimitOption,
+  RateLimitDeclaration,
 } from "../types/handlers";
 import type { HookPhase } from "../types/hooks";
 import type { HttpRouteMethod } from "../types/http-route";
@@ -81,6 +81,7 @@ import type { RelationDefinition } from "../types/relations";
 import type { ScreenDefinition } from "../types/screen";
 import type { TreeActionDef } from "../types/tree-node";
 import type { WorkspaceDefinition } from "../types/workspace";
+import type { RawRefSentinel } from "./extractors/shared";
 import type { SourceLocation } from "./source-location";
 
 // =============================================================================
@@ -367,6 +368,10 @@ export type ScreenPattern = {
 // overrides that derivation explicitly (force-show or force-hide);
 // `agent.risk` ("low" | "mid" | "high") classifies the action's blast
 // radius, defaulting to "mid" for a write handler.
+//
+// access/rateLimit/escapeHatch/agent additionally accept a RawRefSentinel
+// for a non-literal value (imported/same-file const, or a sub-value like
+// `personalData: PD`) that would otherwise lose the reference on render.
 export type WriteHandlerPattern = {
   readonly kind: "writeHandler";
   readonly source: SourceLocation;
@@ -384,12 +389,12 @@ export type WriteHandlerPattern = {
   // handlerBody: the closure body as source text. Always opaque — AI
   // generates raw TypeScript, no DSL interpretation.
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
+  readonly access?: AccessRule | RawRefSentinel;
   readonly description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
+  readonly agent?: AgentHandlerHints | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
   readonly unsafeSkipTransitionGuard?: boolean;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.queryHandler(...)` — registers a read handler: name, Zod input schema,
@@ -408,25 +413,27 @@ export type QueryHandlerPattern = {
   readonly handlerName?: string;
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
+  readonly access?: AccessRule | RawRefSentinel;
   readonly description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly agent?: AgentHandlerHints | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.streamHandler(...)` — registers a streaming read handler: name, Zod
-// input schema, async-generator handler closure, plus optional `access` and
-// `rateLimit` rules. Same header/body split and opaque single-reference
-// case as QueryHandlerPattern.
+// input schema, async-generator handler closure, plus optional `access`,
+// `rateLimit`, and `escapeHatch` rules (StreamHandlerDef carries all three
+// at runtime). Same header/body split and opaque single-reference case as
+// QueryHandlerPattern.
 export type StreamHandlerPattern = {
   readonly kind: "streamHandler";
   readonly source: SourceLocation;
   readonly handlerName?: string;
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
-  readonly rateLimit?: RateLimitOption;
+  readonly access?: AccessRule | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.hook(type, target, fn, options?)` — attaches a lifecycle hook
@@ -447,7 +454,7 @@ export type HookPattern = {
   readonly target: string | readonly string[] | { readonly allOf: string };
   readonly fnBody: SourceLocation;
   readonly phase?: HookPhase;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.job(name, options, handler)` — registers a background job, qualified

package/src/engine/feature-ast/render.ts

@@ -436,6 +436,7 @@ function renderStreamHandler(p: StreamHandlerPattern): string {
   lines.push(`  handler: ${reindentBody(p.handlerBody?.raw ?? "", PATTERN_INDENT)},`);
   if (p.access !== undefined) lines.push(`  access: ${renderValue(p.access)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
+  if (p.escapeHatch !== undefined) lines.push(`  escapeHatch: ${renderValue(p.escapeHatch)},`);
   lines.push("});");
   return lines.join("\n");
 }

package/src/engine/feature-ui-extensions.ts

@@ -229,9 +229,9 @@ export function buildUiExtensionsMethods<TName extends string>(
     useExtension(
       extensionNameOrDefinition:
         | string
-        | ({ readonly name: string; readonly entity: NameOrRef } & Record<string, unknown>),
+        | ({ readonly name: string; readonly entity: NameOrRef } & object),
       entityRef?: NameOrRef,
-      options?: Record<string, unknown>,
+      options?: object,
     ): void {
       const [extensionName, resolvedEntityRef, resolvedOptions] =
         typeof extensionNameOrDefinition === "string"
@@ -241,11 +241,12 @@ export function buildUiExtensionsMethods<TName extends string>(
               return [name, entity, rest] as const;
             })();
       const resolvedEntityName = resolveName(resolvedEntityRef);
+      // @cast-boundary engine-bridge — typed per-extension options → erased registration bag
+      const optionsBag = resolvedOptions as Record<string, unknown> | undefined;
       // fw#2914 — cross-cutting escapeHatch convention for hook-context db
-      // access (mirrors r.hook's validation above). Not part of a typed
-      // per-extension options shape: useExtension's bag stays generic, but
-      // this one key is validated for every extension the same way.
-      const escapeHatch = resolvedOptions?.["escapeHatch"];
+      // access (mirrors r.hook's validation above). Validated the same way
+      // for every extension regardless of its typed hook shape.
+      const escapeHatch = optionsBag?.["escapeHatch"];
       if (escapeHatch !== undefined) {
         const reason =
           typeof escapeHatch === "object" && escapeHatch !== null
@@ -261,7 +262,7 @@ export function buildUiExtensionsMethods<TName extends string>(
       state.extensionUsages.push({
         extensionName,
         entityName: resolvedEntityName,
-        options: resolvedOptions,
+        options: optionsBag,
       });
     },
     extensionSelector(extensionName: string, key: { readonly name: string } | string): void {

package/src/engine/index.ts

@@ -98,7 +98,7 @@ export {
 export { declareEscapeHatch } from "./escape-hatch-declaration";
 export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
-export type { KumikoExtensionName } from "./extension-names";
+export type { KumikoExtensionName, TenantResourceExtensionName } from "./extension-names";
 export {
   EXT_DERIVATIVE_OVERLAY_RESOLVER,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
@@ -124,11 +124,18 @@ export type {
   StorageProviderExtensionHooks,
   StorageProviderHookCtx,
 } from "./extensions/storage-provider";
-export type {
-  TenantDataDestroyHook,
-  TenantDataExtensionHooks,
-  TenantDataHookCtx,
+export {
+  isTenantDataExtensionHooks,
+  type TenantDataDestroyHook,
+  type TenantDataExtensionHooks,
+  type TenantDataHookCtx,
 } from "./extensions/tenant-data";
+export {
+  isTenantResourceExtensionHooks,
+  type TenantResourceDestroyHook,
+  type TenantResourceExtensionHooks,
+  type TenantResourceHookCtx,
+} from "./extensions/tenant-resource";
 export type {
   TenantUserModel,
   UserDataDeleteHook,
@@ -136,6 +143,7 @@ export type {
   UserDataExportHook,
   UserDataExportSnippet,
   UserDataExtensionHooks,
+  UserDataExtensionOptions,
   UserDataHookCtx,
   UserDataStorageProvider,
 } from "./extensions/user-data";
@@ -178,10 +186,13 @@ export type {
   FormFieldLabel,
   FormFieldSpec,
   FormInputType,
+  HandlerHeaderUpdate,
   ParseError,
   ParseResult,
   PatternCategory,
   PatternChange,
+  PatternChangeIssue,
+  PatternChangesParseResult,
   PatternFormSchema,
   PatternId,
   RenderFeatureFileInput,
@@ -195,11 +206,13 @@ export {
   groupByCategory,
   PATTERN_LIBRARY,
   parseFeatureFile,
+  parsePatternChanges,
   parseSourceFile,
   removePattern,
   renderFeatureFile,
   renderPattern,
   replacePattern,
+  updatePattern,
   VERSION_HEADER,
 } from "./feature-ast";
 export {
@@ -392,6 +405,8 @@ export type {
   EscapeHatchTarget,
   EscapeHatchUseEvent,
   EventDef,
+  ExtensionOptionsArgs,
+  ExtensionOptionsFor,
   FeatureDefinition,
   FeatureRegistrar,
   FieldAccess,
@@ -419,6 +434,7 @@ export type {
   JsonbFieldDef,
   KumikoEntityTypeMap,
   KumikoEventTypeMap,
+  KumikoExtensionOptionsMap,
   KumikoHandlerPayloadMap,
   KumikoHandlerResultMap,
   LifecycleHookType,

package/src/engine/types/extension-options-map.ts

@@ -0,0 +1 @@
+export type * from "@cosmicdrift/kumiko-types/extension-options-map";

package/src/engine/types/index.ts

@@ -72,6 +72,12 @@ export type {
   KumikoHandlerPayloadMap,
   KumikoHandlerResultMap,
 } from "@cosmicdrift/kumiko-types/event-type-map";
+// Cross-Feature Compile-Time-Type-Map for r.useExtension options — mirrors KumikoEventTypeMap above.
+export type {
+  ExtensionOptionsArgs,
+  ExtensionOptionsFor,
+  KumikoExtensionOptionsMap,
+} from "@cosmicdrift/kumiko-types/extension-options-map";
 export type {
   BootCheckContext,
   BootCheckFn,

package/src/jobs/__tests__/job-retention.integration.test.ts

@@ -0,0 +1,316 @@
+// BullMQ's moveToFinished lua sweeps a queue's WHOLE
+// completed/failed zset whenever any job finishes with keepJobs set, not
+// just the finishing job, and only lazily (on a later finish into the same
+// set). These tests exercise the real sweep against a real Redis, on every
+// enqueue path, plus the runOnBoot marker and the perTenant invariant that
+// keeps the sweep from breaking wrapper-retry child dedup.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { Queue } from "bullmq";
+import { z } from "zod";
+import { createRegistry, defineFeature } from "../../engine";
+import type { AppContext, TenantId } from "../../engine/types";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { sleep, waitFor } from "../../testing";
+import { bootJobIdForJobName, createJobRunner } from "../job-runner";
+
+let testRedis: TestRedis;
+let redisUrl: string;
+
+beforeAll(async () => {
+  testRedis = await createTestRedis();
+  redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+});
+
+afterAll(async () => {
+  await testRedis.cleanup();
+});
+
+function uniquePrefix(tag: string): string {
+  return `kumiko-test-retention-${tag}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+async function purgeQueueKeys(queueNamePrefix: string): Promise<void> {
+  const workerKeys = await testRedis.redis.keys(`bull:${queueNamePrefix}-worker:*`);
+  if (workerKeys.length > 0) await testRedis.redis.del(...workerKeys);
+  const apiKeys = await testRedis.redis.keys(`bull:${queueNamePrefix}-api:*`);
+  if (apiKeys.length > 0) await testRedis.redis.del(...apiKeys);
+}
+
+function rawWorkerQueue(queueNamePrefix: string): Queue {
+  const queue = new Queue(`${queueNamePrefix}-worker`, {
+    connection: { host: testRedis.redis.options.host, port: testRedis.redis.options.port },
+  });
+  // A post-close 'error' here is otherwise unhandled and bun:test attributes
+  // it to whichever test runs next (fw#1805).
+  queue.on("error", () => {});
+  return queue;
+}
+
+describe("bounded job retention (fw#3199)", () => {
+  test("completed jobs from every enqueue path are swept after the age once a later job completes", async () => {
+    const queueNamePrefix = uniquePrefix("completed");
+    const tenants = ["ret-a", "ret-b"] as TenantId[];
+    const completed: Array<{ name: string; jobId: string }> = [];
+
+    const feature = defineFeature("retention", (r) => {
+      const someEvent = r.defineEvent("some-event", z.object({}), { piiFields: "none" });
+      r.job("tick", { trigger: { manual: true } }, async () => {});
+      r.job("onEvent", { trigger: { on: someEvent.name } }, async () => {});
+      r.job("fanout", { trigger: { manual: true }, perTenant: true }, async () => {});
+      r.job("cronJob", { trigger: { cron: "* * * * * *" } }, async () => {});
+      r.job("sweeper", { trigger: { manual: true } }, async () => {});
+    });
+
+    const registry = createRegistry([feature]);
+    const context: AppContext = {};
+    const runner = createJobRunner({
+      registry,
+      context,
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+      getActiveTenantIds: async () => tenants,
+      jobRetention: { completedAgeSec: 1, failedAgeSec: 1 },
+      onJobComplete: (name, jobId) => {
+        completed.push({ name, jobId });
+      },
+    });
+
+    const rawQueue = rawWorkerQueue(queueNamePrefix);
+    try {
+      await runner.start();
+      const tickId = await runner.dispatch("retention:job:tick");
+      await runner.handleEvent("retention:event:some-event", {});
+      const wrapperId = await runner.dispatch("retention:job:fanout");
+
+      await waitFor(() => {
+        expect(completed.some((c) => c.jobId === tickId)).toBe(true);
+        expect(completed.some((c) => c.name === "retention:job:on-event")).toBe(true);
+        expect(completed.filter((c) => c.name === "retention:job:fanout").length).toBe(2);
+        expect(completed.some((c) => c.name === "retention:job:cron-job")).toBe(true);
+      });
+
+      const cronId = completed.find((c) => c.name === "retention:job:cron-job")?.jobId;
+      const eventId = completed.find((c) => c.name === "retention:job:on-event")?.jobId;
+      const childIds = completed
+        .filter((c) => c.name === "retention:job:fanout")
+        .map((c) => c.jobId);
+
+      await sleep(1200);
+
+      await runner.dispatch("retention:job:sweeper");
+      await waitFor(() => {
+        expect(completed.some((c) => c.name === "retention:job:sweeper")).toBe(true);
+      });
+
+      const idsToCheck = [tickId, wrapperId, eventId, cronId, ...childIds].filter(
+        (id): id is string => id !== undefined,
+      );
+      for (const id of idsToCheck) {
+        await waitFor(async () => {
+          expect(await rawQueue.getJob(id)).toBeUndefined();
+        });
+      }
+    } finally {
+      await rawQueue.close();
+      await runner.stop();
+      await purgeQueueKeys(queueNamePrefix);
+    }
+  });
+
+  test("failed jobs are swept after the age once a later failure completes", async () => {
+    const queueNamePrefix = uniquePrefix("failed");
+    const failed: Array<{ name: string; jobId: string }> = [];
+
+    const feature = defineFeature("retentionfail", (r) => {
+      r.job("boom", { trigger: { manual: true } }, async () => {
+        throw new Error("always fails");
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    const context: AppContext = {};
+    const runner = createJobRunner({
+      registry,
+      context,
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+      jobRetention: { completedAgeSec: 1, failedAgeSec: 1 },
+      onJobFailed: (name, jobId) => {
+        failed.push({ name, jobId });
+      },
+    });
+
+    const rawQueue = rawWorkerQueue(queueNamePrefix);
+    try {
+      await runner.start();
+      const firstId = await runner.dispatch("retentionfail:job:boom");
+      await waitFor(() => {
+        expect(failed.some((f) => f.jobId === firstId)).toBe(true);
+      });
+
+      await sleep(1200);
+
+      const secondId = await runner.dispatch("retentionfail:job:boom");
+      await waitFor(() => {
+        expect(failed.some((f) => f.jobId === secondId)).toBe(true);
+      });
+
+      await waitFor(async () => {
+        expect(await rawQueue.getJob(firstId)).toBeUndefined();
+      });
+    } finally {
+      await rawQueue.close();
+      await runner.stop();
+      await purgeQueueKeys(queueNamePrefix);
+    }
+  });
+
+  test("runOnBoot marker survives the retention sweep and still dedupes across restarts", async () => {
+    const queueNamePrefix = uniquePrefix("boot");
+    let bootRuns = 0;
+    let tickRuns = 0;
+
+    const feature = defineFeature("retentionboot", (r) => {
+      r.job("boot", { trigger: { manual: true }, runOnBoot: true }, async () => {
+        bootRuns += 1;
+      });
+      r.job("tick", { trigger: { manual: true } }, async () => {
+        tickRuns += 1;
+      });
+    });
+
+    const registry1 = createRegistry([feature]);
+    const context: AppContext = {};
+    const runner1 = createJobRunner({
+      registry: registry1,
+      context,
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+      jobRetention: { completedAgeSec: 1, failedAgeSec: 1 },
+    });
+
+    const rawQueue = rawWorkerQueue(queueNamePrefix);
+    const bootJobId = bootJobIdForJobName("retentionboot:job:boot");
+    try {
+      await runner1.start();
+      await waitFor(() => {
+        expect(bootRuns).toBe(1);
+      });
+
+      await sleep(1200);
+      await runner1.dispatch("retentionboot:job:tick");
+      await waitFor(() => {
+        expect(tickRuns).toBe(1);
+      });
+
+      // Proves the sweep actually ran — without it this assertion (and the
+      // regression it guards) would pass on the old fixed-job-id dedup too.
+      await waitFor(async () => {
+        expect(await rawQueue.getJob(bootJobId)).toBeUndefined();
+      });
+
+      await runner1.stop();
+
+      const registry2 = createRegistry([feature]);
+      const runner2 = createJobRunner({
+        registry: registry2,
+        context,
+        redisUrl,
+        consumerLane: "worker",
+        queueNamePrefix,
+        jobRetention: { completedAgeSec: 1, failedAgeSec: 1 },
+      });
+      try {
+        await runner2.start();
+        await sleep(300);
+        expect(bootRuns).toBe(1);
+      } finally {
+        await runner2.stop();
+      }
+    } finally {
+      await rawQueue.close();
+      await purgeQueueKeys(queueNamePrefix);
+    }
+  });
+
+  test("createJobRunner throws for a perTenant job whose retry window reaches the completed retention", () => {
+    const feature = defineFeature("retentioninvariant", (r) => {
+      r.job(
+        "risky",
+        {
+          trigger: { manual: true },
+          perTenant: true,
+          retries: 2,
+          backoff: { type: "fixed", delayMs: 1000 },
+        },
+        async () => {},
+      );
+    });
+    const registry = createRegistry([feature]);
+    expect(() =>
+      createJobRunner({
+        registry,
+        context: {},
+        redisUrl,
+        consumerLane: "worker",
+        queueNamePrefix: uniquePrefix("invariant"),
+        jobRetention: { completedAgeSec: 1, failedAgeSec: 1 },
+      }),
+    ).toThrow(/retry window/);
+  });
+
+  test("createJobRunner does not throw for a non-perTenant job with the same retry config", async () => {
+    const feature = defineFeature("retentionnonpertenant", (r) => {
+      r.job(
+        "risky",
+        { trigger: { manual: true }, retries: 2, backoff: { type: "fixed", delayMs: 1000 } },
+        async () => {},
+      );
+    });
+    const registry = createRegistry([feature]);
+    const queueNamePrefix = uniquePrefix("nonpertenant");
+    let ran = false;
+    const runner = createJobRunner({
+      registry,
+      context: {},
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+      jobRetention: { completedAgeSec: 1, failedAgeSec: 1 },
+      onJobComplete: () => {
+        ran = true;
+      },
+    });
+    try {
+      await runner.start();
+      await runner.dispatch("retentionnonpertenant:job:risky");
+      await waitFor(() => {
+        expect(ran).toBe(true);
+      });
+    } finally {
+      await runner.stop();
+      await purgeQueueKeys(queueNamePrefix);
+    }
+  });
+
+  test.each([0, 1.5])("createJobRunner throws for jobRetention.completedAgeSec = %p", (value) => {
+    const feature = defineFeature("retentionbadvalue", (r) => {
+      r.job("noop", { trigger: { manual: true } }, async () => {});
+    });
+    const registry = createRegistry([feature]);
+    expect(() =>
+      createJobRunner({
+        registry,
+        context: {},
+        redisUrl,
+        consumerLane: "worker",
+        queueNamePrefix: uniquePrefix("badvalue"),
+        jobRetention: { completedAgeSec: value },
+      }),
+    ).toThrow();
+  });
+});