@cosmicdrift/kumiko-bundled-features 0.174.0 → 0.176.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.174.0",
+  "version": "0.176.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -104,12 +104,10 @@
     "./personal-access-tokens/web": "./src/personal-access-tokens/web/index.ts",
     "./feature-toggles": "./src/feature-toggles/index.ts",
     "./feature-toggles/web": "./src/feature-toggles/web/index.ts",
-    "./text-content": "./src/text-content/index.ts",
-    "./text-content/seeding": "./src/text-content/seeding.ts",
-    "./text-content/web": "./src/text-content/web/index.ts",
     "./template-resolver": "./src/template-resolver/index.ts",
     "./template-resolver/seeding": "./src/template-resolver/seeding.ts",
     "./template-resolver/testing": "./src/template-resolver/testing.ts",
+    "./template-resolver/web": "./src/template-resolver/web/index.ts",
     "./renderer-foundation": "./src/renderer-foundation/index.ts",
     "./legal-pages": "./src/legal-pages/index.ts",
     "./legal-pages/web": "./src/legal-pages/web/index.ts",
@@ -122,12 +120,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.174.0",
-    "@cosmicdrift/kumiko-framework": "0.174.0",
-    "@cosmicdrift/kumiko-headless": "0.174.0",
-    "@cosmicdrift/kumiko-renderer": "0.174.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.174.0",
-    "@cosmicdrift/kumiko-types": "0.174.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.176.0",
+    "@cosmicdrift/kumiko-framework": "0.176.0",
+    "@cosmicdrift/kumiko-headless": "0.176.0",
+    "@cosmicdrift/kumiko-renderer": "0.176.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.176.0",
+    "@cosmicdrift/kumiko-types": "0.176.0",
     "@mollie/api-client": "^4.5.0",
     "imapflow": "^1.3.3",
     "mailparser": "^3.9.8",

package/src/__tests__/boot-seed-contract.integration.test.ts

@@ -17,17 +17,21 @@ import {
   tenantComplianceProfileTable,
 } from "../compliance-profiles/schema/profile-selection";
 import { seedComplianceProfile } from "../compliance-profiles/seeding";
-import { createTextContentFeature } from "../text-content/feature";
-import { seedTextBlock } from "../text-content/seeding";
-import { type TextBlockRow, textBlockEntity, textBlocksTable } from "../text-content/table";
+import { createTemplateResolverFeature } from "../template-resolver/feature";
+import { seedTextBlock } from "../template-resolver/seeding";
+import {
+  type TemplateResourceRow,
+  templateResourceEntity,
+  templateResourcesTable,
+} from "../template-resolver/table";
 
 let stack: TestStack;
 
 beforeAll(async () => {
   stack = await setupTestStack({
-    features: [createTextContentFeature(), createComplianceProfilesFeature()],
+    features: [createTemplateResolverFeature(), createComplianceProfilesFeature()],
   });
-  await unsafeCreateEntityTable(stack.db, textBlockEntity);
+  await unsafeCreateEntityTable(stack.db, templateResourceEntity);
   await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
   await createEventsTable(stack.db);
 });
@@ -43,32 +47,32 @@ describe("boot-seed contract", () => {
     await seedTextBlock(stack.db, {
       tenantId,
       slug: "imprint",
-      lang: "de",
+      locale: "de",
       title: "Impressum",
-      body: "seed body",
+      content: "seed body",
     });
     await seedTextBlock(stack.db, {
       tenantId,
       slug: "imprint",
-      lang: "de",
+      locale: "de",
       title: "Impressum (edited)",
-      body: "admin body",
+      content: "admin body",
       ifExists: "update",
     });
     await seedTextBlock(stack.db, {
       tenantId,
       slug: "imprint",
-      lang: "de",
+      locale: "de",
       title: "Impressum",
-      body: "seed body",
+      content: "seed body",
     });
 
-    const row = await fetchOne<TextBlockRow>(stack.db, textBlocksTable, {
+    const row = await fetchOne<TemplateResourceRow>(stack.db, templateResourcesTable, {
       tenantId,
       slug: "imprint",
-      lang: "de",
+      locale: "de",
     });
-    expect(row).toMatchObject({ title: "Impressum (edited)", body: "admin body", version: 2 });
+    expect(row).toMatchObject({ title: "Impressum (edited)", content: "admin body", version: 2 });
 
     const events = await selectMany(stack.db, eventsTable, { aggregateId: String(row!.id) });
     expect(events).toHaveLength(2);

package/src/auth-email-password/__tests__/login-gates.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import { USER_STATUS } from "../../user";
 import type { AuthUserRow } from "../auth-user-row";
+import { accountRestricted, emailNotVerified, invalidCredentials } from "../errors";
 import {
   gateBuildSession,
   gateEnforceAccountStatus,
@@ -21,7 +22,7 @@ describe("login.write gates (fw#1284)", () => {
   test("gateEnforceEmailVerified rejects when strict and unverified", () => {
     const g = gateEnforceEmailVerified(row({ emailVerified: false }), true);
     expect(g.ok).toBe(false);
-    if (!g.ok) expect(g.result.isSuccess).toBe(false);
+    if (!g.ok) expect(g.result).toEqual(emailNotVerified());
   });
 
   test("gateEnforceEmailVerified passes when not strict", () => {
@@ -31,16 +32,21 @@ describe("login.write gates (fw#1284)", () => {
   test("gateEnforceAccountStatus rejects restricted", () => {
     const g = gateEnforceAccountStatus(row({ status: USER_STATUS.Restricted }));
     expect(g.ok).toBe(false);
+    if (!g.ok) expect(g.result).toEqual(accountRestricted());
   });
 
   test("gateEnforceAccountStatus rejects deletion_requested as invalid_creds shape", () => {
     const g = gateEnforceAccountStatus(row({ status: USER_STATUS.DeletionRequested }));
     expect(g.ok).toBe(false);
-    if (!g.ok) {
-      expect(g.result.isSuccess).toBe(false);
-      // anti-enumeration — same family as invalid credentials
-      expect(g.result).toMatchObject({ isSuccess: false });
-    }
+    // anti-enumeration — same payload as invalid credentials, not a
+    // distinguishable "account deleted" error.
+    if (!g.ok) expect(g.result).toEqual(invalidCredentials());
+  });
+
+  test("gateEnforceAccountStatus rejects deleted as invalid_creds shape", () => {
+    const g = gateEnforceAccountStatus(row({ status: USER_STATUS.Deleted }));
+    expect(g.ok).toBe(false);
+    if (!g.ok) expect(g.result).toEqual(invalidCredentials());
   });
 
   test("gateEnforceAccountStatus passes active", () => {

package/src/auth-email-password/seeding.ts

@@ -190,8 +190,10 @@ export type SeedAdminOptions = {
    *  membership-Rollen. Typischer use-case: `["SystemAdmin"]` für
    *  einen Plattform-Operator. Default: leer. */
   readonly globalRoles?: readonly string[];
-  /** Initial-emailVerified-Flag — Default false (unverified),
-   *  gleicher Mechanismus wie seedUserWithPassword.emailVerified. */
+  /** Initial emailVerified state — defaults to false (unverified). Same
+   *  mechanism as seedUserWithPassword.emailVerified. Re-running the seed
+   *  against an already-seeded row reconciles this flag too (true → sets
+   *  it via a real `.updated` event; never flips true → false). */
   readonly emailVerified?: boolean;
   readonly by?: SessionUser;
 };

package/src/auth-mfa/__tests__/token-secrets.test.ts

@@ -30,6 +30,25 @@ describe("resolveMfaTokenSecrets", () => {
     );
   });
 
+  test("an empty-string override falls back to derivation instead of an empty key", () => {
+    const resolved = resolveMfaTokenSecrets(JWT_SECRET, {
+      setupTokenSecret: "",
+      challengeTokenSecret: "",
+    });
+
+    expect(resolved).toEqual(resolveMfaTokenSecrets(JWT_SECRET));
+    expect(resolved.setupTokenSecret).not.toBe("");
+  });
+
+  test("a whitespace-only override falls back to derivation too", () => {
+    const resolved = resolveMfaTokenSecrets(JWT_SECRET, {
+      setupTokenSecret: "   ",
+      challengeTokenSecret: "\t",
+    });
+
+    expect(resolved).toEqual(resolveMfaTokenSecrets(JWT_SECRET));
+  });
+
   test("rotating the master rotates both", () => {
     const before = resolveMfaTokenSecrets(JWT_SECRET);
     const after = resolveMfaTokenSecrets(`${JWT_SECRET}-rotated`);

package/src/auth-mfa/handlers/reencrypt.job.ts

@@ -38,8 +38,12 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
-import { type EnvelopeCipher, isStoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
-import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  type ChunkedMigrationStopReason,
+  classifyStoredEnvelope,
+  runChunkedMigration,
+} from "../../shared";
 import { userMfaEntity, userMfaTable } from "../schema/user-mfa";
 
 const DEFAULT_BATCH_SIZE = 100;
@@ -66,22 +70,6 @@ export type MfaReencryptJobResult = {
   readonly stoppedReason: ChunkedMigrationStopReason;
 };
 
-type EnvelopeClassification = "rotate" | "current" | "unrecognized";
-
-// After PII peel (when configured), values must be current-cipher envelopes.
-// Non-JSON / non-envelope is not a supported legacy decrypt path — fail the
-// row instead of treating it as "needs rotate" (#1541, mirrors config #1513).
-function classifyEnvelope(value: string, targetVersion: number): EnvelopeClassification {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    return "unrecognized";
-  }
-  if (!isStoredEnvelope(parsed)) return "unrecognized";
-  return parsed.kekVersion === targetVersion ? "current" : "rotate";
-}
-
 export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
   const payload = rawPayload as MfaReencryptJobPayload; // @cast-boundary engine-payload
   const maybeCipher = configuredEntityFieldEncryption();
@@ -166,8 +154,11 @@ export const mfaReencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<vo
       envelopeValues = unwrapped as { totpSecret: string; recoveryCodes: string }; // @cast-boundary engine-payload
     }
 
-    const totpClass = classifyEnvelope(envelopeValues.totpSecret, targetVersion);
-    const recoveryClass = classifyEnvelope(envelopeValues.recoveryCodes, targetVersion);
+    // After PII peel (when configured), values must be current-cipher
+    // envelopes — non-JSON/non-envelope is not a supported legacy decrypt
+    // path (#1541, mirrors config #1513).
+    const totpClass = classifyStoredEnvelope(envelopeValues.totpSecret, targetVersion);
+    const recoveryClass = classifyStoredEnvelope(envelopeValues.recoveryCodes, targetVersion);
     if (totpClass === "unrecognized" || recoveryClass === "unrecognized") {
       ctx.log?.warn?.(
         `[auth-mfa:reencrypt] row ${row.id} has a field that is not a current-cipher envelope, not re-encryptable`,

package/src/auth-mfa/token-secrets.ts

@@ -10,19 +10,19 @@ export type ResolvedMfaTokenSecrets = {
   readonly challengeTokenSecret: string;
 };
 
-// The two HKDF purposes auth-mfa needs. They live here rather than at each
-// call site because an app typically resolves them twice — once in the prod
-// entrypoint against a validated JWT_SECRET, once in the dev server against
-// its fallback — and a purpose string that drifts between those two files
-// invalidates every token issued by the other.
-//
-// Setup and challenge stay separate on purpose: a setup token proves "this
-// user is enrolling a factor", a challenge token proves "this user passed
-// step one of login". Sharing one key would let the first be replayed as the
-// second.
+// Shared here (not per call site) so the purpose string can't drift between
+// prod/dev entrypoints. Setup and challenge stay separate: sharing one key
+// would let a setup token be replayed as a login-challenge token.
 const SETUP_TOKEN_PURPOSE = "mfa-setup-token-v1";
 const CHALLENGE_TOKEN_PURPOSE = "mfa-challenge-token-v1";
 
+// A blank or whitespace-only override is treated as absent — an empty env
+// var (MFA_SETUP_TOKEN_SECRET="") must fall back to derivation, not sign
+// tokens with an empty/near-empty HMAC key (fw#1623).
+function resolveSecret(override: string | undefined, fallback: () => string): string {
+  return override !== undefined && override.trim() !== "" ? override : fallback();
+}
+
 /** Derives both MFA token secrets from the app's master secret. Pass explicit
  *  overrides only when a deployment needs its own key for one of them —
  *  otherwise deriving keeps a single env var authoritative. */
@@ -31,9 +31,11 @@ export function resolveMfaTokenSecrets(
   overrides: MfaTokenSecretOverrides = {},
 ): ResolvedMfaTokenSecrets {
   return {
-    setupTokenSecret:
-      overrides.setupTokenSecret ?? derivePurposeSecret(masterSecret, SETUP_TOKEN_PURPOSE),
-    challengeTokenSecret:
-      overrides.challengeTokenSecret ?? derivePurposeSecret(masterSecret, CHALLENGE_TOKEN_PURPOSE),
+    setupTokenSecret: resolveSecret(overrides.setupTokenSecret, () =>
+      derivePurposeSecret(masterSecret, SETUP_TOKEN_PURPOSE),
+    ),
+    challengeTokenSecret: resolveSecret(overrides.challengeTokenSecret, () =>
+      derivePurposeSecret(masterSecret, CHALLENGE_TOKEN_PURPOSE),
+    ),
   };
 }

package/src/billing-foundation/subscription-tier-sync.ts

@@ -116,9 +116,16 @@ export function createSubscriptionTierSync<TTier extends string>(
           tenantId: targetTenantId,
         });
         if (!result.isSuccess) return result;
+        // The primary write already committed — a webhook caller (Stripe/
+        // PayPal) that sees isSuccess:false here retries the whole event,
+        // re-running an already-succeeded side effect. Log the tier-sync
+        // failure instead of masking the primary write's success.
         const syncError = await syncTierFromSubscription(targetTenantId);
         if (syncError) {
-          return { isSuccess: false, error: syncError };
+          // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
+          console.warn(
+            `[subscription-tier-sync] tier sync failed for tenant ${targetTenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
+          );
         }
         return result;
       },

package/src/cap-counter/__tests__/stock-cap-guard.integration.test.ts

@@ -0,0 +1,98 @@
+// Regression test for the tenant-scope override bug: checkStockCap used to
+// spread `spec.where` AFTER the injected `tenantId`, so a `where` object
+// carrying its own `tenantId` key silently overrode the caller's real tenant
+// and the count ran against the wrong tenant's rows.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { createEntityExecutor, type SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { resetTestTables } from "@cosmicdrift/kumiko-framework/testing";
+import { capCounterEntity } from "../entity";
+import { createStockCapGuard } from "../stock-cap-guard";
+
+const { executor, table: capCounterTable } = createEntityExecutor("cap-counter", capCounterEntity);
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  db = stack.db;
+  await unsafeCreateEntityTable(db, capCounterEntity, "cap-counter");
+  await createEventsTable(db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await resetTestTables(db, [capCounterTable, eventsTable]);
+});
+
+function seedUser(tenantId: ReturnType<typeof testTenantId>): SessionUser {
+  return { id: "seed-user", tenantId, roles: ["SystemAdmin"] };
+}
+
+async function seedCounterRow(tenantId: ReturnType<typeof testTenantId>): Promise<void> {
+  const result = await executor.create(
+    { tenantId, capName: "x", value: 0, periodStart: "2026-07-01T00:00:00Z" },
+    seedUser(tenantId),
+    createTenantDb(db, tenantId),
+  );
+  if (!result.isSuccess) throw new Error(`seed failed: ${JSON.stringify(result)}`);
+}
+
+describe("checkStockCap tenant scoping", () => {
+  test("spec.where cannot override the caller's real tenantId", async () => {
+    const realTenant = testTenantId(1);
+    const otherTenant = testTenantId(2);
+
+    // 5 rows live under otherTenant — realTenant has none.
+    for (let i = 0; i < 5; i++) {
+      await seedCounterRow(otherTenant);
+    }
+
+    const guard = createStockCapGuard(async () => ({}));
+    const failure = await guard.checkStockCap(db, realTenant, {
+      table: capCounterTable,
+      limit: () => 1,
+      // A where object that (accidentally or maliciously) carries its own
+      // tenantId must NOT be able to redirect the count to another tenant.
+      where: { tenantId: otherTenant, capName: "x" },
+      code: "cap-exceeded",
+      i18nKey: "cap.exceeded",
+      field: "capName",
+    });
+
+    // realTenant has zero matching rows — must not see otherTenant's 5.
+    expect(failure).toBeNull();
+  });
+
+  test("still enforces the cap for the caller's own tenant", async () => {
+    const tenant = testTenantId(1);
+    for (let i = 0; i < 2; i++) {
+      await seedCounterRow(tenant);
+    }
+
+    const guard = createStockCapGuard(async () => ({}));
+    const failure = await guard.checkStockCap(db, tenant, {
+      table: capCounterTable,
+      limit: () => 1,
+      where: { capName: "x" },
+      code: "cap-exceeded",
+      i18nKey: "cap.exceeded",
+      field: "capName",
+    });
+
+    expect(failure).not.toBeNull();
+  });
+});

package/src/cap-counter/stock-cap-guard.ts

@@ -39,7 +39,7 @@ export function createStockCapGuard<TCaps>(
     spec: StockCapSpec<TCaps>,
   ): Promise<WriteFailure | null> {
     const caps = await resolveTierCaps(db, tenantId);
-    const current = await countWhere(db, spec.table, { tenantId, ...spec.where });
+    const current = await countWhere(db, spec.table, { ...spec.where, tenantId });
     const { state, limit } = enforceStockCap({
       current,
       limit: spec.limit(caps),

package/src/config/handlers/reencrypt.job.ts

@@ -25,8 +25,12 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
-import { type EnvelopeCipher, isStoredEnvelope } from "@cosmicdrift/kumiko-framework/secrets";
-import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared";
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-framework/secrets";
+import {
+  type ChunkedMigrationStopReason,
+  classifyStoredEnvelope,
+  runChunkedMigration,
+} from "../../shared";
 import { configValueEntity, configValuesTable } from "../table";
 
 const DEFAULT_MAX_FAILURES = 10;
@@ -49,21 +53,6 @@ export type ReencryptJobResult = {
   readonly stoppedReason: ChunkedMigrationStopReason;
 };
 
-type RowClassification = "rotate" | "current" | "unrecognized";
-
-function classifyRow(value: string, targetVersion: number): RowClassification {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    // not JSON at all — no supported format decrypts this; let
-    // cipher.decrypt reject it and count the row as failed.
-    return "unrecognized";
-  }
-  if (!isStoredEnvelope(parsed)) return "unrecognized";
-  return parsed.kekVersion === targetVersion ? "current" : "rotate";
-}
-
 export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
   const payload = rawPayload as ReencryptJobPayload; // @cast-boundary engine-payload
   const maybeCipher = ctx.configEncryption;
@@ -148,7 +137,7 @@ export const reencryptJob: JobHandlerFn = async (rawPayload, ctx): Promise<void>
 
   async function migrateRow(row: ConfigRow): Promise<"migrated" | "skipped" | "failed"> {
     if (row.value === null || row.value === undefined) return "skipped";
-    const classification = classifyRow(row.value, targetVersion);
+    const classification = classifyStoredEnvelope(row.value, targetVersion);
     if (classification === "current") {
       alreadyCurrent++;
       return "skipped";

package/src/delivery/delivery-service.ts

@@ -488,7 +488,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             tenantId,
             notificationType,
             channel: "*",
-            recipientId: null,
+            recipientId: options.recipientId ?? null,
             recipientAddress: null,
             status: "skipped",
             error: "duplicate_idempotency_key",

package/src/document-ingest-foundation/__tests__/feature.integration.test.ts

@@ -89,6 +89,14 @@ async function loadIngestRequestedEvents(): Promise<{ payload: Record<string, un
   return rows as { payload: Record<string, unknown> }[];
 }
 
+async function loadIngestSkippedEvents(): Promise<{ payload: Record<string, unknown> }[]> {
+  const rows = await asRawClient(stack.db).unsafe(
+    `SELECT payload FROM kumiko_events WHERE type = $1`,
+    ["document-ingest-foundation:event:document-ingest-skipped"],
+  );
+  return rows as { payload: Record<string, unknown> }[];
+}
+
 describe("fileRef.created → documentIngest.requested", () => {
   test("PDF upload requests ingest with the fileRef pointer, no binary", async () => {
     const { id, storageKey } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
@@ -97,12 +105,13 @@ describe("fileRef.created → documentIngest.requested", () => {
 
     const rows = await loadIngestRequestedEvents();
     expect(rows).toHaveLength(1);
-    const payload = rows[0]?.payload;
-    expect(payload?.["fileRefId"]).toBe(id);
-    expect(payload?.["storageKey"]).toBe(storageKey);
-    expect(payload?.["mimeType"]).toBe("application/pdf");
-    expect(payload?.["data"]).toBeUndefined();
-    expect(payload?.["binary"]).toBeUndefined();
+    expect(rows[0]?.payload).toEqual({
+      fileRefId: id,
+      storageKey,
+      fileName: "invoice.pdf",
+      mimeType: "application/pdf",
+      size: pdfBytes.length,
+    });
   });
 
   test("image/png upload also requests ingest (Phase-1 mime allowlist)", async () => {
@@ -113,19 +122,32 @@ describe("fileRef.created → documentIngest.requested", () => {
     expect(await loadIngestRequestedEvents()).toHaveLength(1);
   });
 
-  test("unsupported mime type is skipped — no ingest requested", async () => {
-    await uploadFile("notes.txt", textBytes, "text/plain");
+  test("unsupported mime type is skipped — no ingest requested, skip is observable", async () => {
+    const { id, storageKey } = await uploadFile("notes.txt", textBytes, "text/plain");
 
     await stack.eventDispatcher?.runOnce();
 
     expect(await loadIngestRequestedEvents()).toHaveLength(0);
+    const skipped = await loadIngestSkippedEvents();
+    expect(skipped).toHaveLength(1);
+    // mimeType not pinned exactly: the upload route/File API append a
+    // charset suffix ("text/plain;charset=utf-8") that isn't this MSP's
+    // concern — the allowlist-miss is.
+    expect(skipped[0]?.payload).toMatchObject({
+      fileRefId: id,
+      storageKey,
+      fileName: "notes.txt",
+      reason: "unsupported-mime-type",
+    });
+    expect(String(skipped[0]?.payload["mimeType"])).toStartWith("text/plain");
   });
 
-  test("oversized file is skipped before the mime check — no ingest requested", async () => {
+  test("oversized file is skipped before the mime check — no ingest requested, skip is observable", async () => {
     // Real uploads can't exceed file-routes.ts' 10mb unconstrained-upload
     // default, well below this feature's 25mb domain cap — so an oversized
     // fileRef.created is inserted directly (bypassing the upload route) to
     // prove the MSP's own size-check fires independently of it.
+    const oversizedSize = 26 * 1024 * 1024;
     await asRawClient(stack.db).unsafe(
       `
       INSERT INTO kumiko_events
@@ -142,9 +164,13 @@ describe("fileRef.created → documentIngest.requested", () => {
           storageKey: "huge.pdf",
           fileName: "huge.pdf",
           mimeType: "application/pdf",
-          size: 26 * 1024 * 1024,
+          size: oversizedSize,
         }),
-        "{}",
+        // MSP-apply's ctx.unsafeAppendEvent stamps the new event's actor from
+        // the TRIGGERING event's metadata.userId (server.ts) — an empty
+        // metadata object here leaves it undefined and the skip-event insert
+        // rejects with "UNDEFINED_VALUE".
+        JSON.stringify({ userId: admin.id }),
         admin.id,
       ],
     );
@@ -152,5 +178,15 @@ describe("fileRef.created → documentIngest.requested", () => {
     await stack.eventDispatcher?.runOnce();
 
     expect(await loadIngestRequestedEvents()).toHaveLength(0);
+    const skipped = await loadIngestSkippedEvents();
+    expect(skipped).toHaveLength(1);
+    expect(skipped[0]?.payload).toEqual({
+      fileRefId: "00000000-0000-4000-8000-0000000000ff",
+      storageKey: "huge.pdf",
+      fileName: "huge.pdf",
+      mimeType: "application/pdf",
+      size: oversizedSize,
+      reason: "file-too-large",
+    });
   });
 });

package/src/document-ingest-foundation/__tests__/feature.test.ts

@@ -7,7 +7,7 @@
 import { describe, expect, test } from "bun:test";
 import { EXT_TENANT_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import { documentExtractEntity } from "../entity";
-import { DOCUMENT_INGEST_REQUESTED_EVENT_QN } from "../events";
+import { DOCUMENT_INGEST_REQUESTED_EVENT_QN, DOCUMENT_INGEST_SKIPPED_EVENT_QN } from "../events";
 import { documentIngestFoundationFeature } from "../feature";
 
 describe("documentIngestFoundationFeature — shape", () => {
@@ -64,9 +64,10 @@ describe("documentIngestFoundationFeature — shape", () => {
     expect(Object.keys(documentIngestFoundationFeature.queryHandlers)).toHaveLength(0);
   });
 
-  test("registers the documentIngest.requested event under the exported QN", () => {
+  test("registers the documentIngest.requested and documentIngest.skipped events under their exported QNs", () => {
     expect(Object.keys(documentIngestFoundationFeature.events)).toEqual([
       "documentIngest.requested",
+      "documentIngest.skipped",
     ]);
     // The registry qualifies short → QN via qn(toKebab(feature), "event",
     // toKebab(short)) — pin the hand-written DOCUMENT_INGEST_REQUESTED_EVENT_QN
@@ -77,6 +78,9 @@ describe("documentIngestFoundationFeature — shape", () => {
     expect(documentIngestFoundationFeature.events["documentIngest.requested"]?.name).toBe(
       DOCUMENT_INGEST_REQUESTED_EVENT_QN,
     );
+    expect(documentIngestFoundationFeature.events["documentIngest.skipped"]?.name).toBe(
+      DOCUMENT_INGEST_SKIPPED_EVENT_QN,
+    );
   });
 
   test("registers the fileRef.created MSP", () => {

package/src/document-ingest-foundation/events.ts

@@ -23,3 +23,18 @@ export const documentIngestRequestedPayloadSchema = z.object({
   size: z.number().int().min(0),
 });
 export type DocumentIngestRequestedPayload = z.infer<typeof documentIngestRequestedPayloadSchema>;
+
+export const DOCUMENT_INGEST_SKIPPED_EVENT_SHORT = "documentIngest.skipped" as const;
+
+export const DOCUMENT_INGEST_SKIPPED_EVENT_QN =
+  "document-ingest-foundation:event:document-ingest-skipped" as const;
+
+export const documentIngestSkippedPayloadSchema = z.object({
+  fileRefId: z.string().min(1),
+  storageKey: z.string().min(1),
+  fileName: z.string().min(1),
+  mimeType: z.string().min(1),
+  size: z.number().int().min(0),
+  reason: z.enum(["file-too-large", "unsupported-mime-type"]),
+});
+export type DocumentIngestSkippedPayload = z.infer<typeof documentIngestSkippedPayloadSchema>;