@cosmicdrift/kumiko-bundled-features 0.353.0 → 0.354.0

package/dist/feature-toggles/toggle-runtime.js

@@ -1,6 +1,10 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { computeEffectiveFeatures, } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { createDefaultCacheSyncBus, } from "@cosmicdrift/kumiko-framework/redis";
 import { globalFeatureStateTable } from "./global-feature-state-table.js";
+import { createCacheSyncToggleSignal } from "./toggle-sync-signal.js";
+const log = createFallbackLogger("kumiko:feature-toggles");
 // Holds the current global-override snapshot in memory and exposes a
 // synchronous reader — the dispatcher's feature-gate calls it on every
 // handler invocation, so this must not do I/O on the hot path. The
@@ -16,14 +20,16 @@ export class GlobalFeatureToggleRuntime {
     db;
     registry;
     syncSignal;
+    ownedBus;
     snapshot = new Map();
     // Flips applied while a snapshot load is in flight. The load's SELECT may have
     // started before the flip committed, so its rows can be older than these.
     appliedDuringLoad;
-    constructor(db, registry, syncSignal) {
+    constructor(db, registry, syncSignal, ownedBus) {
         this.db = db;
         this.registry = registry;
         this.syncSignal = syncSignal;
+        this.ownedBus = ownedBus;
         // Every process, including the one that calls broadcastToggle, learns
         // of a flip through this same subscription — mirrors the SSE broker's
         // publish-then-echo-to-self pattern instead of a separate local-apply
@@ -31,6 +37,15 @@ export class GlobalFeatureToggleRuntime {
         this.syncSignal?.onMessage((featureName, enabled) => {
             this.apply(featureName, enabled);
         });
+        this.syncSignal?.onResync?.(() => {
+            this.refresh().catch((err) => {
+                log.error("snapshot reload after sync reconnect failed", { err });
+            });
+        });
+    }
+    // Only the runtime built by createFeatureToggleRuntime without an explicit signal owns one.
+    async close() {
+        await this.ownedBus?.close();
     }
     async initialize() {
         const pendingFlips = new Map();
@@ -99,11 +114,20 @@ export class GlobalFeatureToggleRuntime {
         return computeEffectiveFeatures(this.registry, reader);
     };
 }
-// Factory for app-boot wiring: instantiate, initialize, return both the
-// runtime (for the set-handler to refresh) and the callback (for
-// createDispatcher's effectiveFeatures option).
+// Factory for app-boot wiring: instantiate, initialize, return the runtime (for the
+// set-handler to refresh; its effectiveFeatures feeds createDispatcher). Without an explicit
+// syncSignal the runtime builds one on the framework cache-sync bus: Redis-backed when
+// REDIS_URL is set, process-local otherwise. close() releases a bus it created.
 export async function createFeatureToggleRuntime(db, registry, syncSignal) {
-    const runtime = new GlobalFeatureToggleRuntime(db, registry, syncSignal);
-    await runtime.initialize();
+    const ownedBus = syncSignal ? undefined : createDefaultCacheSyncBus();
+    const signal = syncSignal ?? (ownedBus ? createCacheSyncToggleSignal(ownedBus) : undefined);
+    const runtime = new GlobalFeatureToggleRuntime(db, registry, signal, ownedBus);
+    try {
+        await runtime.initialize();
+    }
+    catch (err) {
+        await runtime.close();
+        throw err;
+    }
     return runtime;
 }

package/dist/feature-toggles/toggle-sync-signal.d.ts

@@ -1,6 +1,7 @@
-import { type RedisClientOptions } from "@cosmicdrift/kumiko-framework/redis";
+import { type CacheSyncBus, type RedisClientOptions } from "@cosmicdrift/kumiko-framework/redis";
 import type { ToggleSyncSignal } from "./toggle-runtime.js";
 export type RedisToggleSyncSignal = ToggleSyncSignal & {
     close(): Promise<void>;
 };
-export declare function createRedisToggleSyncSignal(redisUrl: string, clientOptions?: RedisClientOptions): RedisToggleSyncSignal;
+export declare function createRedisToggleSyncSignal(redisUrl: string, clientOptions?: RedisClientOptions, channelPrefix?: string): RedisToggleSyncSignal;
+export declare function createCacheSyncToggleSignal(bus: CacheSyncBus): ToggleSyncSignal;

package/dist/feature-toggles/toggle-sync-signal.js

@@ -1,7 +1,7 @@
-import { createRedisPubSubSignal, } from "@cosmicdrift/kumiko-framework/redis";
+import { CACHE_SYNC_TOPICS, createRedisPubSubSignal, redisChannelPrefixFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
 // Single fixed channel — unlike the SSE broker there's no per-tenant/
 // per-user variance to multiplex, every toggle flip is global.
-const TOGGLE_SYNC_CHANNEL = "kumiko:feature-toggles:cache-sync";
+const TOGGLE_SYNC_CHANNEL_NAME = "kumiko:feature-toggles:cache-sync";
 function isTogglePayload(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -11,26 +11,25 @@ function isTogglePayload(value) {
 // fw#2625: gives toggle-cache-sync the cross-replica transport its shared
 // dispatcher cursor needs — without this, only the one process that won
 // the shared cursor's toggle-set event would ever learn about a flip.
-// Same REDIS_URL-gated assumption as the SSE broker: a deployment with
-// replicas > 1 is expected to set REDIS_URL, so app-boot code should build
-// this only when REDIS_URL is present and pass it into
-// createFeatureToggleRuntime.
-export function createRedisToggleSyncSignal(redisUrl, clientOptions) {
+// Standalone Redis transport for callers that want their own connections;
+// createFeatureToggleRuntime builds a cache-sync-bus signal by default.
+export function createRedisToggleSyncSignal(redisUrl, clientOptions, channelPrefix = redisChannelPrefixFromEnv()) {
+    const toggleSyncChannel = `${channelPrefix}${TOGGLE_SYNC_CHANNEL_NAME}`;
     const signal = createRedisPubSubSignal({
         redisUrl,
-        channelPattern: TOGGLE_SYNC_CHANNEL,
+        channelPattern: toggleSyncChannel,
         label: "feature-toggles",
         ...(clientOptions ? { clientOptions } : {}),
     });
     return {
         publish(featureName, enabled) {
-            signal.publish(TOGGLE_SYNC_CHANNEL, { featureName, enabled });
+            signal.publish(toggleSyncChannel, { featureName, enabled });
         },
         onMessage(listener) {
             signal.onMessage((_channel, payload) => {
                 if (!isTogglePayload(payload)) {
                     // biome-ignore lint/suspicious/noConsole: ops-visible fallback — no ctx.log in a raw PubSubSignal handler.
-                    console.error(`[kumiko:feature-toggles] dropping malformed cache-sync message on "${TOGGLE_SYNC_CHANNEL}"`);
+                    console.error(`[kumiko:feature-toggles] dropping malformed cache-sync message on "${toggleSyncChannel}"`);
                     // skip: malformed message already logged above, nothing to apply
                     return;
                 }
@@ -40,3 +39,23 @@ export function createRedisToggleSyncSignal(redisUrl, clientOptions) {
         close: signal.close,
     };
 }
+// Reuses the framework cache-sync bus (local without REDIS_URL, Redis-backed with it) so
+// toggles need no Pub/Sub wiring of their own. The bus applies a publish locally first.
+export function createCacheSyncToggleSignal(bus) {
+    return {
+        publish(featureName, enabled) {
+            bus.publish(CACHE_SYNC_TOPICS.featureToggle, { featureName, enabled });
+        },
+        onMessage(listener) {
+            bus.subscribe(CACHE_SYNC_TOPICS.featureToggle, (payload) => {
+                // skip: foreign or malformed payload on the topic
+                if (!isTogglePayload(payload))
+                    return;
+                listener(payload.featureName, payload.enabled);
+            });
+        },
+        onResync(listener) {
+            bus.onResync(listener);
+        },
+    };
+}

package/dist/file-derivatives/handlers/public-variant.query.d.ts

@@ -1,6 +1,7 @@
 import { EXT_DERIVATIVE_PUBLIC_PREDICATE, type HandlerContext, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 export type DerivativePublicPredicateArgs = {
+    readonly fileRefId: string;
     readonly entityId: string;
     readonly tenantId: TenantId;
     readonly fieldName: string;

package/dist/file-derivatives/handlers/public-variant.query.js

@@ -78,7 +78,13 @@ export const publicVariantQuery = defineQueryHandler({
         if (!isDerivativePublicPredicatePlugin(usage.options)) {
             throw new Error(`file-derivatives: "${usage.entityName}" registered ${EXT_DERIVATIVE_PUBLIC_PREDICATE} without an isPublic(args, ctx) — extension options must be a DerivativePublicPredicatePlugin.`);
         }
-        const isPublic = await usage.options.isPublic({ entityId, tenantId: ctx.user.tenantId, fieldName, variant: query.payload.variant }, ctx);
+        const isPublic = await usage.options.isPublic({
+            fileRefId: query.payload.fileRefId,
+            entityId,
+            tenantId: ctx.user.tenantId,
+            fieldName,
+            variant: query.payload.variant,
+        }, ctx);
         if (!isPublic)
             return null;
         // ctx.files/ctx.derivatives are optional on HandlerContext (only wired

package/dist/files-tenant-data/handlers/sweep-orphaned-derivatives.job.js

@@ -99,6 +99,11 @@ export async function sweepOrphanedDerivativesJob(rawPayload, ctx, db) {
         const owners = await selectMany(db, fileRefsTable, { tenantId: candidate.tenantId, storageKey: candidate.originalKey }, { limit: 1 });
         if (owners.length > 0)
             return "skipped";
+        // Binaries written through ctx.files.ref(key) (and their derive()d
+        // variants) never get a fileRef row; an original still sitting in storage
+        // means the derivative is not an orphan.
+        if (await candidate.provider.exists(candidate.originalKey))
+            return "skipped";
         if (dryRun) {
             dryRunWouldDelete++;
             return "skipped";

package/dist/files-tenant-data/hooks.js

@@ -49,11 +49,13 @@ import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, parseTenantId, } from "@cosmicdrift/kumiko-framework/engine";
 import { assertSafeStorageKey, fileRefEntity, fileRefsTable, storageKeyStemPrefix, tenantStoragePrefixes, } from "@cosmicdrift/kumiko-framework/files";
+import { runChunkedMigration } from "../shared/index.js";
 const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
 // Existence-check batch size for fileRefStorageDestroyHook's survivor lookup
 // — bounds each query instead of one `storage_key = ANY(...)` per listed key,
 // or a single unbounded array for a tenant with a huge prefix.
 const SURVIVOR_CHECK_BATCH_SIZE = 500;
+const DESTROY_CHUNK_SIZE = 500;
 function chunk(items, size) {
     const chunks = [];
     for (let i = 0; i < items.length; i += size)
@@ -63,25 +65,43 @@ function chunk(items, size) {
 function isUnderOwnPrefix(storageKey, prefixes) {
     return prefixes.some((prefix) => storageKey.startsWith(prefix));
 }
+function toDestroyHookResult(result, failureMessage) {
+    // A failure on the last item ends the run as "done" (nothing left to batch),
+    // so the failed count, not the stop reason, decides fail-closed.
+    if (result.failed > 0) {
+        throw new Error(failureMessage() ?? "files-tenant-data: destroy chunk failed");
+    }
+    return { done: result.stoppedReason === "done", processed: result.migrated };
+}
 export const fileRefTenantDestroyHook = async (ctx) => {
-    const rows = await ctx.db.selectMany(fileRefsTable, {
-        tenantId: ctx.tenantId,
-    });
     const ownPrefixes = tenantStoragePrefixes(ctx.tenantId);
     const user = createSystemUser(ctx.tenantId);
-    for (const row of rows) {
-        if (!isUnderOwnPrefix(row.storageKey, ownPrefixes)) {
-            await deleteHandedOverBinary(ctx, row.storageKey);
-        }
-        const result = await crud.forget({ id: row.id }, user, ctx.db);
-        // Executor writes return {isSuccess:false} instead of throwing — a
-        // discarded result would report this destroy stage "succeeded" while the
-        // row (and its PII fileName) survives. Throw so the pipeline's
-        // retry/abandon handling sees it.
-        if (!result.isSuccess) {
-            throw new Error(`files-tenant-data: failed to forget fileRef ${row.id} for tenant ${ctx.tenantId}: ${result.error.message}`);
-        }
-    }
+    let firstFailure;
+    // Converges without a cursor: forget() hard-deletes, so each batch query
+    // returns the next rows.
+    const result = await runChunkedMigration({
+        nextBatch: () => ctx.db.selectMany(fileRefsTable, { tenantId: ctx.tenantId }, { limit: DESTROY_CHUNK_SIZE }),
+        migrateRow: async (row) => {
+            if (!isUnderOwnPrefix(row.storageKey, ownPrefixes)) {
+                await deleteHandedOverBinary(ctx, row.storageKey);
+            }
+            const forgotten = await crud.forget({ id: row.id }, user, ctx.db);
+            // Executor writes return {isSuccess:false} instead of throwing — a
+            // discarded result would report this destroy stage "succeeded" while the
+            // row (and its PII fileName) survives. Throw so the pipeline's
+            // retry/abandon handling sees it.
+            if (!forgotten.isSuccess) {
+                throw new Error(`files-tenant-data: failed to forget fileRef ${row.id} for tenant ${ctx.tenantId}: ${forgotten.error.message}`);
+            }
+            return "migrated";
+        },
+        maxFailures: 1,
+        deadlineAt: ctx.deadlineAt ?? Number.POSITIVE_INFINITY,
+        onRowError: (_row, err) => {
+            firstFailure = err instanceof Error ? err.message : String(err);
+        },
+    });
+    return toDestroyHookResult(result, () => firstFailure);
 };
 // The bytes live under the tenant that uploaded them (`<tenantId>/…` or
 // `exports/<tenantId>/…`), so with per-tenant storage config that tenant's
@@ -140,16 +160,32 @@ export const fileRefStorageDestroyHook = async (tenantId, ctx) => {
     // it and retries up to the stage's attempt cap before abandoning the destroy
     // (list+delete are idempotent, so a retry converges rather than
     // double-deleting or erroring on a missing key).
+    let processed = 0;
     for (const prefix of tenantStoragePrefixes(tenantId)) {
         const keys = await provider.list(prefix);
         const keptStemPrefixes = await survivorStemPrefixes(ctx.db, keys);
-        for (const key of keys) {
-            if (keptStemPrefixes.some((stemPrefix) => key.startsWith(stemPrefix)))
-                continue;
-            assertSafeStorageKey(key);
-            await provider.delete(key);
-        }
+        const deletableKeys = keys.filter((key) => !keptStemPrefixes.some((stemPrefix) => key.startsWith(stemPrefix)));
+        const pending = [...deletableKeys];
+        let firstFailure;
+        const result = await runChunkedMigration({
+            nextBatch: async () => pending.splice(0, DESTROY_CHUNK_SIZE),
+            migrateRow: async (key) => {
+                assertSafeStorageKey(key);
+                await provider.delete(key);
+                return "migrated";
+            },
+            maxFailures: 1,
+            deadlineAt: ctx.deadlineAt ?? Number.POSITIVE_INFINITY,
+            onRowError: (_key, err) => {
+                firstFailure = err instanceof Error ? err.message : String(err);
+            },
+        });
+        const hookResult = toDestroyHookResult(result, () => firstFailure);
+        processed += result.migrated;
+        if (!hookResult.done)
+            return { done: false, processed };
     }
+    return { done: true, processed };
 };
 // Any listed key that is itself a surviving row's exact storageKey means a
 // foreign tenant still owns it (see header comment) — its stem prefix then

package/dist/folders/handlers/delete-folder.write.js

@@ -1,5 +1,6 @@
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
+import { hostRowIsGone } from "../../shared/index.js";
 import { DEFAULT_FOLDER_ACCESS } from "../constants.js";
 import { folderAssignmentExecutor, folderExecutor } from "../executor.js";
 const deleteFolderPayloadSchema = z.object({ id: z.uuid() });
@@ -10,18 +11,44 @@ const deleteFolderPayloadSchema = z.object({ id: z.uuid() });
 // see 658/1). Block server-side instead: this is the same "referential
 // integrity has no FK here" reasoning set-folder.write.ts already applies to
 // folderId on assignment-creation.
+//
+// Assignments whose host is gone (hard-deleted, soft-deleted or unregistered)
+// are cleaned up here instead of blocking forever: clear-folder can't reach
+// them (it requires a visible host). A host-delete hook would break restore,
+// so the cleanup runs lazily at folder:delete.
+const ASSIGNMENT_PAGE_SIZE = 200;
 export function createDeleteFolderHandler(access = DEFAULT_FOLDER_ACCESS) {
     return {
         name: "folder:delete",
         schema: deleteFolderPayloadSchema,
         access,
-        description: "Deletes a folder from the tenant catalog and refuses while any entity is still filed in it; use it once that folder's contents have been unfiled or moved elsewhere.",
+        description: "Deletes a folder from the tenant catalog and refuses while any live entity is still filed in it (assignments of deleted hosts are cleaned up); use it once that folder's contents have been unfiled or moved elsewhere.",
         agent: { risk: "high" },
         handler: async (event, ctx) => {
             const payload = event.payload; // @cast-boundary engine-payload
-            const assigned = await folderAssignmentExecutor.list({ filter: { field: "folderId", op: "eq", value: payload.id }, limit: 1 }, event.user, ctx.db);
-            if (assigned.rows.length > 0) {
-                return writeFailure(new UnprocessableError("folder_has_assignments", { details: { folderId: payload.id } }));
+            const orphanAssignmentIds = [];
+            let cursor;
+            do {
+                const page = await folderAssignmentExecutor.list({
+                    filter: { field: "folderId", op: "eq", value: payload.id },
+                    limit: ASSIGNMENT_PAGE_SIZE,
+                    cursor,
+                }, event.user, ctx.db);
+                for (const row of page.rows) {
+                    const gone = await hostRowIsGone(ctx.registry, String(row["entityType"]), String(row["entityId"]), ctx.db);
+                    if (!gone) {
+                        return writeFailure(new UnprocessableError("folder_has_assignments", {
+                            details: { folderId: payload.id },
+                        }));
+                    }
+                    orphanAssignmentIds.push(String(row["id"]));
+                }
+                cursor = page.nextCursor ?? undefined;
+            } while (cursor !== undefined);
+            for (const id of orphanAssignmentIds) {
+                const removed = await folderAssignmentExecutor.delete({ id }, event.user, ctx.db);
+                if (!removed.isSuccess)
+                    return removed;
             }
             return folderExecutor.delete({ id: payload.id }, event.user, ctx.db);
         },

package/dist/foundation-shared/index.d.ts

@@ -1,3 +1,3 @@
 export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers.js";
 export { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
-export { BlockedHostError, HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, type MailConnectTarget, type MailHostGuardOptions, readAllowedPrivateMailHostsFromEnv, resolveMailConnectTarget, } from "./mail-host-policy.js";
+export { BlockedHostError, HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, type MailConnectTarget, type MailHostGuardOptions, mailAllowedPrivateHostsEnvSchema, readAllowedPrivateMailHostsFromEnv, resolveMailConnectTarget, } from "./mail-host-policy.js";

package/dist/foundation-shared/index.js

@@ -2,4 +2,4 @@
 // Foundation packages (ai-foundation, mail-foundation, file-foundation).
 export { requireDefined, requireNonEmpty, requireSecretSet } from "./config-helpers.js";
 export { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
-export { BlockedHostError, HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, readAllowedPrivateMailHostsFromEnv, resolveMailConnectTarget, } from "./mail-host-policy.js";
+export { BlockedHostError, HostResolutionError, MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, mailAllowedPrivateHostsEnvSchema, readAllowedPrivateMailHostsFromEnv, resolveMailConnectTarget, } from "./mail-host-policy.js";

package/dist/foundation-shared/mail-host-policy.d.ts

@@ -1,5 +1,9 @@
 import type { lookup } from "node:dns/promises";
+import * as z from "zod";
 export declare const MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS";
+export declare const mailAllowedPrivateHostsEnvSchema: z.ZodObject<{
+    KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare function readAllowedPrivateMailHostsFromEnv(env?: Readonly<Record<string, string | undefined>>): readonly string[];
 export type MailHostGuardOptions = {
     readonly allowedPrivateMailHosts?: readonly string[];

package/dist/foundation-shared/mail-host-policy.js

@@ -10,14 +10,23 @@
 // internal relay or a dev/test server (mailpit, greenmail) — deliberately
 // an operator env var (KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, read via
 // readAllowedPrivateMailHostsFromEnv), never a tenant-config key, so a
-// tenant can never grant themselves the bypass. Shared by both features
-// since a deploy commonly mounts both; declared once in mail-transport-
-// smtp's envSchema (see its feature.ts) to avoid the framework's env-var-
-// conflict check tripping when both features are mounted together.
+// tenant can never grant themselves the bypass. Both features register the
+// shared mailAllowedPrivateHostsEnvSchema below.
 import { isIP } from "node:net";
 import { resolvePublicHostname } from "@cosmicdrift/kumiko-framework/http";
+import * as z from "zod";
 import { isHostAllowlisted, readHostAllowlistFromEnv } from "./host-allowlist.js";
 export const MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR = "KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS";
+// One schema instance, registered by every feature that reads the variable:
+// composeEnvSchema accepts the same field instance from several features, so
+// an app mounting only one of them still gets the variable validated and
+// documented.
+export const mailAllowedPrivateHostsEnvSchema = z.object({
+    [MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR]: z
+        .string()
+        .optional()
+        .describe("Comma-separated operator allowlist of private/internal hosts (e.g. a local mailpit/greenmail dev server) that bypass the public-address check for SMTP and IMAP host config. Shared by mail-transport-smtp and inbound-provider-imap — never a tenant-config value."),
+});
 export function readAllowedPrivateMailHostsFromEnv(env = process.env) {
     return readHostAllowlistFromEnv(MAIL_ALLOWED_PRIVATE_HOSTS_ENV_VAR, env);
 }

package/dist/inbound-provider-imap/feature.js

@@ -22,6 +22,7 @@
 // Credentials: JSON-Dokument im per-Account-Secret-Slot
 // (credential-document.ts) — kein Tenant-Config, weil mehrere Accounts
 // pro Tenant verschiedene Hosts haben.
+import { mailAllowedPrivateHostsEnvSchema } from "@cosmicdrift/kumiko-bundled-features/foundation-shared";
 import { INBOUND_MAIL_PROVIDER_EXTENSION, InboundAuthError, inboundCredentialSecretKey, } from "@cosmicdrift/kumiko-bundled-features/inbound-mail-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
@@ -225,5 +226,6 @@ export const inboundProviderImapFeature = defineFeature(FEATURE_NAME, (r) => {
     });
     r.requires("inbound-mail-foundation");
     r.requires("secrets");
+    r.envSchema(mailAllowedPrivateHostsEnvSchema);
     r.useExtension(INBOUND_MAIL_PROVIDER_EXTENSION, IMAP_PROVIDER_KEY, imapInboundMailPlugin);
 });

package/dist/inbound-provider-imap/imap-client.js

@@ -21,10 +21,9 @@ const IMAP_HOST_UNREACHABLE_MESSAGE = "IMAP host is not reachable or not allowed
 // =============================================================================
 // Operator escape hatch for an internal relay or a dev/test IMAP server
 // (greenmail): KUMIKO_MAIL_ALLOWED_PRIVATE_HOSTS, the same operator env
-// var mail-transport-smtp declares (see its envSchema — composeEnvSchema
-// rejects two features declaring the same key, so this feature reads it
-// without redeclaring it), never a tenant-config value, so a tenant can
-// never grant themselves the private-host bypass.
+// var mail-transport-smtp registers (both share one schema instance, see
+// foundation-shared), never a tenant-config value, so a tenant can never
+// grant themselves the private-host bypass.
 //
 // mailHostLookup is a test-only DNS seam — production leaves it undefined,
 // so resolveMailConnectTarget uses the real resolver. Module-global state:

package/dist/jobs/constants.d.ts

@@ -8,6 +8,7 @@ export declare const JobQueries: {
     readonly details: "jobs:query:details";
     readonly catalog: "jobs:query:catalog";
     readonly failures: "jobs:query:failures";
+    readonly tenantRuns: "jobs:query:tenant-runs";
 };
 export declare const JobErrors: {
     readonly unknownJob: "unknown_job";

package/dist/jobs/constants.js

@@ -12,6 +12,7 @@ export const JobQueries = {
     details: "jobs:query:details",
     catalog: "jobs:query:catalog",
     failures: "jobs:query:failures",
+    tenantRuns: "jobs:query:tenant-runs",
 };
 // Error codes
 export const JobErrors = {

package/dist/jobs/db/queries/retention.d.ts

@@ -3,5 +3,6 @@ export type JobRunRetentionResult = {
     readonly runsDeleted: number;
     readonly logsDeleted: number;
     readonly tenantFailuresDeleted: number;
+    readonly tenantRunsDeleted: number;
 };
 export declare function deleteStaleJobRuns(db: DbConnection, retentionDays: number): Promise<JobRunRetentionResult>;

package/dist/jobs/db/queries/retention.js

@@ -12,6 +12,7 @@
 import { deleteManyBatched } from "@cosmicdrift/kumiko-framework/bun-db";
 import { jobRunLogsTable, jobRunsTable } from "../../job-run-table.js";
 import { tenantJobFailuresTable } from "../../tenant-job-failure-table.js";
+import { tenantJobRunsTable } from "../../tenant-job-run-table.js";
 const RETENTION_DELETE_BATCH_SIZE = 500;
 export async function deleteStaleJobRuns(db, retentionDays) {
     const cutoff = Temporal.Now.instant().subtract({ hours: retentionDays * 24 });
@@ -21,9 +22,13 @@ export async function deleteStaleJobRuns(db, retentionDays) {
     // they point at is gone by now, and a job whose subject never ran again
     // would otherwise keep its record forever.
     const tenantFailuresResult = await deleteManyBatched(db, tenantJobFailuresTable, { failedAt: { lt: cutoff } }, { limit: RETENTION_DELETE_BATCH_SIZE });
+    // Only finished rows: active ones are the stale sweep's business, and a
+    // still-running job older than the window must not vanish from the tenant.
+    const tenantRunsResult = await deleteManyBatched(db, tenantJobRunsTable, { status: { in: ["completed", "failed"] }, updatedAt: { lt: cutoff } }, { limit: RETENTION_DELETE_BATCH_SIZE });
     return {
         runsDeleted: runsResult.deleted,
         logsDeleted: logsResult.deleted,
         tenantFailuresDeleted: tenantFailuresResult.deleted,
+        tenantRunsDeleted: tenantRunsResult.deleted,
     };
 }

package/dist/jobs/db/queries/stale-run-sweep.d.ts

@@ -2,5 +2,7 @@ import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 export declare const STALE_JOB_RUN_ERROR = "job run exceeded the stale-run timeout without a completion signal (likely a crashed worker process)";
 export type StaleRunSweepResult = {
     readonly runsMarkedFailed: number;
+    readonly tenantRunsMarkedFailed: number;
+    readonly tenantQueuedDropped: number;
 };
 export declare function markStaleJobRunsFailed(db: DbConnection, timeoutHours: number): Promise<StaleRunSweepResult>;

package/dist/jobs/db/queries/stale-run-sweep.js

@@ -11,11 +11,13 @@
 // schema/migration change, no web filter-dropdown/status-enum update, and
 // the run becomes retriable via the existing jobs:write:retry gate
 // (retry.write.ts only allows retry from "failed").
-import { selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { deleteManyBatched, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { mapWithConcurrency } from "../../../shared/index.js";
 import { encryptFailureError } from "../../job-run-logger.js";
 import { jobRunsTable } from "../../job-run-table.js";
+import { tenantJobRunsTable } from "../../tenant-job-run-table.js";
 const KMS_POOL_CONCURRENCY = 4;
+const STALE_DELETE_BATCH_SIZE = 500;
 export const STALE_JOB_RUN_ERROR = "job run exceeded the stale-run timeout without a completion signal (likely a crashed worker process)";
 export async function markStaleJobRunsFailed(db, timeoutHours) {
     const cutoff = Temporal.Now.instant().subtract({ hours: timeoutHours });
@@ -57,5 +59,14 @@ export async function markStaleJobRunsFailed(db, timeoutHours) {
         return updated.length;
     });
     const runsMarkedFailed = updatedPerSubject.reduce((sum, count) => sum + count, 0);
-    return { runsMarkedFailed };
+    // Tenant-visible run state follows the same clock: a running row whose
+    // worker died is a failure, a queued row that never started (job lost from
+    // Redis, enqueue hook without a run) would otherwise show "waiting" forever.
+    const tenantRunsFailed = await updateMany(db, tenantJobRunsTable, { status: "failed", finishedAt: now, updatedAt: now }, { status: "running", startedAt: { lt: cutoff } });
+    const tenantQueuedStale = await deleteManyBatched(db, tenantJobRunsTable, { status: "queued", updatedAt: { lt: cutoff } }, { limit: STALE_DELETE_BATCH_SIZE });
+    return {
+        runsMarkedFailed,
+        tenantRunsMarkedFailed: tenantRunsFailed.length,
+        tenantQueuedDropped: tenantQueuedStale.deleted,
+    };
 }

package/dist/jobs/feature.js

@@ -9,15 +9,17 @@ import { createRetentionCleanupJob, DEFAULT_JOB_RUN_RETENTION_DAYS, } from "./ha
 import { retryWrite } from "./handlers/retry.write.js";
 import { createStaleRunSweepJob, DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS, } from "./handlers/stale-run-sweep.job.js";
 import { tenantFailuresQuery } from "./handlers/tenant-failures.query.js";
+import { tenantRunsQuery } from "./handlers/tenant-runs.query.js";
 import { triggerWrite } from "./handlers/trigger.write.js";
 import { JOBS_I18N } from "./i18n.js";
 import { jobRunLogsTableMeta, jobRunsTableMeta } from "./job-run-table.js";
 import { tenantJobFailuresTableMeta } from "./tenant-job-failure-table.js";
+import { tenantJobRunsTableMeta } from "./tenant-job-run-table.js";
 export function createJobsFeature(options = {}) {
     const retentionDays = options.retentionDays ?? DEFAULT_JOB_RUN_RETENTION_DAYS;
     const staleRunTimeoutHours = options.staleRunTimeoutHours ?? DEFAULT_JOB_RUN_STALE_TIMEOUT_HOURS;
     return defineFeature("jobs", (r) => {
-        r.describe("Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079).");
+        r.describe("Persistence and operator tooling for background jobs registered via `r.job(...)`. Every job execution writes directly into `store_job_runs` (current status + duration) and `store_job_run_logs` (per-line log rows) from the BullMQ callbacks — no event stream in between (#2243). A daily `retention-cleanup` job deletes runs (and their logs) older than `retentionDays`; an hourly `stale-run-sweep` job marks runs stuck at status `running` past `staleRunTimeoutHours` as `failed` (#2246 — a crashed worker never fires the completion callback, so nothing else ever revisits the row). Exposes `jobs:write:trigger` (manual run) and `jobs:write:retry` (operator retry of a failed run), plus `jobs:query:list`, `jobs:query:details`, and `jobs:query:catalog` (manual jobs) for the operator UI. A job that declares `tenantVisibleFailure` also records its last failed attempt per tenant and subject in `store_tenant_job_failures`, which the tenant itself reads through `jobs:query:failures` — a translation key only, never the provider's message (fw#3079). A job that declares `tenantVisibleRun` also keeps its run state per tenant and subject in `store_tenant_job_runs` (queued, running, plus the latest completed or failed run, no payload, error text or logs), which the tenant reads through `jobs:query:tenant-runs` (fw#3616); the stale-run sweep fails its stuck `running` rows and drops its stuck `queued` rows.");
         r.uiHints({
             displayLabel: "Jobs · Audit & Operator UI",
             category: "operations",
@@ -38,6 +40,9 @@ export function createJobsFeature(options = {}) {
         r.storeTable(tenantJobFailuresTableMeta, {
             reason: "direct_write.tenant_job_failures",
         });
+        r.storeTable(tenantJobRunsTableMeta, {
+            reason: "direct_write.tenant_job_runs",
+        });
         // Framework-provided rebuild job — available whenever `jobs` is composed; enqueueProjectionRebuild dispatches it.
         r.job("projectionRebuild", { trigger: { manual: true }, concurrency: "skip", schema: projectionRebuildPayloadSchema }, projectionRebuildJob);
         // Retroactive search backfill (#1206/#1215) — manual + perTenant, so one
@@ -68,6 +73,7 @@ export function createJobsFeature(options = {}) {
             detail: r.queryHandler(detailQuery),
             catalog: r.queryHandler(catalogQuery),
             failures: r.queryHandler(tenantFailuresQuery),
+            tenantRuns: r.queryHandler(tenantRunsQuery),
         };
         const systemAdminAccess = { roles: ["SystemAdmin"] };
         r.translations({ keys: JOBS_I18N });

package/dist/jobs/handlers/list.query.js

@@ -56,7 +56,7 @@ export const listQuery = defineQueryHandler({
             .optional(),
         sort: z.enum(["jobName", "status", "startedAt", "duration"]).optional(),
         sortDirection: z.enum(["asc", "desc"]).optional(),
-        limit: z.number().optional(),
+        limit: z.number().int().min(1).optional(),
         cursor: z.string().optional(),
         totalCount: z.boolean().optional(),
     }),

package/dist/jobs/handlers/tenant-failures.query.js

@@ -26,7 +26,7 @@ export const tenantFailuresQuery = defineQueryHandler({
     schema: z.object({
         jobName: z.string().optional(),
         subject: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
-        limit: z.number().min(1).max(200).optional(),
+        limit: z.number().int().min(1).max(200).optional(),
     }),
     // Every membership rank: a failure record carries a job name and a
     // translation key, nothing a team member of the tenant may not see.

package/dist/jobs/handlers/tenant-runs.query.d.ts

@@ -0,0 +1,17 @@
+import * as z from "zod";
+import { type TenantJobRunStatus } from "../tenant-job-run-table.js";
+export declare const tenantRunsQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"tenant-runs", z.ZodObject<{
+    jobName: z.ZodOptional<z.ZodString>;
+    subject: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, {
+    rows: {
+        jobName: string;
+        subject: Record<string, unknown> | null;
+        status: TenantJobRunStatus;
+        queuedAt: Temporal.Instant | null;
+        startedAt: Temporal.Instant | null;
+        finishedAt: Temporal.Instant | null;
+    }[];
+    nextCursor: null;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;