@cosmicdrift/kumiko-framework 0.299.0 → 0.305.0

package/src/env/__tests__/dry-run.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import { z } from "zod";
 import { defineFeature } from "../../engine/define-feature";
+import { prometheusMetricsEnvSchema } from "../../observability/metrics-wiring";
 import { renderDryRun } from "../dry-run";
 import { composeEnvSchema } from "../index";
 
@@ -90,7 +91,7 @@ describe("renderDryRun", () => {
     expect(ver?.default).toBe("1");
   });
 
-  it("pulumi mode emits `pulumi config set` lines, omitting optional+defaulted", () => {
+  it("pulumi mode emits required lines, optional ones commented out, omits defaulted", () => {
     const composed = buildComposed();
     const out = renderDryRun(composed, "pulumi", { pulumiPrefix: "studio" });
     expect(out).toContain(
@@ -100,9 +101,36 @@ describe("renderDryRun", () => {
       'pulumi config set --secret studioSecretsMasterKey "$(openssl rand -base64 32)"',
     );
     expect(out).toContain('pulumi config set studioStudioAdminEmail "<set-me>"');
-    // Optional + default skipped:
-    expect(out).not.toContain("SMTP_HOST");
+    expect(out).toContain(
+      '# pulumi config set studioSmtpHost "<set-me>" # SMTP_HOST (channel-email-smtp): Outbound SMTP host',
+    );
+    expect(out).not.toMatch(/^pulumi config set.*SMTP_HOST/m);
     expect(out).not.toContain("CURRENT_VERSION");
+    const requiredLineIndex = out.lastIndexOf("pulumi config set studioStudioAdminEmail");
+    const optionalHeaderIndex = out.indexOf("# Optional (uncomment and set to enable):");
+    expect(requiredLineIndex).toBeGreaterThanOrEqual(0);
+    expect(optionalHeaderIndex).toBeGreaterThan(requiredLineIndex);
+  });
+
+  it("pulumi mode lists an optional secret field (PROMETHEUS_METRICS_TOKEN) commented out with generator", () => {
+    const composed = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }).extend(prometheusMetricsEnvSchema.shape),
+    });
+    const out = renderDryRun(composed, "pulumi");
+    expect(out).toContain(
+      '# pulumi config set --secret prometheusMetricsToken "$(openssl rand -base64 32)" # PROMETHEUS_METRICS_TOKEN (app): Bearer token for /metrics; unset keeps the endpoint off.',
+    );
+    expect(out).not.toMatch(/^pulumi config set.*PROMETHEUS_METRICS_TOKEN/m);
+  });
+
+  it("pulumi mode omits the Optional header when there are no optional fields", () => {
+    const composed = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }),
+    });
+    const out = renderDryRun(composed, "pulumi");
+    expect(out).not.toContain("# Optional");
   });
 
   it("k8s mode emits a Secret manifest", () => {
@@ -117,5 +145,17 @@ describe("renderDryRun", () => {
     expect(out).toContain("namespace: studio");
     expect(out).toContain('JWT_SECRET: "<set-me>"');
     expect(out).toContain('KUMIKO_SECRETS_MASTER_KEY_V1: "<set-me>"');
+    expect(out).toContain('  # SMTP_HOST: "<set-me>" # (channel-email-smtp): Outbound SMTP host');
+    expect(out).not.toMatch(/^ {2}SMTP_HOST:/m);
+    expect(out).not.toContain("CURRENT_VERSION");
+  });
+
+  it("k8s mode omits the Optional header when there are no optional fields", () => {
+    const composed = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }),
+    });
+    const out = renderDryRun(composed, "k8s");
+    expect(out).not.toContain("# Optional");
   });
 });

package/src/env/dry-run.ts

@@ -152,20 +152,27 @@ function renderJson(fields: readonly EnvField[], options: DryRunOptions): string
   )}\n`;
 }
 
+function pulumiConfigSetLine(f: EnvField, options: DryRunOptions): string {
+  const meta = readKumikoMeta(f.field);
+  const key = pulumiConfigKey(f.name, f.field, options.pulumiPrefix);
+  const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+  const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+  const comment = f.description
+    ? ` # ${f.name} (${f.source}): ${f.description}`
+    : ` # ${f.name} (${f.source})`;
+  return `pulumi config set${secretFlag} ${key} ${value}${comment}`;
+}
+
 function renderPulumi(fields: readonly EnvField[], options: DryRunOptions): string {
   // Defaulted vars are skipped — the framework provides them, ops doesn't.
-  const lines: string[] = [];
-  for (const f of fields) {
-    if (f.klass === "withDefault") continue;
-    if (f.klass === "optional") continue;
-    const meta = readKumikoMeta(f.field);
-    const key = pulumiConfigKey(f.name, f.field, options.pulumiPrefix);
-    const secretFlag = meta.pulumi?.secret ? " --secret" : "";
-    const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
-    const comment = f.description
-      ? ` # ${f.name} (${f.source}): ${f.description}`
-      : ` # ${f.name} (${f.source})`;
-    lines.push(`pulumi config set${secretFlag} ${key} ${value}${comment}`);
+  // Optional vars stay commented out: setting one turns its feature on.
+  const required = fields.filter((f) => f.klass === "required");
+  const optional = fields.filter((f) => f.klass === "optional");
+  const lines: string[] = required.map((f) => pulumiConfigSetLine(f, options));
+  if (optional.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push("# Optional (uncomment and set to enable):");
+    for (const f of optional) lines.push(`# ${pulumiConfigSetLine(f, options)}`);
   }
   return `${lines.join("\n")}\n`;
 }
@@ -183,9 +190,15 @@ function renderK8s(fields: readonly EnvField[], options: DryRunOptions): string
     "stringData:",
   ];
   for (const f of fields) {
-    if (f.klass === "withDefault") continue;
-    if (f.klass === "optional") continue;
-    lines.push(`  ${f.name}: "<set-me>"`);
+    if (f.klass === "required") lines.push(`  ${f.name}: "<set-me>"`);
+  }
+  const optional = fields.filter((f) => f.klass === "optional");
+  if (optional.length > 0) {
+    lines.push("  # Optional (uncomment and set to enable):");
+    for (const f of optional) {
+      const comment = f.description ? ` # (${f.source}): ${f.description}` : ` # (${f.source})`;
+      lines.push(`  # ${f.name}: "<set-me>"${comment}`);
+    }
   }
   return `${lines.join("\n")}\n`;
 }

package/src/errors/__tests__/write-failures.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { failNotFound, failTransition, failUnprocessable } from "../write-error-info";
+import { InternalError, NotFoundError } from "../classes";
+import {
+  failNotFound,
+  failTransition,
+  failUnprocessable,
+  reraiseAsKumikoError,
+  toWriteErrorInfo,
+} from "../write-error-info";
 
 describe("failNotFound", () => {
   test("baut WriteFailure mit reason=not_found + entity-id-details", () => {
@@ -73,7 +80,6 @@ describe("failTransition", () => {
 describe("toWriteErrorInfo — dev cause-snapshot", () => {
   test("InternalError mit cause exposed cause-Snapshot in details (dev)", async () => {
     const { toWriteErrorInfo } = await import("../write-error-info");
-    const { InternalError } = await import("../classes");
     const previous = process.env["NODE_ENV"];
     process.env["NODE_ENV"] = "development";
     try {
@@ -93,7 +99,6 @@ describe("toWriteErrorInfo — dev cause-snapshot", () => {
 
   test("Production: InternalError lässt details undefined (kein Stack-Leak)", async () => {
     const { toWriteErrorInfo } = await import("../write-error-info");
-    const { InternalError } = await import("../classes");
     const previous = process.env["NODE_ENV"];
     process.env["NODE_ENV"] = "production";
     try {
@@ -107,7 +112,6 @@ describe("toWriteErrorInfo — dev cause-snapshot", () => {
 
   test("InternalError MIT bereits gesetztem details → Author-details gewinnt (kein Overwrite)", async () => {
     const { toWriteErrorInfo } = await import("../write-error-info");
-    const { InternalError } = await import("../classes");
     const previous = process.env["NODE_ENV"];
     process.env["NODE_ENV"] = "development";
     try {
@@ -122,3 +126,42 @@ describe("toWriteErrorInfo — dev cause-snapshot", () => {
     }
   });
 });
+
+// The cause must reach routes.ts's logServerFault via reraiseAsKumikoError,
+// but never the wire body or the idempotency cache (both serialize the info).
+describe("toWriteErrorInfo / reraiseAsKumikoError — cause round-trip", () => {
+  test("cause survives toWriteErrorInfo → reraiseAsKumikoError without appearing on the info object", () => {
+    const boom = new Error("connection was closed");
+    const info = toWriteErrorInfo(new InternalError({ cause: boom }));
+    expect(reraiseAsKumikoError(info).cause).toBe(boom);
+    expect(Object.keys(info)).not.toContain("cause");
+  });
+
+  test("production: cause still reaches reraise even though details/message stay sanitized", () => {
+    const previous = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    try {
+      const boom = new Error("connection was closed");
+      const info = toWriteErrorInfo(new InternalError({ cause: boom }));
+      expect(info.details).toBeUndefined();
+      const serialized = JSON.stringify(info);
+      expect(serialized).not.toContain("connection was closed");
+      expect(serialized).not.toContain("cause");
+      expect(reraiseAsKumikoError(info).cause).toBe(boom);
+    } finally {
+      if (previous === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = previous;
+    }
+  });
+
+  test("KumikoError without a cause → reraised error has no cause", () => {
+    const info = toWriteErrorInfo(new NotFoundError("invoice", "inv-1"));
+    expect(reraiseAsKumikoError(info).cause).toBeUndefined();
+  });
+
+  test("a plain object with the same shape (simulated idempotency-cache replay) carries no cause", () => {
+    const info = toWriteErrorInfo(new InternalError({ cause: new Error("connection was closed") }));
+    const replayed = { ...info };
+    expect(reraiseAsKumikoError(replayed).cause).toBeUndefined();
+  });
+});

package/src/errors/i18n/de.yaml

@@ -147,6 +147,18 @@ member_resolution_read_only:
     `jobRunner`/...). Aufgelöste Member-Principals sind nur lesend — es gibt
     kein `writeAsMember`.
 
+public_intake_required:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: ein Write unter einem anonymen Wurzel-Handler hat ein
+    Personendaten-Feld (`pii` / `userOwned` / `recordOwned`) geschrieben, direkt
+    oder über `ctx.write`/`writeAs`/`queryAs` oder einen Hook. `details` nennen
+    `rootHandler`, `target` und `fields`. Ist der anonyme Intake gewollt, am
+    Wurzel-Handler `access: { roles: [..., "anonymous"], personalData: "public-intake" }`
+    deklarieren.
+
 agent.tool_not_allowed:
   endUser: |
     Dieses Tool ist im aktuellen Modus nicht verfügbar.

package/src/errors/i18n/en.yaml

@@ -141,6 +141,18 @@ member_resolution_read_only:
     to write (`ctx.write`/`writeAs`/`appendEvent`/`jobRunner`/...). Resolved
     member principals are read-only — there is no `writeAsMember`.
 
+public_intake_required:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: a write under an anonymous root handler touched a
+    personal-data field (`pii` / `userOwned` / `recordOwned`), directly or via
+    `ctx.write`/`writeAs`/`queryAs` or a hook. `details` name `rootHandler`,
+    `target` and `fields`. Declare
+    `access: { roles: [..., "anonymous"], personalData: "public-intake" }` on
+    the root handler if the anonymous intake is intended.
+
 agent.tool_not_allowed:
   endUser: |
     This tool is not available in the current mode.

package/src/errors/reasons.ts

@@ -59,6 +59,10 @@ export const FrameworkReasons = {
   // AccessDeniedError: a query handler invoked via ctx.queryAsMember tried to
   // write — a resolved member principal is read-only by construction.
   memberResolutionReadOnly: "member_resolution_read_only",
+
+  // AccessDeniedError: a write under an anonymous root touched a personal-data field
+  // without the root handler declaring access.personalData: "public-intake".
+  publicIntakeRequired: "public_intake_required",
 } as const;
 
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];

package/src/errors/write-error-info.ts

@@ -58,6 +58,12 @@ export function failTransition(from: string, to: string, allowed: readonly strin
   );
 }
 
+// The cause travels out-of-band, keyed on the info object's identity: a field
+// on WriteErrorInfo would leak the underlying Error into the /batch failure
+// body and the idempotency cache, both of which serialize the info to JSON.
+// A cache replay yields a fresh object without an entry, so no cause there.
+const causeByWriteErrorInfo = new WeakMap<WriteErrorInfo, Error>();
+
 export function toWriteErrorInfo(err: KumikoError): WriteErrorInfo {
   // In dev/test surface the cause-snapshot through `details` so the
   // HTTP response carries something useful. Without this, internal_error
@@ -79,7 +85,7 @@ export function toWriteErrorInfo(err: KumikoError): WriteErrorInfo {
         : undefined
       : undefined;
   const effectiveDetails = err.details ?? causeDetails;
-  return {
+  const info: WriteErrorInfo = {
     code: err.code,
     httpStatus: err.httpStatus,
     i18nKey: err.i18nKey,
@@ -87,6 +93,8 @@ export function toWriteErrorInfo(err: KumikoError): WriteErrorInfo {
     ...(err.i18nParams && { i18nParams: err.i18nParams }),
     ...(effectiveDetails !== undefined && { details: effectiveDetails }),
   };
+  if (err.cause instanceof Error) causeByWriteErrorInfo.set(info, err.cause);
+  return info;
 }
 
 // Reconstitutes an error from WriteErrorInfo so command() (throw-based) can
@@ -95,19 +103,20 @@ export function toWriteErrorInfo(err: KumikoError): WriteErrorInfo {
 // httpStatus / details but `instanceof NotFoundError` won't work. That's OK:
 // the HTTP layer keys off code + httpStatus, not class identity.
 export function reraiseAsKumikoError(info: WriteErrorInfo): KumikoError {
-  return new ReraisedError(info);
+  return new ReraisedError(info, causeByWriteErrorInfo.get(info));
 }
 
 class ReraisedError extends KumikoError {
   readonly code: string;
   readonly httpStatus: number;
 
-  constructor(info: WriteErrorInfo) {
+  constructor(info: WriteErrorInfo, cause?: Error) {
     super({
       message: info.message,
       i18nKey: info.i18nKey,
       ...(info.i18nParams && { i18nParams: info.i18nParams }),
       ...(info.details !== undefined && { details: info.details }),
+      ...(cause && { cause }),
     });
     this.code = info.code;
     this.httpStatus = info.httpStatus;

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

@@ -0,0 +1,155 @@
+// fw#3167: buildRetryBullOpts only passed `{ type }` to BullMQ, never
+// `delay` — BullMQ's fixed/exponential backoff strategies compute
+// NaN/undefined without it (falsy), so a job with `backoff` set retried
+// immediately instead of waiting. These tests assert real inter-attempt
+// gaps via a real HTTP write that triggers the job through `trigger.on`,
+// same delivery path as dispatch-write.ts's afterCommitHooks.
+//
+// Only lower bounds are asserted (never upper) — BullMQ schedules the next
+// attempt at failureTime + delay using the same wall clock this test reads,
+// so a >= assertion is flake-free without inflating waitFor's budget.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../engine";
+import { setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { waitFor } from "../../testing";
+import { generateId } from "../../utils";
+
+const exponentialDefaultStarts: number[] = [];
+const exponentialCustomStarts: number[] = [];
+const fixedCustomStarts: number[] = [];
+
+function gapsBetween(starts: readonly number[]): number[] {
+  return starts.slice(1).map((start, index) => start - (starts[index] ?? start));
+}
+
+const backoffFixtureFeature = defineFeature("backofffixture", (r) => {
+  r.writeHandler(
+    "trigger-exponential-default",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: {} }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+  // AC: retries: 3, backoff: "exponential" — fails once, succeeds on retry 2.
+  // Default base delay is 1000ms, so the single retry gap must be >= 1000ms.
+  r.job(
+    "exponential-default",
+    {
+      trigger: { on: "backofffixture:write:trigger-exponential-default" },
+      retries: 3,
+      backoff: "exponential",
+    },
+    async () => {
+      exponentialDefaultStarts.push(Date.now());
+      if (exponentialDefaultStarts.length === 1) throw new Error("fails on attempt 1");
+    },
+  );
+
+  r.writeHandler(
+    "trigger-exponential-custom",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: {} }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+  // Per-job configurable + growing: delayMs 50 → gaps 50, 100, 200ms.
+  r.job(
+    "exponential-custom",
+    {
+      trigger: { on: "backofffixture:write:trigger-exponential-custom" },
+      retries: 3,
+      backoff: { type: "exponential", delayMs: 50 },
+    },
+    async () => {
+      exponentialCustomStarts.push(Date.now());
+      if (exponentialCustomStarts.length < 4)
+        throw new Error(`fails on attempt ${exponentialCustomStarts.length}`);
+    },
+  );
+
+  r.writeHandler(
+    "trigger-fixed-custom",
+    z.object({}),
+    async () => ({ isSuccess: true as const, data: {} }),
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+  );
+  r.job(
+    "fixed-custom",
+    {
+      trigger: { on: "backofffixture:write:trigger-fixed-custom" },
+      retries: 1,
+      backoff: { type: "fixed", delayMs: 300 },
+    },
+    async () => {
+      fixedCustomStarts.push(Date.now());
+      if (fixedCustomStarts.length === 1) throw new Error("fails on attempt 1");
+    },
+  );
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [backoffFixtureFeature],
+    // Own queue namespace: the default "kumiko-jobs" queue on the shared test
+    // Redis is consumed by every parallel test process, and a foreign worker
+    // grabbing a promoted delayed retry fails it as "Unknown job".
+    jobs: { consumerLane: "worker", queueNamePrefix: `backoff-test-${generateId()}` },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  exponentialDefaultStarts.length = 0;
+  exponentialCustomStarts.length = 0;
+  fixedCustomStarts.length = 0;
+});
+
+describe("job backoff waits between retries (fw#3167)", () => {
+  test('backoff: "exponential" without delayMs waits the default 1000ms base delay', async () => {
+    await stack.http.writeOk(
+      "backofffixture:write:trigger-exponential-default",
+      {},
+      TestUsers.admin,
+    );
+
+    await waitFor(() => {
+      expect(exponentialDefaultStarts).toHaveLength(2);
+    });
+
+    const [gap = 0] = gapsBetween(exponentialDefaultStarts);
+    expect(gap).toBeGreaterThanOrEqual(1000);
+  });
+
+  test("object-form backoff.delayMs is configurable per job and grows exponentially", async () => {
+    await stack.http.writeOk(
+      "backofffixture:write:trigger-exponential-custom",
+      {},
+      TestUsers.admin,
+    );
+
+    await waitFor(() => {
+      expect(exponentialCustomStarts).toHaveLength(4);
+    });
+
+    const [gap1 = 0, gap2 = 0, gap3 = 0] = gapsBetween(exponentialCustomStarts);
+    expect(gap1).toBeGreaterThanOrEqual(50);
+    expect(gap2).toBeGreaterThanOrEqual(100);
+    expect(gap3).toBeGreaterThanOrEqual(200);
+  });
+
+  test('backoff: { type: "fixed", delayMs } waits the configured constant delay', async () => {
+    await stack.http.writeOk("backofffixture:write:trigger-fixed-custom", {}, TestUsers.admin);
+
+    await waitFor(() => {
+      expect(fixedCustomStarts).toHaveLength(2);
+    });
+
+    const [gap = 0] = gapsBetween(fixedCustomStarts);
+    expect(gap).toBeGreaterThanOrEqual(300);
+  });
+});

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

@@ -1390,4 +1390,39 @@ describe("boot gates", () => {
     });
     expect(() => createRegistry([sequentialGate])).toThrow(/bootGate with concurrency/);
   });
+
+  test("object-form backoff.delayMs must be a positive integer", () => {
+    for (const badDelayMs of [0, -5, 1.5]) {
+      const feature = defineFeature("badbackoff", (r) => {
+        r.job(
+          "check",
+          { trigger: { manual: true }, backoff: { type: "fixed", delayMs: badDelayMs } },
+          async () => {
+            gateLog.push("never");
+          },
+        );
+      });
+      expect(() => createRegistry([feature])).toThrow(
+        /backoff\.delayMs must be a positive integer/,
+      );
+    }
+
+    const validObjectForm = defineFeature("goodbackoffobject", (r) => {
+      r.job(
+        "check",
+        { trigger: { manual: true }, backoff: { type: "exponential", delayMs: 100 } },
+        async () => {
+          gateLog.push("never");
+        },
+      );
+    });
+    expect(() => createRegistry([validObjectForm])).not.toThrow();
+
+    const validStringForm = defineFeature("goodbackoffstring", (r) => {
+      r.job("check", { trigger: { manual: true }, backoff: "fixed" }, async () => {
+        gateLog.push("never");
+      });
+    });
+    expect(() => createRegistry([validStringForm])).not.toThrow();
+  });
 });

package/src/jobs/job-runner.ts

@@ -1,4 +1,4 @@
-import { Queue, Worker } from "bullmq";
+import { type JobsOptions, Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow } from "../db/connection";
@@ -317,13 +317,27 @@ function timeoutReject(
   };
 }
 
+// Default base delay when a job opts into backoff without an explicit
+// delayMs. Without a `delay`, BullMQ's fixed/exponential strategies compute
+// NaN/undefined, which is falsy — the job retries immediately instead of
+// waiting.
+const DEFAULT_JOB_BACKOFF_DELAY_MS = 1_000;
+
 // Shared by dispatch() and handleEvent() — an event-triggered job must retry
 // on failure the same way a directly-dispatched one does; a duplicated
 // inline computation in handleEvent previously dropped both options.
-function buildRetryBullOpts(jobDef: JobDefinition): Record<string, unknown> {
-  const opts: Record<string, unknown> = {};
-  if (jobDef.retries !== undefined) opts["attempts"] = jobDef.retries + 1;
-  if (jobDef.backoff) opts["backoff"] = { type: jobDef.backoff };
+function buildRetryBullOpts(jobDef: JobDefinition): Pick<JobsOptions, "attempts" | "backoff"> {
+  const opts: Pick<JobsOptions, "attempts" | "backoff"> = {};
+  if (jobDef.retries !== undefined) opts.attempts = jobDef.retries + 1;
+  if (jobDef.backoff) {
+    opts.backoff =
+      typeof jobDef.backoff === "string"
+        ? { type: jobDef.backoff, delay: DEFAULT_JOB_BACKOFF_DELAY_MS }
+        : {
+            type: jobDef.backoff.type,
+            delay: jobDef.backoff.delayMs ?? DEFAULT_JOB_BACKOFF_DELAY_MS,
+          };
+  }
   return opts;
 }
 

package/src/observability/__tests__/metrics-wiring.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import { composeEnvSchema, readKumikoMeta } from "../../env";
+import { prometheusMetricsEnvSchema, resolveObservabilityWiring } from "../metrics-wiring";
+
+describe("resolveObservabilityWiring", () => {
+  it("returns {} without a token", () => {
+    expect(resolveObservabilityWiring(undefined)).toEqual({});
+  });
+
+  it("returns {} for an empty token", () => {
+    expect(resolveObservabilityWiring("")).toEqual({});
+  });
+
+  it("wires a prometheus provider and metrics route when a token is set", () => {
+    const token = "a".repeat(32);
+    const wiring = resolveObservabilityWiring(token);
+
+    expect("metrics" in wiring).toBe(true);
+    if (!("metrics" in wiring)) throw new Error("expected wiring to include metrics");
+
+    expect(wiring.metrics).toEqual({ path: "/metrics", token });
+    expect(wiring.observability.name).toBe("prometheus");
+    expect(wiring.observability.meter.snapshot()).toEqual(new Map());
+  });
+});
+
+describe("prometheusMetricsEnvSchema", () => {
+  it("rejects tokens shorter than 32 characters", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({
+      PROMETHEUS_METRICS_TOKEN: "a".repeat(31),
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts a 32-character token", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({
+      PROMETHEUS_METRICS_TOKEN: "a".repeat(32),
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a missing token", () => {
+    const result = prometheusMetricsEnvSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("exposes pulumi secret metadata for consumer env-schemas", () => {
+    const { schema } = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }).extend(prometheusMetricsEnvSchema.shape),
+    });
+
+    const field = schema.shape["PROMETHEUS_METRICS_TOKEN"];
+    if (!(field instanceof z.ZodType))
+      throw new Error("expected PROMETHEUS_METRICS_TOKEN in composed schema");
+    const meta = readKumikoMeta(field);
+    expect(meta.pulumi?.secret).toBe(true);
+    expect(meta.pulumi?.generator).toBe("openssl rand -base64 32");
+  });
+});

package/src/observability/index.ts

@@ -16,6 +16,11 @@ export {
   createSafeMetricsHandle,
   createUnboundMetricsHandle,
 } from "./metrics-handle";
+export {
+  type ObservabilityWiring,
+  prometheusMetricsEnvSchema,
+  resolveObservabilityWiring,
+} from "./metrics-wiring";
 export { createNoopProvider } from "./noop-provider";
 export {
   createPrometheusMeter,

package/src/observability/metrics-wiring.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { createNoopProvider } from "./noop-provider";
+import { createPrometheusMeter, type PrometheusMeter } from "./prometheus-meter";
+import type { ObservabilityProvider } from "./types";
+
+export const prometheusMetricsEnvSchema = z.object({
+  PROMETHEUS_METRICS_TOKEN: z
+    .string()
+    .min(32)
+    .optional()
+    .describe("Bearer token for /metrics; unset keeps the endpoint off.")
+    .meta({ kumiko: { pulumi: { secret: true, generator: "openssl rand -base64 32" } } }),
+});
+
+type PrometheusObservabilityProvider = ObservabilityProvider & { readonly meter: PrometheusMeter };
+
+export type ObservabilityWiring =
+  | {
+      readonly observability: PrometheusObservabilityProvider;
+      readonly metrics: { readonly path: string; readonly token: string };
+    }
+  | Record<string, never>;
+
+// Fail-closed: public tenant hosts share the /metrics port, so no token means no endpoint.
+export function resolveObservabilityWiring(metricsToken: string | undefined): ObservabilityWiring {
+  if (!metricsToken) return {};
+  return {
+    // Overrides the spread's name "noop", which would otherwise show up in diagnostics/logs.
+    observability: { ...createNoopProvider(), name: "prometheus", meter: createPrometheusMeter() },
+    metrics: { path: "/metrics", token: metricsToken },
+  };
+}