@cosmicdrift/kumiko-samples 0.403.0 → 0.404.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.403.0",
+  "version": "0.404.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

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

package/packages/bundled-features/src/audit/feature.ts

@@ -77,7 +77,7 @@ export function createAuditFeature(): FeatureDefinition {
 
       r.job({
         name: "escape-hatch-retention",
-        trigger: { cron: "30 3 * * *" },
+        trigger: { maintenance: true },
         concurrency: "skip",
         // pruneEvents needs a transaction-capable connection, which only unsafeRaw() hands a job.
         escapeHatch: {

package/packages/bundled-features/src/data-retention/feature.ts

@@ -71,7 +71,7 @@ export function createDataRetentionFeature(): FeatureDefinition {
     // retention rules are configured but never enforced.
     r.job({
       name: "retention-cleanup",
-      trigger: { cron: "0 3 * * *" },
+      trigger: { maintenance: true },
       perTenant: true,
       concurrency: "skip",
       escapeHatch: {

package/packages/bundled-features/src/delivery/feature.ts

@@ -197,7 +197,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     if (attemptLogRetentionDays !== undefined) {
       r.job({
         name: DeliveryJobNames.attemptLogRetention,
-        trigger: { cron: "15 3 * * *" },
+        trigger: { maintenance: true },
         concurrency: "skip",
         escapeHatch: { reason: ATTEMPT_LOG_RETENTION_ESCAPE_HATCH_REASON },
         handler: async (_payload, ctx) => {

package/packages/bundled-features/src/feature-toggles/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.404.0",
+    "type": "improvement",
+    "title": "Feature-toggle Redis signal follows KUMIKO_REDIS_PREFIX",
+    "detail": "createRedisToggleSyncSignal takes an optional channelSubscribePattern (default from KUMIKO_REDIS_PREFIX) and ignores messages from other channels, which a prefix-wide subscription delivers."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/feature-toggles/toggle-sync-signal.ts

@@ -4,6 +4,7 @@ import {
   createRedisPubSubSignal,
   type RedisClientOptions,
   redisChannelPrefixFromEnv,
+  redisNamespaceFromEnv,
 } from "@cosmicdrift/kumiko-framework/redis";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type { ToggleSyncSignal } from "./toggle-runtime.ts";
@@ -36,11 +37,12 @@ export function createRedisToggleSyncSignal(
   redisUrl: string,
   clientOptions?: RedisClientOptions,
   channelPrefix: string = redisChannelPrefixFromEnv(),
+  channelSubscribePattern: string | undefined = redisNamespaceFromEnv().channelSubscribePattern,
 ): RedisToggleSyncSignal {
   const toggleSyncChannel = `${channelPrefix}${TOGGLE_SYNC_CHANNEL_NAME}`;
   const signal = createRedisPubSubSignal({
     redisUrl,
-    channelPattern: toggleSyncChannel,
+    channelPattern: channelSubscribePattern ?? toggleSyncChannel,
     label: "feature-toggles",
     ...(clientOptions ? { clientOptions } : {}),
   });
@@ -50,7 +52,9 @@ export function createRedisToggleSyncSignal(
       signal.publish(toggleSyncChannel, { featureName, enabled });
     },
     onMessage(listener) {
-      signal.onMessage((_channel, payload) => {
+      signal.onMessage((channel, payload) => {
+        // skip: a wide subscribe pattern also delivers other features' channels
+        if (channel !== toggleSyncChannel) return;
         if (!isTogglePayload(payload)) {
           // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no ctx.obs.log in a raw PubSubSignal handler.
           console.error(

package/packages/bundled-features/src/form-draft/feature.ts

@@ -43,7 +43,7 @@ function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>):
   r.config({ keys: { retentionDays: formDraftRetentionDaysConfig } });
   r.job({
     name: "cleanup",
-    trigger: { cron: "0 3 * * *" },
+    trigger: { maintenance: true },
     concurrency: "skip",
     escapeHatch: { reason: CLEANUP_ESCAPE_HATCH_REASON },
     handler: (payload, ctx) =>

package/packages/bundled-features/src/inbound-mail-foundation/retention-job.ts

@@ -18,7 +18,7 @@ export function registerInboundMailRetentionJob(r: FeatureRegistrar<"inbound-mai
     "inbound-mail retention runs raw deletes; every statement filters by this run's tenantId";
   r.job({
     name: "inbound-mail-retention",
-    trigger: { cron: "0 3 * * *" },
+    trigger: { maintenance: true },
     perTenant: true,
     concurrency: "skip",
     escapeHatch: { reason: INBOUND_MAIL_RETENTION_REASON },

package/packages/bundled-features/src/jobs/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.404.0",
+    "type": "improvement",
+    "title": "Cleanup jobs run once a day in the maintenance window",
+    "detail": "jobs (stale-run-sweep, hourly before, and retention-cleanup), user-data-rights (export and forget), data-retention, audit escape-hatch-retention, inbound-mail retention, delivery attempt-log-retention and form-draft cleanup use trigger { maintenance: true } instead of 03:00 to 03:30 and hourly crons. Without KUMIKO_MAINTENANCE_WINDOW they all run at 03:00 UTC. A stuck job run is now marked failed at most a day after it crosses the stale timeout."
+  },
   {
     "version": "0.394.0",
     "type": "fix",

package/packages/bundled-features/src/jobs/feature.ts

@@ -43,7 +43,7 @@ export type JobsFeatureOptions = {
   // store_job_run_logs before the daily retention-cleanup job deletes it. Also the age after
   // which a tenant-visible "queued" row counts as lost and is dropped by the stale-run sweep.
   readonly retentionDays?: number;
-  // How long a run can sit at status "running" before the hourly
+  // How long a run can sit at status "running" before the daily
   // stale-run-sweep job marks it "failed" — a process kill mid-run
   // never fires onJobComplete/onJobFailed, so nothing else ever revisits
   // it). Must clear any legitimately long-running job (reindexEntity,
@@ -120,18 +120,17 @@ export function createJobsFeature(options: JobsFeatureOptions = {}): FeatureDefi
     // stores — nothing else purges them.
     r.job(
       "retention-cleanup",
-      { trigger: { cron: "0 3 * * *" }, concurrency: "skip" },
+      { trigger: { maintenance: true }, concurrency: "skip" },
       createRetentionCleanupJob(retentionDays),
     );
 
     // Sweeps store_job_runs for rows stuck at status "running" past the
-    // timeout. Hourly matches the timeout's own granularity —
-    // frequent enough to catch a stuck run soon after it crosses the
-    // threshold, cheap enough that an (almost always empty) result set
-    // doesn't matter.
+    // timeout. Runs in the maintenance window: the timeout is
+    // hours, so a daily pass finds a stuck run at most a day late and a sleeping
+    // app is not woken every hour for it.
     r.job(
       "stale-run-sweep",
-      { trigger: { cron: "0 * * * *" }, concurrency: "skip" },
+      { trigger: { maintenance: true }, concurrency: "skip" },
       createStaleRunSweepJob(staleRunTimeoutHours, retentionDays),
     );
 

package/packages/bundled-features/src/user-data-rights/feature.ts

@@ -600,14 +600,14 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
       type: "gauge",
       unit: "seconds",
       description:
-        "Unix timestamp of the last export storage-cleanup pass that completed. Alert on time() minus this value exceeding the cron interval plus a buffer; the backlog-age gauge alone stays at its last value when the cron stops.",
+        "Unix timestamp of the last export storage-cleanup pass that completed. Alert on time() minus this value exceeding one day plus a buffer; the backlog-age gauge alone stays at its last value when the cron stops.",
     });
 
     // Worker for the asynchronous export pipeline, triggered by a cron job.
     const RUN_EXPORT_JOBS_REASON = "processes pending export jobs across every tenant";
     r.job({
       name: "run-export-jobs",
-      trigger: { cron: "0 3 * * *" },
+      trigger: { maintenance: true },
       concurrency: "skip",
       escapeHatch: { reason: RUN_EXPORT_JOBS_REASON },
       handler: async (_payload, ctx) => {
@@ -705,7 +705,7 @@ export function createUserDataRightsFeature(opts: UserDataRightsOptions = {}): F
     const RUN_FORGET_CLEANUP_REASON = "executes overdue Art.17 forget requests across every tenant";
     r.job({
       name: "run-forget-cleanup",
-      trigger: { cron: "0 3 * * *" },
+      trigger: { maintenance: true },
       concurrency: "skip",
       escapeHatch: { reason: RUN_FORGET_CLEANUP_REASON },
       handler: async (_payload, ctx) => {

package/samples/recipes/lane-routing/README.md

@@ -5,6 +5,7 @@ Pin jobs to deploy lanes (`api` | `worker`) with event-triggered fan-out.
 ## What it shows
 
 - `r.job({ runIn: "worker" })` after an HTTP write
+- `trigger: { maintenance: true }` for a daily housekeeping job in the app's maintenance window (`KUMIKO_MAINTENANCE_WINDOW`)
 - End-to-end verification via `createAllInOneEntrypoint`
 
 ## Source

package/samples/recipes/lane-routing/src/feature.ts

@@ -23,6 +23,7 @@ import { z } from "zod";
 // opaque to the framework.
 export const renderedReceipts: Array<{ customerName: string; amount: number }> = [];
 export const sentConfirmations: Array<{ customerName: string; amount: number }> = [];
+export const pruneRuns: number[] = [];
 
 // The entity declaration secures the qualified-name prefix "orders:write:order:create"
 // for the write handler below and thereby the job trigger on this event.
@@ -100,5 +101,12 @@ export function createLaneRoutingFeature(): FeatureDefinition {
         });
       },
     );
+
+    // Housekeeping: `maintenance` runs once a day in the app's maintenance window
+    // (KUMIKO_MAINTENANCE_WINDOW, UTC, default 03:00) instead of a cron time of its own, so a
+    // sleeping app wakes once a day for all its cleanup jobs.
+    r.job("prune-old-receipts", { trigger: { maintenance: true }, runIn: "worker" }, async () => {
+      pruneRuns.push(Date.now());
+    });
   });
 }