@cosmicdrift/kumiko-framework 0.290.0 → 0.292.0

package/src/engine/boot-validator/projection-list-screens.ts

@@ -105,13 +105,63 @@ function validateProjectionListFilterSchemaAcceptance(
 // (fw#2165): definePagedQueryHandler doesn't auto-merge params into the
 // handler's own Zod schema, so a declared facet would 422 on every query
 // unless the author added `filters` themselves.
+// A dateRange facet (fw#3104) sends its two bounds as the top-level payload
+// keys it names in `params`, not as a `filters` entry — so the query has to
+// accept exactly those keys. Catches the facet pointed at a field the query
+// can't narrow by, which would otherwise 422 on the first date the user picks.
+// Keys buildListQueryPayload owns — a facet param naming one of them would
+// silently replace the list's own paging/sorting on every pick.
+const RESERVED_LIST_PAYLOAD_KEYS: ReadonlySet<string> = new Set([
+  "limit",
+  "search",
+  "sort",
+  "sortDirection",
+  "offset",
+  "totalCount",
+  "cursor",
+  "filter",
+  "filters",
+]);
+
+function validateProjectionListDateRangeFacets(
+  prefix: string,
+  screen: ProjectionListScreenDefinition,
+  schema: QueryHandlerDef["schema"] | undefined,
+): void {
+  for (const facet of screen.facets ?? []) {
+    if (facet.type !== "dateRange") continue;
+    if (facet.params.from === facet.params.to) {
+      throw new Error(
+        `${prefix}: dateRange facet on "${facet.field}" names the same param ` +
+          `"${facet.params.from}" for both bounds.`,
+      );
+    }
+    for (const param of [facet.params.from, facet.params.to]) {
+      if (RESERVED_LIST_PAYLOAD_KEYS.has(param)) {
+        throw new Error(
+          `${prefix}: dateRange facet on "${facet.field}" names "${param}" as a bound, ` +
+            `which is a reserved list-payload key — pick the query's own time-bound param names.`,
+        );
+      }
+      if (schemaAccepts(schema, param)) continue;
+      throw new Error(
+        `${prefix}: dateRange facet on "${facet.field}" sends "${param}" but query ` +
+          `"${screen.query}" has no "${param}" parameter in its Zod schema — add ` +
+          `${param}: z.iso.datetime().optional() to the handler's schema, or point ` +
+          `params at the keys it already accepts.`,
+      );
+    }
+  }
+}
+
 function validateProjectionListFacetsSchemaAcceptance(
   prefix: string,
   screen: ProjectionListScreenDefinition,
   schema: QueryHandlerDef["schema"] | undefined,
 ): void {
-  // skip: no facets declared — nothing to reject.
-  if (screen.facets === undefined || screen.facets.length === 0) return;
+  validateProjectionListDateRangeFacets(prefix, screen, schema);
+  // skip: no facets that travel via `filters` — nothing to reject.
+  if (screen.facets === undefined || !screen.facets.some((f) => f.type !== "dateRange")) return;
   // skip: the schema already accepts filters — nothing to reject.
   if (schemaAccepts(schema, "filters")) return;
   throw new Error(

package/src/engine/boot-validator/screens.ts

@@ -578,10 +578,59 @@ function validateFormFieldsMap(
           `\`type\` set. Each field must declare a type (e.g. "text", "number", "select").`,
       );
     }
+    if (ftype === "money") {
+      validateFormMoneyCurrency(featureName, screenId, context, fname, fdef);
+    }
   }
   return fieldNames;
 }
 
+// Fail-closed currency-source gate (fw#2839), the runtime half of the
+// narrowed `FormFieldDefinition` — an untyped JS consumer has no compiler to
+// stop it. An inline form screen has no entity, so a money field there can't
+// borrow `entity.defaultCurrency`: without a declared source the renderer
+// seeds a bare `0` and the handler's zod schema rejects the submit. Entity
+// money fields are exempt — create-app already refuses an entity that holds
+// money without a `defaultCurrency`.
+function validateFormMoneyCurrency(
+  featureName: string,
+  screenId: string,
+  context: string,
+  fieldName: string,
+  fdef: unknown,
+): void {
+  const where = `[Feature ${featureName}] Screen "${screenId}" (${context}) money field "${fieldName}"`;
+  const validForms =
+    `Declare \`currency: { kind: "literal", code: "EUR" }\` for a fixed currency, or ` +
+    `\`currency: { kind: "tenant" }\` to take the tenant-settings bundle's per-tenant currency.`;
+  // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
+  const currency = (fdef as { currency?: { kind?: unknown; code?: unknown } | null }).currency;
+  if (currency === undefined) {
+    throw new Error(
+      `${where} must declare where its currency comes from — this screen has no entity whose ` +
+        `\`defaultCurrency\` it could inherit, so the form would seed a bare \`0\` that the ` +
+        `handler's schema rejects. ${validForms}`,
+    );
+  }
+  if (typeof currency !== "object" || currency === null) {
+    throw new Error(`${where} has a non-object \`currency\`. ${validForms}`);
+  }
+  const kind = currency.kind;
+  if (kind === "literal") {
+    const code = currency.code;
+    if (typeof code !== "string" || code.trim() === "") {
+      throw new Error(
+        `${where} declares \`currency: { kind: "literal" }\` with an empty or non-string \`code\`. ` +
+          `Pass the ISO code, e.g. { kind: "literal", code: "EUR" }.`,
+      );
+    }
+  } else if (kind !== "tenant") {
+    throw new Error(
+      `${where} declares an unknown currency kind ${JSON.stringify(kind)}. ${validForms}`,
+    );
+  }
+}
+
 // `allowEmptySections` mirrors `validateFormFieldsMap`'s `allowEmpty` — the
 // caller only ever passes true together with an actually-empty fields map
 // (an input-less secretMint declares BOTH `fields: {}` and
@@ -1265,6 +1314,7 @@ export function validateScreens(
                 `(writeForm) has zero fields — drop the section or add fields to it.`,
             );
           }
+          // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
           for (const f of section.fields) {
             const fieldName = normalizeEditField(f).field;
             if (section.fieldDefs[fieldName] === undefined) {

package/src/engine/create-app.ts

@@ -1,3 +1,4 @@
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-types/screen";
 import { type ValidateBootOptions, validateBoot } from "./boot-validator";
 import { dedupeFeatures } from "./dedupe-features";
 import { createRegistry } from "./registry";
@@ -20,6 +21,37 @@ export type App = {
   currencies: readonly string[];
 };
 
+// Every field map an entity-less inline form screen renders: actionForm's and
+// secretMint's own fields, plus a secretMint's separate `confirm` step.
+function inlineFormFieldMaps(
+  screen: ScreenDefinition,
+): readonly Readonly<Record<string, unknown>>[] {
+  if (screen.type === "actionForm") return [screen.fields];
+  if (screen.type !== "secretMint") return [];
+  return screen.confirm !== undefined ? [screen.fields, screen.confirm.fields] : [screen.fields];
+}
+
+// `currency: { kind: "literal", code }` (fw#2839) is only meaningful for a
+// code the app knows — a typo would otherwise render and submit amounts in a
+// currency no formatter or rate table covers.
+function validateLiteralCurrencyCode(
+  where: string,
+  field: unknown,
+  currencies: readonly string[],
+): void {
+  // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
+  const shape = field as { type?: unknown; currency?: { kind?: unknown; code?: unknown } };
+  if (shape.type === "money" && shape.currency?.kind === "literal") {
+    const code = shape.currency.code;
+    if (typeof code !== "string" || !currencies.includes(code)) {
+      throw new Error(
+        `${where} declares currency: { kind: "literal", code: ${JSON.stringify(code)} } which is ` +
+          `not in the currencies list. Available: ${currencies.join(", ")}`,
+      );
+    }
+  }
+}
+
 export function createApp(config: AppConfig): App {
   const features = dedupeFeatures(config.features);
   const validRoles = new Set(config.roles);
@@ -108,6 +140,28 @@ export function createApp(config: AppConfig): App {
           `Entity "${entityName}" in feature "${feature.name}" has money fields but no defaultCurrency. Set defaultCurrency on the entity definition.`,
         );
       }
+      for (const [fieldName, field] of Object.entries(entity.fields)) {
+        validateLiteralCurrencyCode(
+          `Entity "${entityName}" in feature "${feature.name}", money field "${fieldName}"`,
+          field,
+          currencies,
+        );
+      }
+    }
+    // A money field on an entity-less form screen names its own currency
+    // source (fw#2839) — a literal code has to be one the app actually knows,
+    // same rule the entity `defaultCurrency` check above applies.
+    for (const [screenId, screen] of Object.entries(feature.screens ?? {})) {
+      const inlineFields = inlineFormFieldMaps(screen);
+      for (const fields of inlineFields) {
+        for (const [fieldName, field] of Object.entries(fields)) {
+          validateLiteralCurrencyCode(
+            `Screen "${screenId}" in feature "${feature.name}", money field "${fieldName}"`,
+            field,
+            currencies,
+          );
+        }
+      }
     }
   }
 

package/src/engine/extension-names.ts

@@ -87,6 +87,16 @@ export const EXT_FILE_PROVIDER = "fileProvider" as const;
 // des file-foundation-Features MUSS diese Konstante mitziehen.
 export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider" as const;
 
+// Two roles: boot gate (validateBoot requires its presence once file/image
+// fields are in use) AND the ENV source of the config key above, bridged via
+// keyDef.env. Tenant rows keep overriding the bridged value.
+export const FILE_STORAGE_PROVIDER_ENV = "FILE_STORAGE_PROVIDER" as const;
+
+// Presence placeholder runDevApp writes when an explicitly wired provider
+// (options.files) already satisfies the boot gate. It names no plugin, so
+// provider resolution treats it like an unset key.
+export const FILE_STORAGE_PROVIDER_BOOT_SENTINEL = "configured" as const;
+
 /**
  * `derivativeRenderer` — File-Derivative-Renderer-Plugin-Selection
  * (file-derivatives).

package/src/engine/feature-config-events-jobs.ts

@@ -30,6 +30,17 @@ import type {
   TranslationsDef,
 } from "./types";
 
+// A payload field that still holds null/undefined after parsing — the case
+// where an event-PII owner field yields no subject at append time (fw#2776).
+// A `.default(...)` accepts undefined but parses to a value, so it is not
+// absentable.
+function isAbsentable(field: ZodType): boolean {
+  return [null, undefined].some((candidate) => {
+    const parsed = field.safeParse(candidate);
+    return parsed.success && (parsed.data === null || parsed.data === undefined);
+  });
+}
+
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
 export function buildConfigEventsJobsMethods<TName extends string>(
   state: FeatureBuilderState,
@@ -130,6 +141,14 @@ export function buildConfigEventsJobsMethods<TName extends string>(
           );
         }
       }
+      const owner = shape?.[normalized.ownerField];
+      if (normalized.whenAbsent === undefined && owner !== undefined && isAbsentable(owner)) {
+        throw new Error(
+          `[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${normalized.ownerField}", which the payload schema allows to be null/undefined. ` +
+            `Declare what happens then: { personal: { of: "${normalized.ownerField}", whenAbsent: "tenant" } } encrypts under the envelope tenant key, ` +
+            `whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`,
+        );
+      }
     }
   }
 

package/src/engine/index.ts

@@ -13,6 +13,7 @@ export {
 export {
   collectWriteHandlerQns,
   SECURITY_BASELINE_FEATURE_NAMES,
+  type ValidateBootOptions,
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "./boot-validator";
@@ -112,6 +113,8 @@ export {
   EXT_USER_DATA,
   EXT_USER_DATA_ORDER,
   FILE_PROVIDER_CONFIG_KEY,
+  FILE_STORAGE_PROVIDER_BOOT_SENTINEL,
+  FILE_STORAGE_PROVIDER_ENV,
   TENANT_MEMBERSHIPS_QUERY,
 } from "./extension-names";
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage";

package/src/engine/screen-helpers.ts

@@ -112,6 +112,7 @@ export type FieldsOrGroupsSection = {
 // one runs after the fields-XOR-groups check, collectors run without it and must
 // not drop a source (fw#2986).
 export function sectionFieldSpecs(section: FieldsOrGroupsSection): readonly EditFieldSpec[] {
+  // kumiko-lint-ignore section-fields-raw this IS the union reader — the groups source is added on the same line
   return [...section.fields, ...(section.groups?.flatMap((group) => group.fields) ?? [])];
 }
 

package/src/engine/system-user.ts

@@ -1,10 +1,8 @@
 import type { SessionUser } from "./types";
-import type { TenantId } from "./types/identifiers";
+import { SYSTEM_USER_ID, type TenantId } from "./types/identifiers";
+
+export { SYSTEM_USER_ID };
 
-// Stringified so it round-trips through SessionUser.id (string UUID-shape).
-// Not a real UUID — SYSTEM acts as an alias for "no human caller" and event-
-// store createdBy is text, so the literal suffices.
-export const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
 export const SYSTEM_ROLE = "system" as const;
 
 // extraRoles: hasAccess kennt keinen System-Bypass — Handler gaten auf

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -56,12 +56,20 @@ const crmFeature = defineFeature("crm", (r) => {
 // hand-written, so a camelCase event name (tenantNote → tenant-note) can
 // never drift from what the catalog is actually keyed by (fw#2801).
 let PING_EVENT_TYPE: string;
+let PING_TENANT_EVENT_TYPE: string;
+const pingSchema = z.object({
+  targetId: z.string().nullable(),
+  address: z.string().nullable(),
+});
 const mailerFeature = defineFeature("mailer", (r) => {
-  PING_EVENT_TYPE = r.defineEvent(
-    "ping",
-    z.object({ targetId: z.string().nullable(), address: z.string().nullable() }),
-    { piiFields: { address: { subjectField: "targetId" } } },
-  ).name;
+  // targetId is nullable, so the stance has to say what happens without an
+  // owner — the two events below cover both declarations (fw#2776).
+  PING_EVENT_TYPE = r.defineEvent("ping", pingSchema, {
+    piiFields: { address: { personal: { of: "targetId", whenAbsent: "plaintext" } } },
+  }).name;
+  PING_TENANT_EVENT_TYPE = r.defineEvent("pingTenant", pingSchema, {
+    piiFields: { address: { personal: { of: "targetId", whenAbsent: "tenant" } } },
+  }).name;
 });
 
 // fw#2801: custom events declaring a tenant/self subject — no entity,
@@ -272,7 +280,7 @@ describe("backfillEventPiiEncryption", () => {
     >;
     expect(erased["address"]).toBe(PII_ERASED_SENTINEL);
 
-    // No subject → no key to shred; stays plaintext (documented rollout gap).
+    // No subject and whenAbsent: "plaintext" → declared, stays plaintext.
     const system = (await loadAggregate(testDb.db, p3, TENANT))[0]?.payload as Record<
       string,
       unknown
@@ -280,6 +288,22 @@ describe("backfillEventPiiEncryption", () => {
     expect(system["address"]).toBe("ops@x.com");
   });
 
+  test('an absent owner with whenAbsent: "tenant" backfills under the tenant key (fw#2776)', async () => {
+    const p4 = generateId();
+    await appendPlain(p4, "ping", PING_TENANT_EVENT_TYPE, {
+      targetId: null,
+      address: "ops@x.com",
+    });
+
+    armKms();
+    const result = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(result.failures).toEqual([]);
+
+    const row = (await loadAggregate(testDb.db, p4, TENANT))[0]?.payload as Record<string, unknown>;
+    expect(isPiiCiphertext(row["address"])).toBe(true);
+    expect(String(row["address"])).toContain(`tenant:${TENANT}`);
+  });
+
   test("idempotent: second run updates nothing; dryRun writes nothing", async () => {
     const c1 = generateId();
     await appendPlain(c1, "contact", "contact.created", { id: c1, email: "a@x.com" });

package/src/files/provider-resolver.ts

@@ -15,7 +15,11 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { DbConnection } from "../db/connection";
 import type { TenantDb } from "../db/tenant-db";
-import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY } from "../engine/extension-names";
+import {
+  EXT_FILE_PROVIDER,
+  FILE_PROVIDER_CONFIG_KEY,
+  FILE_STORAGE_PROVIDER_BOOT_SENTINEL,
+} from "../engine/extension-names";
 import { SYSTEM_USER_ID } from "../engine/system-user";
 import type { ConfigAccessor, ConfigAccessorFactory, Registry } from "../engine/types";
 import type { SecretsContext } from "../secrets";
@@ -93,7 +97,10 @@ export async function createFileProviderForTenant(
 
   const raw = await ctxConfig(FILE_PROVIDER_CONFIG_KEY);
   const provider = typeof raw === "string" ? raw : raw == null ? "" : String(raw);
-  if (provider.length === 0) {
+  // The boot-gate placeholder names no plugin: treated as a provider name it
+  // would let FILE_STORAGE_PROVIDER=configured fake a selection through the
+  // ENV bridge.
+  if (provider.length === 0 || provider === FILE_STORAGE_PROVIDER_BOOT_SENTINEL) {
     const usages = ctx.registry.getExtensionUsages(EXT_FILE_PROVIDER);
     const known = usages.map((u) => u.entityName).join(", ") || "<none>";
     throw new Error(

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

@@ -328,6 +328,7 @@ export function requiredKeysFromScreen(
         if (isWriteFormEditSection(section)) {
           pushKey(out, section.title);
           pushKey(out, section.submitLabel);
+          // kumiko-lint-ignore section-fields-raw writeForm sections carry no groups (EditWriteFormSection)
           for (const f of section.fields) {
             const fieldName = editFieldName(f);
             out.add(fieldLabelKey(featureName, WRITE_FORM_SECTION_ENTITY, fieldName));

package/src/jobs/__tests__/job-last-success.integration.test.ts

@@ -0,0 +1,135 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { buildServer } from "../../api/server";
+import { createRegistry, defineFeature } from "../../engine";
+import type { AppContext, Registry } from "../../engine/types";
+import {
+  createNoopProvider,
+  createPrometheusMeter,
+  registerStandardMetrics,
+} from "../../observability";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { waitFor } from "../../testing";
+import { createJobRunner } from "../job-runner";
+
+const JWT = "job-last-success-test-secret-minimum-32-chars!!";
+const SUCCEEDS = "liveness:job:succeeds";
+const FAILS = "liveness:job:fails-always";
+
+let testRedis: TestRedis;
+let redisUrl: string;
+
+const livenessFeature = defineFeature("liveness", (r) => {
+  r.job("succeeds", { trigger: { manual: true } }, async () => {});
+  r.job("failsAlways", { trigger: { manual: true } }, async () => {
+    throw new Error("intentional failure");
+  });
+});
+
+beforeAll(async () => {
+  testRedis = await createTestRedis();
+  redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+});
+
+afterAll(async () => {
+  await testRedis.cleanup();
+});
+
+function slotFor(meter: ReturnType<typeof createPrometheusMeter>, job: string) {
+  return meter
+    .snapshot()
+    .get("kumiko_job_last_success_timestamp_seconds")
+    ?.slots.find((s) => s.labels?.["job"] === job);
+}
+
+async function withRunner(
+  meter: ReturnType<typeof createPrometheusMeter>,
+  fn: (runner: ReturnType<typeof createJobRunner>, failures: string[]) => Promise<void>,
+): Promise<void> {
+  const registry: Registry = createRegistry([livenessFeature]);
+  const context: AppContext = { meter };
+  const failures: string[] = [];
+  const queueNamePrefix = `kumiko-test-ls-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const runner = createJobRunner({
+    registry,
+    context,
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix,
+    onJobFailed: (jobName) => {
+      failures.push(jobName);
+    },
+  });
+  await runner.start();
+  try {
+    await fn(runner, failures);
+  } finally {
+    await runner.stop();
+    const keys = await testRedis.redis.keys(`bull:${queueNamePrefix}-worker:*`);
+    if (keys.length > 0) await testRedis.redis.del(...keys);
+  }
+}
+
+describe("job-runner — kumiko_job_last_success_timestamp_seconds", () => {
+  test("a successful run stamps the gauge, a failing run leaves no series", async () => {
+    const meter = createPrometheusMeter();
+    registerStandardMetrics(meter);
+
+    await withRunner(meter, async (runner, failures) => {
+      const before = Date.now() / 1000;
+      await runner.dispatch(SUCCEEDS, {});
+      await waitFor(() => slotFor(meter, SUCCEEDS) !== undefined);
+
+      const stamped = slotFor(meter, SUCCEEDS) as { value: number };
+      expect(stamped.value).toBeGreaterThanOrEqual(before);
+      expect(stamped.value).toBeLessThanOrEqual(Date.now() / 1000 + 1);
+
+      // Separate job name, so the "failure must not stamp" assertion cannot
+      // pass just because a prior success left a value inside the same second.
+      await runner.dispatch(FAILS, {});
+      await waitFor(() => failures.includes(FAILS));
+      expect(slotFor(meter, FAILS)).toBeUndefined();
+    });
+  });
+
+  test("a later success advances the stamp", async () => {
+    const meter = createPrometheusMeter();
+    registerStandardMetrics(meter);
+
+    await withRunner(meter, async (runner) => {
+      await runner.dispatch(SUCCEEDS, {});
+      await waitFor(() => slotFor(meter, SUCCEEDS) !== undefined);
+      const first = (slotFor(meter, SUCCEEDS) as { value: number }).value;
+
+      await runner.dispatch(SUCCEEDS, {});
+      await waitFor(() => (slotFor(meter, SUCCEEDS) as { value: number }).value > first, {
+        delays: [250, 1000, 3000],
+      });
+      expect((slotFor(meter, SUCCEEDS) as { value: number }).value).toBeGreaterThan(first);
+    });
+  });
+
+  test("the stamp reaches the real /metrics scrape output", async () => {
+    const meter = createPrometheusMeter();
+    registerStandardMetrics(meter);
+
+    await withRunner(meter, async (runner) => {
+      await runner.dispatch(SUCCEEDS, {});
+      await waitFor(() => slotFor(meter, SUCCEEDS) !== undefined);
+
+      // Same meter instance the runner wrote into — that sharing is what
+      // buildServer + job-runner do in a real process (fw#1046).
+      const { app } = buildServer({
+        registry: createRegistry([livenessFeature]),
+        context: {},
+        jwtSecret: JWT,
+        observability: { ...createNoopProvider(), meter },
+        metrics: {},
+      });
+      const res = await app.request("/metrics");
+      expect(res.status).toBe(200);
+      const body = await res.text();
+      expect(body).toContain("# TYPE kumiko_job_last_success_timestamp_seconds gauge");
+      expect(body).toContain(`kumiko_job_last_success_timestamp_seconds{job="${SUCCEEDS}"} `);
+    });
+  });
+});

package/src/jobs/index.ts

@@ -1,2 +1,8 @@
-export type { JobLogEntry, JobMeta, JobRunner, JobRunnerOptions } from "./job-runner";
+export type {
+  JobLogEntry,
+  JobMeta,
+  JobOutcomeMeta,
+  JobRunner,
+  JobRunnerOptions,
+} from "./job-runner";
 export { createJobRunner } from "./job-runner";