@cosmicdrift/kumiko-framework 0.234.0 → 0.235.0

package/src/engine/build-config-feature-schema.ts

@@ -24,8 +24,8 @@ import {
   createTextField,
 } from "./factories";
 import { isKebabSegment } from "./qualified-name";
-import type { ConfigKeyDefinition } from "./types/config";
-import type { Registry } from "./types/feature";
+import type { ConfigKeyDefinition, TranslationKeys } from "./types/config";
+import type { Registry, SecretKeyDefinition } from "./types/feature";
 import type { FieldDefinition } from "./types/fields";
 import type { AccessRule } from "./types/handlers";
 import type { NavDefinition, NavIconKey } from "./types/nav";
@@ -33,6 +33,8 @@ import type {
   ConfigEditScreenDefinition,
   EditFieldsSection,
   ScreenDefinition,
+  SecretsEditScreenDefinition,
+  SecretsEditSection,
 } from "./types/screen";
 
 // Namespace, unter dem buildAppSchema die generierten Screens/Navs einhängt
@@ -53,6 +55,9 @@ export type ConfigFeatureSchema = {
   // wenn die App bereits Workspaces nutzt (sonst kippt eine workspace-lose
   // App in den Filter-Modus und verliert alle übrigen Navs).
   readonly workspace?: WorkspaceSchema;
+  // Generated i18n keys for the secrets screen (label/hint text pulled from
+  // the `r.secret()` declaration itself, not authored via r.translations).
+  readonly translations?: TranslationKeys;
 };
 
 // Audience-Reihenfolge im Sidebar: Plattform vor Tenant vor Benutzer.
@@ -105,64 +110,231 @@ type MaskedKey = {
 
 type ScopedKey = { readonly key: MaskedKey; readonly roles: readonly string[] };
 
-export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchema {
-  const masked = collectMaskedKeys(registry);
-  if (masked.length === 0) return { screens: [], navs: [] };
+type ScopeResult = {
+  readonly screens: readonly ScreenDefinition[];
+  readonly navs: readonly NavDefinition[];
+  readonly translations?: TranslationKeys;
+};
 
-  // Verbatim (unprefixed) keys as the client sees them — NOT getAllTranslations()
-  // (server-merged, "feature:"-prefixed, see build-app-schema.ts:77-81).
+// Verbatim (unprefixed) keys as the client sees them — NOT getAllTranslations()
+// (server-merged, "feature:"-prefixed, see build-app-schema.ts:77-81).
+function collectDeclaredTranslationKeys(registry: Registry): Set<string> {
   const declaredTranslationKeys = new Set<string>();
   for (const f of registry.features.values()) {
     for (const key of Object.keys(f.translations ?? {})) declaredTranslationKeys.add(key);
   }
+  return declaredTranslationKeys;
+}
+
+// Per-feature configEdit screen + child-nav, one pair per feature present in
+// `visible` at this scope.
+function buildFeatureScreensAndNavs(
+  scope: ConfigScope,
+  visible: readonly ScopedKey[],
+  declaredTranslationKeys: ReadonlySet<string>,
+): { screens: ScreenDefinition[]; navs: NavDefinition[] } {
+  const screens: ScreenDefinition[] = [];
+  const navs: NavDefinition[] = [];
+  for (const feature of featuresPresent(visible.map((v) => v.key))) {
+    const group = visible.filter((v) => v.key.feature === feature);
+    const ordered = sortByMaskOrder(group.map((v) => v.key));
+    const access = rolesToAccess(group.flatMap((v) => v.roles));
+    const shortId = `${feature}-${scope}`;
+
+    screens.push(buildScreen(shortId, scope, feature, ordered, access, declaredTranslationKeys));
+    // A tenant/user-home key with an elevated write role (SystemAdmin on a
+    // tenant key, see ELEVATED_ROLES) surfaces the SAME feature under two
+    // audience navs (cascade-default screen + home screen) — both would
+    // otherwise carry the identical `${feature}.settings` label. Opt-in
+    // scoped override (`${feature}.settings.${scope}`) disambiguates only
+    // where a feature actually declares one; every single-scope feature
+    // keeps the plain key unchanged.
+    const scopedLabel = `${feature}.settings.${scope}`;
+    navs.push({
+      id: shortId,
+      label: declaredTranslationKeys.has(scopedLabel) ? scopedLabel : `${feature}.settings`,
+      parent: audienceNavShortId(scope),
+      screen: shortId,
+      icon: ordered[0]?.def.mask?.icon ?? "settings",
+      order: minMaskOrder(ordered),
+      access,
+    });
+  }
+  return { screens, navs };
+}
+
+// Everything generated for one audience scope: the audience-parent nav, the
+// per-feature configEdit screens+navs, and (tenant-scope only, when secrets
+// are enabled) the secrets screen. Null when nothing is visible at this scope.
+function buildScopeResult(
+  scope: ConfigScope,
+  masked: readonly MaskedKey[],
+  secretsEnabled: boolean,
+  secretsWriteHandler: ReturnType<Registry["getWriteHandler"]>,
+  declaredSecrets: readonly DeclaredSecret[],
+  declaredTranslationKeys: ReadonlySet<string>,
+): ScopeResult | null {
+  const visible = scopedKeysAt(masked, scope);
+  // Secrets attach to the tenant-audience nav regardless of whether any
+  // config key is visible there — they alone must be enough to open it.
+  const includeSecrets = secretsEnabled && scope === "tenant";
+  if (visible.length === 0 && !includeSecrets) return null;
+
+  const configAccess = rolesToAccess(visible.flatMap((v) => v.roles));
+  const secretsAccess = secretsWriteHandler?.access;
+  const screens: ScreenDefinition[] = [];
+  const navs: NavDefinition[] = [];
+  // Audience-Parent: Gruppierungs-Knoten ohne Screen.
+  navs.push({
+    id: audienceNavShortId(scope),
+    label: `config.settings.${scope}`,
+    icon: SCOPE_ICON[scope],
+    order: SCOPE_ORDER[scope],
+    access: includeSecrets ? unionAccessRules([configAccess, secretsAccess]) : configAccess,
+  });
+
+  const perFeature = buildFeatureScreensAndNavs(scope, visible, declaredTranslationKeys);
+  screens.push(...perFeature.screens);
+  navs.push(...perFeature.navs);
+
+  let translations: TranslationKeys | undefined;
+  if (includeSecrets) {
+    const generated = buildSecretsScreen(declaredSecrets, secretsAccess, declaredTranslationKeys);
+    screens.push(generated.screen);
+    navs.push(generated.nav);
+    translations = generated.translations;
+  }
+
+  return { screens, navs, ...(translations !== undefined && { translations }) };
+}
+
+export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchema {
+  const masked = collectMaskedKeys(registry);
+  const declaredSecrets = collectDeclaredSecrets(registry);
+  // The `secrets` feature must actually be mounted (its set-handler
+  // registered) for a declared `r.secret()` to have anywhere to write to.
+  const secretsWriteHandler = registry.getWriteHandler("secrets:write:set");
+  const secretsEnabled = secretsWriteHandler !== undefined && declaredSecrets.length > 0;
+  if (masked.length === 0 && !secretsEnabled) return { screens: [], navs: [] };
+
+  const declaredTranslationKeys = collectDeclaredTranslationKeys(registry);
 
   const screens: ScreenDefinition[] = [];
   const navs: NavDefinition[] = [];
+  let translations: TranslationKeys | undefined;
 
   for (const scope of SCOPES_BROAD_TO_DEEP) {
-    const visible = scopedKeysAt(masked, scope);
-    if (visible.length === 0) continue;
+    const result = buildScopeResult(
+      scope,
+      masked,
+      secretsEnabled,
+      secretsWriteHandler,
+      declaredSecrets,
+      declaredTranslationKeys,
+    );
+    if (result === null) continue;
+    screens.push(...result.screens);
+    navs.push(...result.navs);
+    if (result.translations !== undefined) translations = result.translations;
+  }
 
-    // Audience-Parent: Gruppierungs-Knoten ohne Screen.
-    navs.push({
-      id: audienceNavShortId(scope),
-      label: `config.settings.${scope}`,
-      icon: SCOPE_ICON[scope],
-      order: SCOPE_ORDER[scope],
-      access: rolesToAccess(visible.flatMap((v) => v.roles)),
+  // Every masked key machine-only and no secrets → no human hub, and no
+  // (empty) settings switcher.
+  if (navs.length === 0) return { screens, navs };
+  return {
+    screens,
+    navs,
+    workspace: buildSettingsWorkspace(navs),
+    ...(translations !== undefined && { translations }),
+  };
+}
+
+type DeclaredSecret = {
+  readonly qn: string;
+  readonly feature: string;
+  readonly shortKey: string;
+  readonly def: SecretKeyDefinition;
+};
+
+function collectDeclaredSecrets(registry: Registry): DeclaredSecret[] {
+  const out: DeclaredSecret[] = [];
+  for (const [qn, def] of registry.getAllSecretKeys()) {
+    const sep = qn.indexOf(":secret:");
+    if (sep === -1) continue;
+    out.push({
+      qn,
+      feature: qn.slice(0, sep),
+      shortKey: qn.slice(sep + ":secret:".length),
+      def,
     });
+  }
+  return out.sort(
+    (a, b) => a.feature.localeCompare(b.feature) || a.shortKey.localeCompare(b.shortKey),
+  );
+}
+
+// One screen for ALL declared secrets (not one per feature — a per-feature
+// nav would collide with the same feature's configEdit nav under
+// audience-tenant). `access` mirrors the secrets `set`-handler's own access
+// rule verbatim so a screen never permits more than the handler itself does.
+function buildSecretsScreen(
+  secrets: readonly DeclaredSecret[],
+  access: AccessRule | undefined,
+  declaredTranslationKeys: ReadonlySet<string>,
+): { screen: SecretsEditScreenDefinition; nav: NavDefinition; translations: TranslationKeys } {
+  const secretKeys: Record<string, string> = {};
+  const fieldLabels: Record<string, string> = {};
+  const fieldHints: Record<string, string> = {};
+  const requiredFields: string[] = [];
+  // Mutable outer record — TranslationKeys' Readonly<Record<...>> index
+  // signature only permits reading, so the top-level assignments below
+  // need a writable local type; each entry is still a fresh, never-mutated object.
+  const translations: Record<string, Readonly<Record<string, string>>> = {};
+  const sections: SecretsEditSection[] = [];
 
-    for (const feature of featuresPresent(visible.map((v) => v.key))) {
-      const group = visible.filter((v) => v.key.feature === feature);
-      const ordered = sortByMaskOrder(group.map((v) => v.key));
-      const access = rolesToAccess(group.flatMap((v) => v.roles));
-      const shortId = `${feature}-${scope}`;
-
-      screens.push(buildScreen(shortId, scope, feature, ordered, access, declaredTranslationKeys));
-      // A tenant/user-home key with an elevated write role (SystemAdmin on a
-      // tenant key, see ELEVATED_ROLES) surfaces the SAME feature under two
-      // audience navs (cascade-default screen + home screen) — both would
-      // otherwise carry the identical `${feature}.settings` label. Opt-in
-      // scoped override (`${feature}.settings.${scope}`) disambiguates only
-      // where a feature actually declares one; every single-scope feature
-      // keeps the plain key unchanged.
-      const scopedLabel = `${feature}.settings.${scope}`;
-      navs.push({
-        id: shortId,
-        label: declaredTranslationKeys.has(scopedLabel) ? scopedLabel : `${feature}.settings`,
-        parent: audienceNavShortId(scope),
-        screen: shortId,
-        icon: ordered[0]?.def.mask?.icon ?? "settings",
-        order: minMaskOrder(ordered),
-        access,
-      });
+  for (const feature of [...new Set(secrets.map((s) => s.feature))]) {
+    const fieldIds: string[] = [];
+    for (const s of secrets.filter((v) => v.feature === feature)) {
+      const fieldId = `${s.feature}-${s.shortKey}`;
+      fieldIds.push(fieldId);
+      secretKeys[fieldId] = s.qn;
+      const labelKey = `config.secret.${s.feature}.${s.shortKey}.label`;
+      fieldLabels[fieldId] = labelKey;
+      translations[labelKey] = { ...s.def.label };
+      if (s.def.hint !== undefined) {
+        const hintKey = `config.secret.${s.feature}.${s.shortKey}.hint`;
+        fieldHints[fieldId] = hintKey;
+        translations[hintKey] = { ...s.def.hint };
+      }
+      if (s.def.required === true) requiredFields.push(fieldId);
     }
+    const titleKey = `${feature}.settings`;
+    sections.push({
+      ...(declaredTranslationKeys.has(titleKey) && { title: titleKey }),
+      fields: fieldIds,
+    });
   }
 
-  // Alle masked Keys maschinen-only → kein menschlicher Hub, kein (leerer)
-  // Settings-Switcher.
-  if (navs.length === 0) return { screens, navs };
-  return { screens, navs, workspace: buildSettingsWorkspace(navs) };
+  const screen: SecretsEditScreenDefinition = {
+    id: "secrets",
+    type: "secretsEdit",
+    secretKeys,
+    fieldLabels,
+    ...(Object.keys(fieldHints).length > 0 && { fieldHints }),
+    ...(requiredFields.length > 0 && { requiredFields }),
+    sections,
+    ...(access !== undefined && { access }),
+  };
+  const nav: NavDefinition = {
+    id: "secrets",
+    label: "config.secrets.title",
+    parent: audienceNavShortId("tenant"),
+    screen: "secrets",
+    icon: "key",
+    order: 900,
+    ...(access !== undefined && { access }),
+  };
+  return { screen, nav, translations };
 }
 
 // Keys visible at `scope`, paired with their effective write roles AT that

package/src/engine/index.ts

@@ -440,6 +440,8 @@ export type {
   ScreenNavSugar,
   ScreenSlots,
   SecretKeyHandle,
+  SecretsEditScreenDefinition,
+  SecretsEditSection,
   SelectFieldDef,
   SessionUser,
   StreamHandlerDef,

package/src/engine/registry-validate.ts

@@ -587,6 +587,22 @@ export function validateJobTriggers(state: RegistryState): void {
   }
 }
 
+export function validateBootGates(state: RegistryState): void {
+  // Boot gates run inline in JobRunner.start(), which has neither the
+  // per-tenant fan-out (that re-enqueues) nor the sequential lock's
+  // re-enqueue-and-return path. Both would make the gate pass silently
+  // without ever running the handler.
+  for (const [jobName, jobDef] of state.jobMap) {
+    if (!jobDef.bootGate) continue;
+    if (jobDef.perTenant) {
+      throw new Error(`Job "${jobName}" cannot combine bootGate with perTenant`);
+    }
+    if (jobDef.concurrency === "sequential") {
+      throw new Error(`Job "${jobName}" cannot combine bootGate with concurrency "sequential"`);
+    }
+  }
+}
+
 export function validateExtensionUsageTargets(state: RegistryState): void {
   // Validate: extension usages must reference existing extensions
   for (const usage of state.extensionUsages) {

package/src/engine/registry.ts

@@ -27,6 +27,7 @@ import {
   populateHandlerEntityMappings,
   publishEventPiiCatalog,
   resolveNotificationTriggersAndRegisterHooks,
+  validateBootGates,
   validateEntityHookTargets,
   validateEventMigrationVersions,
   validateExtensionSelectors,
@@ -79,6 +80,7 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   validateLifecycleHookTargets(state);
   validateEntityHookTargets(state, features);
   validateJobTriggers(state);
+  validateBootGates(state);
   validateExtensionUsageTargets(state);
   computeHasRateLimitedHandler(state);
   publishEventPiiCatalog(state);

package/src/engine/types/index.ts

@@ -297,6 +297,8 @@ export type {
   ScreenFilterOp,
   ScreenNavSugar,
   ScreenSlots,
+  SecretsEditScreenDefinition,
+  SecretsEditSection,
   ToolbarAction,
   UnitKey,
 } from "@cosmicdrift/kumiko-types/screen";

package/src/i18n/index.ts

@@ -13,6 +13,7 @@ export {
   pickAcceptLanguage,
   resolveHeaderLocale,
 } from "./request-locale";
+export { SETTINGS_HUB_I18N } from "./settings-hub-keys";
 
 export type I18nOptions = {
   defaultLocale: string;

package/src/i18n/required-surface-keys.ts

@@ -13,6 +13,7 @@ import type {
   ProjectionListScreenDefinition,
   RowAction,
   ScreenDefinition,
+  SecretsEditScreenDefinition,
   ToolbarAction,
   WorkspaceDefinition,
 } from "../engine/types";
@@ -223,6 +224,16 @@ export function requiredKeysFromScreen(
       }
       break;
     }
+    case "secretsEdit": {
+      const secretsEdit = screen as SecretsEditScreenDefinition;
+      for (const key of Object.values(secretsEdit.fieldLabels))
+        pushKey(out, key, treatDotFormAsKey);
+      for (const key of Object.values(secretsEdit.fieldHints ?? {})) {
+        pushKey(out, key, treatDotFormAsKey);
+      }
+      for (const section of secretsEdit.sections) pushKey(out, section.title, treatDotFormAsKey);
+      break;
+    }
     case "projectionDetail": {
       const detail = screen as ProjectionDetailScreenDefinition;
       for (const section of detail.layout.sections) {

package/src/i18n/settings-hub-keys.ts

@@ -0,0 +1,28 @@
+import type { TranslationKeys } from "../engine/types/config";
+
+/**
+ * Settings-Hub chrome keys (parent-nav labels, secrets-screen title/strings)
+ * needed by ANY app that mounts a foundation feature producing a hub nav —
+ * `secrets` is auto-mounted (see FOUNDATION_FEATURES in
+ * @cosmicdrift/kumiko-dev-server scaffold-app.ts) while `config` stays
+ * optional, so these keys must be shippable without `config` present.
+ * Both `config` and `secrets` ship this bundle via r.translations — see
+ * @cosmicdrift/kumiko-bundled-features config/i18n.ts (CONFIG_FEATURE_I18N)
+ * and secrets/feature.ts. Owned here (not in bundled-features) because the
+ * Settings-Hub generator that requires these keys
+ * (build-config-feature-schema.ts) lives in this package.
+ */
+export const SETTINGS_HUB_I18N: TranslationKeys = {
+  "config.settings.title": { en: "Settings" },
+  "config.settings.system": { en: "Platform" },
+  "config.settings.tenant": { en: "Tenant" },
+  "config.settings.user": { en: "Personal" },
+  "config.secrets.title": { en: "Secrets" },
+  "config.secrets.notSet": { en: "Not set" },
+  "config.secrets.set": { en: "Set" },
+  "config.secrets.required": { en: "Required" },
+  "config.secrets.placeholder": { en: "Enter a value" },
+  "config.secrets.replacePlaceholder": { en: "Enter a new value to replace" },
+  "config.secrets.delete": { en: "Delete" },
+  "screen:secrets.title": { en: "Secrets" },
+};

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -15,6 +15,7 @@ import { createInMemoryFileProvider } from "../../files/in-memory-provider";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { sleep, waitFor } from "../../testing";
 import {
+  bootJobIdForJobName,
   createJobRunner,
   type JobLogEntry,
   type JobMeta,
@@ -1222,3 +1223,129 @@ describe("job registry", () => {
     expect(job?.runOnBoot).toBe(true);
   });
 });
+
+// --- Boot gates: only an inline gate can abort a boot (fw#2590) ---
+
+describe("boot gates", () => {
+  const gateLog: string[] = [];
+  const GATE_FAILURE = "required legal blocks are not seeded";
+
+  function uniquePrefix(): string {
+    return `kumiko-gate-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+
+  function createGateRunner(
+    feature: ReturnType<typeof defineFeature>,
+    queueNamePrefix: string,
+  ): JobRunner {
+    const context: AppContext = {};
+    return createJobRunner({
+      registry: createRegistry([feature]),
+      context,
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+    });
+  }
+
+  async function purge(queueNamePrefix: string): Promise<void> {
+    const keys = await testRedis.redis.keys(`bull:${queueNamePrefix}-worker:*`);
+    if (keys.length > 0) await testRedis.redis.del(...keys);
+  }
+
+  test("a throwing gate rejects start() and stops the remaining boot wiring", async () => {
+    const feature = defineFeature("failgate", (r) => {
+      r.job("check", { trigger: { manual: true }, bootGate: true }, async () => {
+        throw new Error(GATE_FAILURE);
+      });
+      r.job("afterGate", { trigger: { manual: true }, runOnBoot: true }, async () => {
+        gateLog.push("after-gate");
+      });
+    });
+    const prefix = uniquePrefix();
+    const runner = createGateRunner(feature, prefix);
+    gateLog.length = 0;
+
+    // Pin the qualified name the boot-job-id assertion below is built on —
+    // a typo there would make that assertion pass vacuously.
+    const afterGateName = "failgate:job:after-gate";
+    expect(createRegistry([feature]).getJob(afterGateName)).toBeDefined();
+
+    const queue = new Queue(`${prefix}-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", () => {});
+
+    try {
+      // The gate's own message must survive — which blocks are missing is the
+      // entire operational value, and onJobFailed runs before the re-throw.
+      await expect(runner.start()).rejects.toThrow(GATE_FAILURE);
+      await sleep(300);
+      // The gate aborted start() before any further boot wiring ran: the
+      // runOnBoot job was never even enqueued, and never executed.
+      const bootJob = await queue.getJob(bootJobIdForJobName(afterGateName));
+      expect(bootJob).toBeUndefined();
+      expect(gateLog).toEqual([]);
+    } finally {
+      await queue.close();
+      await runner.stop();
+      await purge(prefix);
+    }
+  });
+
+  test("a gate runs on every start, unlike a deduped runOnBoot job", async () => {
+    const feature = defineFeature("everygate", (r) => {
+      r.job("check", { trigger: { manual: true }, bootGate: true }, async () => {
+        gateLog.push("gate");
+      });
+      r.job("once", { trigger: { manual: true }, runOnBoot: true }, async () => {
+        gateLog.push("boot");
+      });
+    });
+    const prefix = uniquePrefix();
+    gateLog.length = 0;
+
+    const first = createGateRunner(feature, prefix);
+    await first.start();
+    await waitFor(() => {
+      expect(gateLog.filter((e) => e === "boot").length).toBe(1);
+    });
+    await first.stop();
+
+    const second = createGateRunner(feature, prefix);
+    try {
+      await second.start();
+      await sleep(300);
+      expect(gateLog.filter((e) => e === "gate").length).toBe(2);
+      // Same fixed boot job id, still present in Redis from the first start,
+      // so BullMQ drops the second enqueue — that dedup is why runOnBoot
+      // cannot gate a deploy.
+      expect(gateLog.filter((e) => e === "boot").length).toBe(1);
+    } finally {
+      await second.stop();
+      await purge(prefix);
+    }
+  });
+
+  test("bootGate is rejected for perTenant and sequential jobs", () => {
+    const perTenantGate = defineFeature("pergate", (r) => {
+      r.job("check", { trigger: { manual: true }, bootGate: true, perTenant: true }, async () => {
+        gateLog.push("never");
+      });
+    });
+    expect(() => createRegistry([perTenantGate])).toThrow(/bootGate with perTenant/);
+
+    const sequentialGate = defineFeature("seqgate", (r) => {
+      r.job(
+        "check",
+        { trigger: { manual: true }, bootGate: true, concurrency: "sequential" },
+        async () => {
+          gateLog.push("never");
+        },
+      );
+    });
+    expect(() => createRegistry([sequentialGate])).toThrow(/bootGate with concurrency/);
+  });
+});

package/src/jobs/job-runner.ts

@@ -1,4 +1,4 @@
-import { type Job, Queue, Worker } from "bullmq";
+import { Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow } from "../db/connection";
@@ -395,7 +395,17 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     return false;
   }
 
-  async function handleJob(bullJob: Job): Promise<void> {
+  // Structural instead of BullMQ's `Job` so boot gates can invoke the same
+  // execution path inline. A real `Job` stays assignable, so handleJob is
+  // still a valid BullMQ Processor.
+  type JobInvocation = {
+    readonly id?: string | undefined;
+    readonly name: string;
+    readonly data: Record<string, unknown>;
+    readonly attemptsMade: number;
+  };
+
+  async function handleJob(bullJob: JobInvocation): Promise<void> {
     const rawName = bullJob.name;
 
     // Handle perTenant dispatch jobs — fan out to one job per tenant. The
@@ -651,6 +661,27 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     }
   }
 
+  // Boot gates run inline and are awaited, so a throwing gate rejects start()
+  // — and with it the entrypoint's start() and runProdApp's boot, before the
+  // process reports ready. Enqueuing them (as runOnBoot does) would only fail
+  // a queue job and let the deploy through (fw#2590).
+  async function runBootGates(lane: JobRunIn): Promise<void> {
+    for (const [name, jobDef] of allJobs) {
+      if (laneForJob(jobDef) !== lane) continue;
+      if (!jobDef.bootGate) continue;
+      try {
+        await handleJob({ id: bootJobIdForJobName(name), name, data: {}, attemptsMade: 0 });
+      } catch (err) {
+        // The worker is already consuming here; leaving its Redis connections
+        // open would keep the event loop alive and turn the aborted boot into
+        // a hanging process instead of a non-zero exit.
+        await worker?.close();
+        worker = null;
+        throw err;
+      }
+    }
+  }
+
   const runnerApi: JobRunner = {
     async start(): Promise<void> {
       // skip: enqueuer-only runner — no BullMQ worker, no cron schedules,
@@ -689,6 +720,10 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         bootTimeout.cancel();
       }
 
+      // Ahead of cron/runOnBoot wiring on purpose: a failed gate must not
+      // leave recurring schedulers behind.
+      await runBootGates(consumerLane);
+
       // Only schedule cron + boot for jobs that belong to this lane. Jobs
       // assigned to the other lane get their cron/boot wiring from the
       // runner running on that lane. Running both here would double-fire.