@cosmicdrift/kumiko-bundled-features 1.0.0 → 2.0.0

package/src/delivery/i18n.ts

@@ -0,0 +1,6 @@
+type LocalizedString = { readonly de: string; readonly en: string };
+
+export const DELIVERY_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:delivery-log.title": { de: "Delivery-Log", en: "Delivery log" },
+  "delivery:nav.deliveryLog": { de: "Zustellungen", en: "Delivery" },
+};

package/src/delivery/index.ts

@@ -1,6 +1,7 @@
 export type { DeliveryStatusValue } from "./constants";
 export {
   DELIVERY_FEATURE,
+  DELIVERY_LOG_SCREEN_ID,
   DeliveryErrors,
   DeliveryHandlers,
   DeliveryJobs,
@@ -15,7 +16,11 @@ export {
   type RateLimitConfig,
 } from "./delivery-service";
 export { createDeliveryFeature } from "./feature";
-export { deliveryAttemptsTable, notificationPreferencesTable } from "./tables";
+export {
+  deliveryAttemptsTable,
+  notificationPreferenceEntity,
+  notificationPreferencesTable,
+} from "./tables";
 export { type CreateDeliveryTestContextOptions, createDeliveryTestContext } from "./testing";
 export type {
   ChannelContext,

package/src/delivery/public-names.ts

@@ -0,0 +1,36 @@
+// @runtime client
+// String-only delivery QNs and screen ids — safe for client bundles.
+
+export const DELIVERY_FEATURE = "delivery" as const;
+
+export const DeliveryHandlers = {
+  setPreference: "delivery:write:set-preference",
+} as const;
+
+export const DeliveryQueries = {
+  log: "delivery:query:log",
+  preferences: "delivery:query:preferences",
+} as const;
+
+export const DELIVERY_LOG_SCREEN_ID = "delivery-log" as const;
+
+export const DeliveryErrors = {
+  noRecipient: "delivery_no_recipient",
+  channelFailed: "delivery_channel_failed",
+} as const;
+
+export const DeliveryStatus = {
+  queued: "queued",
+  sent: "sent",
+  failed: "failed",
+  skipped: "skipped",
+} as const;
+
+export type DeliveryStatusValue = (typeof DeliveryStatus)[keyof typeof DeliveryStatus];
+
+export const DELIVERY_ATTEMPT_EVENT = "delivery:event:attempt" as const;
+
+export const DeliveryJobNames = {
+  render: "render",
+  send: "send",
+} as const;

package/src/delivery/tables.ts

@@ -28,7 +28,7 @@ import {
 // PK = event aggregate-id (uuid). Keeps the projection row linked back to
 // its event stream 1:1 — same convention as jobRunsTable + tenantSecretsTable.
 // Event replays stay idempotent (primary-key conflict instead of duplicate rows).
-export const deliveryAttemptsTable = pgTable("read_delivery_attempts", {
+export const deliveryAttemptsTable = pgTable("store_delivery_attempts", {
   id: uuid("id").primaryKey(),
   tenantId: uuid("tenant_id").notNull(),
   notificationType: text("notification_type").notNull(),
@@ -53,7 +53,7 @@ export const deliveryAttemptsTable = pgTable("read_delivery_attempts", {
 // pgTable bleibt source-of-truth für Query-API; Phase 4 leitet das pgTable
 // aus dieser Meta ab.
 export const deliveryAttemptsTableMeta: EntityTableMeta = defineUnmanagedTable({
-  tableName: "read_delivery_attempts",
+  tableName: "store_delivery_attempts",
   columns: [
     { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
     { name: "tenant_id", pgType: "uuid", notNull: true },
@@ -76,7 +76,7 @@ export const deliveryAttemptsTableMeta: EntityTableMeta = defineUnmanagedTable({
 export const notificationPreferenceEntity = createEntity({
   table: "read_notification_preferences",
   fields: {
-    userId: createTextField({ required: true }),
+    userId: createTextField({ required: true, allowPlaintext: "pseudonymous-fk" }),
     notificationType: createTextField({ required: true }), // qualified name or "*"
     channel: createTextField({ required: true }), // "inApp", "email", "push", or "*"
     enabled: createBooleanField({ default: true }),

package/src/delivery/web/client-plugin.tsx

@@ -0,0 +1,20 @@
+// @runtime client
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { DELIVERY_FEATURE, DELIVERY_LOG_SCREEN_ID } from "../public-names";
+import { DeliveryLogScreen } from "./delivery-log-screen";
+import { defaultTranslations } from "./i18n";
+
+export type DeliveryClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function deliveryClient(options?: DeliveryClientOptions): ClientFeatureDefinition {
+  return {
+    name: DELIVERY_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    components: {
+      [DELIVERY_LOG_SCREEN_ID]: DeliveryLogScreen,
+    },
+  };
+}

package/src/delivery/web/delivery-log-screen.tsx

@@ -0,0 +1,103 @@
+// @runtime client
+import { useDispatcher, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { FormScreenShell } from "@cosmicdrift/kumiko-renderer-web";
+import { type ReactNode, useCallback, useEffect, useState } from "react";
+import { DeliveryQueries } from "../public-names";
+
+type DeliveryRow = {
+  readonly id: string;
+  readonly notificationType: string;
+  readonly channel: string;
+  readonly recipientAddress: string | null;
+  readonly status: string;
+  readonly error: string | null;
+};
+
+type DeliveryLogResponse = {
+  readonly rows: readonly DeliveryRow[];
+};
+
+type State =
+  | { readonly kind: "loading" }
+  | { readonly kind: "error"; readonly message: string }
+  | { readonly kind: "ready"; readonly rows: readonly DeliveryRow[] };
+
+export function DeliveryLogScreen(): ReactNode {
+  const t = useTranslation();
+  const { Banner, Card, DataTable, Heading, Text } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const [state, setState] = useState<State>({ kind: "loading" });
+
+  const load = useCallback(async (): Promise<void> => {
+    setState({ kind: "loading" });
+    const res = await dispatcher.query<DeliveryLogResponse>(DeliveryQueries.log, { limit: 50 });
+    if (!res.isSuccess) {
+      setState({ kind: "error", message: res.error.message });
+      return;
+    }
+    setState({ kind: "ready", rows: res.data.rows });
+  }, [dispatcher]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  if (state.kind === "loading") {
+    return (
+      <FormScreenShell testId="delivery-log-screen">
+        <Text variant="small">{t("delivery.log.loading")}</Text>
+      </FormScreenShell>
+    );
+  }
+
+  if (state.kind === "error") {
+    return (
+      <FormScreenShell testId="delivery-log-screen">
+        <Banner variant="error">{state.message}</Banner>
+      </FormScreenShell>
+    );
+  }
+
+  return (
+    <FormScreenShell testId="delivery-log-screen" maxWidth="4xl" className="flex flex-col gap-6">
+      <Heading variant="page">{t("delivery.log.title")}</Heading>
+
+      <Card options={{ padded: false }}>
+        <DataTable
+          testId="delivery-log-table"
+          columns={[
+            { field: "type", label: t("delivery.log.col.type"), type: "string", sortable: false },
+            {
+              field: "channel",
+              label: t("delivery.log.col.channel"),
+              type: "string",
+              sortable: false,
+            },
+            {
+              field: "recipient",
+              label: t("delivery.log.col.recipient"),
+              type: "string",
+              sortable: false,
+            },
+            {
+              field: "status",
+              label: t("delivery.log.col.status"),
+              type: "string",
+              sortable: false,
+            },
+          ]}
+          rows={state.rows.map((row) => ({
+            id: row.id,
+            values: {
+              type: row.notificationType,
+              channel: row.channel,
+              recipient: row.recipientAddress ?? "—",
+              status: row.error ? `${row.status} (${row.error})` : row.status,
+            },
+          }))}
+          emptyState={<Text variant="small">{t("delivery.log.empty")}</Text>}
+        />
+      </Card>
+    </FormScreenShell>
+  );
+}

package/src/delivery/web/i18n.ts

@@ -0,0 +1,25 @@
+// @runtime client
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "delivery.log.title": "Delivery-Log",
+    "delivery.log.loading": "Lade Zustellversuche…",
+    "delivery.log.empty": "Keine Zustellversuche.",
+    "delivery.log.col.type": "Typ",
+    "delivery.log.col.channel": "Kanal",
+    "delivery.log.col.recipient": "Empfänger",
+    "delivery.log.col.status": "Status",
+    "delivery:nav.deliveryLog": "Zustellungen",
+  },
+  en: {
+    "delivery.log.title": "Delivery log",
+    "delivery.log.loading": "Loading delivery attempts…",
+    "delivery.log.empty": "No delivery attempts.",
+    "delivery.log.col.type": "Type",
+    "delivery.log.col.channel": "Channel",
+    "delivery.log.col.recipient": "Recipient",
+    "delivery.log.col.status": "Status",
+    "delivery:nav.deliveryLog": "Delivery",
+  },
+};

package/src/delivery/web/index.ts

@@ -0,0 +1,3 @@
+// @runtime client
+export { type DeliveryClientOptions, deliveryClient } from "./client-plugin";
+export { DeliveryLogScreen } from "./delivery-log-screen";

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

@@ -0,0 +1,147 @@
+// document-ingest-foundation — fileRef.created MSP integration test.
+//
+// Proves the end-to-end trigger flow: upload → fileRef.created →
+// documentIngest.requested, gated on mime/size (files-post-processing
+// pattern, kumiko-framework#1497).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  createInMemoryFileProvider,
+  type InMemoryFileProvider,
+} from "@cosmicdrift/kumiko-framework/files";
+import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { createConfigFeature } from "../../config";
+import { documentIngestFoundationFeature } from "../feature";
+
+let stack: TestStack;
+let provider: InMemoryFileProvider;
+
+const admin = TestUsers.admin;
+
+const pdfBytes = new TextEncoder().encode("%PDF-1.4 minimal");
+const pngBytes = new Uint8Array([
+  0x89,
+  0x50,
+  0x4e,
+  0x47,
+  0x0d,
+  0x0a,
+  0x1a,
+  0x0a,
+  ...Array(64).fill(0),
+]);
+const textBytes = new TextEncoder().encode("plain text, not a supported mime type");
+
+beforeAll(async () => {
+  provider = createInMemoryFileProvider();
+  stack = await setupTestStack({
+    features: [createConfigFeature(), documentIngestFoundationFeature],
+    files: { storageProvider: provider },
+  });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  provider.clear();
+  stack.events.reset();
+  await asRawClient(stack.db).unsafe(
+    `TRUNCATE kumiko_events, kumiko_event_consumers, file_refs RESTART IDENTITY CASCADE`,
+  );
+  await stack.eventDispatcher?.ensureRegistered();
+});
+
+async function uploadFile(
+  fileName: string,
+  content: Uint8Array,
+  mimeType: string,
+): Promise<{ id: string; storageKey: string }> {
+  const token = await stack.jwt.sign(admin);
+  const formData = new FormData();
+  formData.append("file", new File([Buffer.from(content)], fileName, { type: mimeType }));
+  const res = await stack.app.request("/api/files", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+    body: formData,
+  });
+  expect(res.status).toBe(201);
+  const body = (await res.json()) as { id: string; storageKey: string };
+  return body;
+}
+
+async function loadIngestRequestedEvents(): 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-requested"],
+  );
+  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");
+
+    await stack.eventDispatcher?.runOnce();
+
+    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();
+  });
+
+  test("image/png upload also requests ingest (Phase-1 mime allowlist)", async () => {
+    await uploadFile("scan.png", pngBytes, "image/png");
+
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await loadIngestRequestedEvents()).toHaveLength(1);
+  });
+
+  test("unsupported mime type is skipped — no ingest requested", async () => {
+    await uploadFile("notes.txt", textBytes, "text/plain");
+
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await loadIngestRequestedEvents()).toHaveLength(0);
+  });
+
+  test("oversized file is skipped before the mime check — no ingest requested", 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.
+    await asRawClient(stack.db).unsafe(
+      `
+      INSERT INTO kumiko_events
+      (tenant_id, aggregate_type, aggregate_id, version, type, payload, metadata, created_at, created_by)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, now(), $8)
+      `,
+      [
+        admin.tenantId,
+        "fileRef",
+        "00000000-0000-4000-8000-0000000000ff",
+        1,
+        "fileRef.created",
+        JSON.stringify({
+          storageKey: "huge.pdf",
+          fileName: "huge.pdf",
+          mimeType: "application/pdf",
+          size: 26 * 1024 * 1024,
+        }),
+        "{}",
+        admin.id,
+      ],
+    );
+
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await loadIngestRequestedEvents()).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,105 @@
+// feature.ts contract tests — pin the public surface of the Phase-1
+// document-ingest-foundation skeleton: entity, tenant-config, the
+// fileRef.created MSP, and the documentIngest.requested event it defines.
+// End-to-end MSP behavior (mime/size validation, event payload) is covered
+// by feature.integration.test.ts.
+
+import { describe, expect, test } from "bun:test";
+import { documentExtractEntity } from "../entity";
+import { DOCUMENT_INGEST_REQUESTED_EVENT_QN } from "../events";
+import { documentIngestFoundationFeature } from "../feature";
+
+describe("documentIngestFoundationFeature — shape", () => {
+  test("has the expected name", () => {
+    expect(documentIngestFoundationFeature.name).toBe("document-ingest-foundation");
+  });
+
+  test("declares config as a hard requirement (tenant-config keys live there)", () => {
+    expect(documentIngestFoundationFeature.requires).toContain("config");
+  });
+
+  test("registers the documentExtract entity as an implicit projection", () => {
+    expect(Object.keys(documentIngestFoundationFeature.entities ?? {})).toEqual([
+      "documentExtract",
+    ]);
+  });
+
+  test("documentExtract entity pins table name, field set, and pages encryption (#1501)", () => {
+    expect(documentExtractEntity.table).toBe("read_document_extracts");
+    expect(Object.keys(documentExtractEntity.fields)).toEqual([
+      "fileRefId",
+      "storageKey",
+      "pages",
+      "meta",
+    ]);
+    expect(documentExtractEntity.fields.pages).toMatchObject({
+      type: "longText",
+      encrypted: true,
+    });
+    expect(documentExtractEntity.fields.meta).toMatchObject({ type: "jsonb" });
+  });
+
+  test("exports writeIngestPages / readIngestPages for the encrypted pages wire format (#1549)", async () => {
+    const { readIngestPages, writeIngestPages } = await import("../pages");
+    const pages = [{ pageNumber: 1, text: "x" }];
+    expect(readIngestPages(writeIngestPages(pages))).toEqual(pages);
+  });
+
+  test("registers NO write/query handlers — only entity, config, event, and MSP", () => {
+    expect(Object.keys(documentIngestFoundationFeature.writeHandlers)).toHaveLength(0);
+    expect(Object.keys(documentIngestFoundationFeature.queryHandlers)).toHaveLength(0);
+  });
+
+  test("registers the documentIngest.requested event under the exported QN", () => {
+    expect(Object.keys(documentIngestFoundationFeature.events)).toEqual([
+      "documentIngest.requested",
+    ]);
+    // The registry qualifies short → QN via qn(toKebab(feature), "event",
+    // toKebab(short)) — pin the hand-written DOCUMENT_INGEST_REQUESTED_EVENT_QN
+    // against what defineEvent actually registered, so a feature/short-name
+    // rename can't silently drift the two apart (kumiko-framework#1497: a
+    // stale QN fails MSP-apply at runtime with "event not registered", not
+    // at compile time).
+    expect(documentIngestFoundationFeature.events["documentIngest.requested"]?.name).toBe(
+      DOCUMENT_INGEST_REQUESTED_EVENT_QN,
+    );
+  });
+
+  test("registers the fileRef.created MSP", () => {
+    expect(Object.keys(documentIngestFoundationFeature.multiStreamProjections)).toEqual([
+      "request-ingest",
+    ]);
+    const msp = documentIngestFoundationFeature.multiStreamProjections["request-ingest"];
+    expect(Object.keys(msp?.apply ?? {})).toEqual(["fileRef.created"]);
+  });
+});
+
+describe("documentIngestFoundationFeature.exports — typed config handles", () => {
+  test("exposes ocrLanguage with the deu+eng default", () => {
+    const key = documentIngestFoundationFeature.exports.ocrLanguageConfigKey;
+    expect(key.name).toBe("document-ingest-foundation:config:ocr-language");
+    expect(documentIngestFoundationFeature.configKeys["ocrLanguage"]?.default).toBe("deu+eng");
+  });
+
+  test("exposes maxPagesPerFile with the 50-page default", () => {
+    const key = documentIngestFoundationFeature.exports.maxPagesPerFileConfigKey;
+    expect(key.name).toBe("document-ingest-foundation:config:max-pages-per-file");
+    expect(documentIngestFoundationFeature.configKeys["maxPagesPerFile"]?.default).toBe(50);
+  });
+
+  test("ocrLanguage rejects a value that isn't a Tesseract -l argument (#1501)", () => {
+    const pattern = documentIngestFoundationFeature.configKeys["ocrLanguage"]?.pattern;
+    expect(pattern).toBeDefined();
+    const re = new RegExp(pattern!.regex, pattern!.flags);
+    expect(re.test("deu+eng")).toBe(true);
+    expect(re.test("eng")).toBe(true);
+    expect(re.test("")).toBe(false);
+    expect(re.test("EU")).toBe(false);
+    expect(re.test("rm -rf /")).toBe(false);
+  });
+
+  test("maxPagesPerFile is bounded so a tenant can't disable or unbound the cap (#1501)", () => {
+    const bounds = documentIngestFoundationFeature.configKeys["maxPagesPerFile"]?.bounds;
+    expect(bounds).toEqual({ min: 1, max: 500 });
+  });
+});

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

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import type { IngestPage } from "../entity";
+import { readIngestPages, writeIngestPages } from "../pages";
+
+const SAMPLE: readonly IngestPage[] = [
+  { pageNumber: 1, text: "Hello" },
+  { pageNumber: 2, text: "World" },
+];
+
+describe("writeIngestPages / readIngestPages", () => {
+  test("round-trips an IngestPage[] through the longText wire format", () => {
+    const raw = writeIngestPages(SAMPLE);
+    expect(typeof raw).toBe("string");
+    expect(readIngestPages(raw)).toEqual([...SAMPLE]);
+  });
+
+  test("writeIngestPages emits JSON an encrypted longText field can store", () => {
+    expect(writeIngestPages([])).toBe("[]");
+    expect(JSON.parse(writeIngestPages(SAMPLE))).toEqual([...SAMPLE]);
+  });
+
+  test("readIngestPages accepts an already-parsed array (legacy jsonb / raw SQL)", () => {
+    expect(readIngestPages([...SAMPLE])).toEqual([...SAMPLE]);
+  });
+
+  test("readIngestPages drops malformed entries and tolerates null/garbage", () => {
+    expect(readIngestPages(null)).toEqual([]);
+    expect(readIngestPages(undefined)).toEqual([]);
+    expect(readIngestPages("{not-json")).toEqual([]);
+    expect(readIngestPages({ pageNumber: 1 })).toEqual([]);
+    expect(
+      readIngestPages(
+        JSON.stringify([{ pageNumber: 1, text: "ok" }, { pageNumber: "x" }, null, "nope"]),
+      ),
+    ).toEqual([{ pageNumber: 1, text: "ok" }]);
+  });
+});

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

@@ -0,0 +1,43 @@
+import {
+  createEntity,
+  createJsonbField,
+  createLongTextField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Phase-1 (MVP) page shape — LiteParse fills this in (kumiko-enterprise#273).
+// Kept minimal on purpose: downstream themes (provider, recipe) extend it.
+// Stored as JSON.stringify(IngestPage[]) in the encrypted `pages` column —
+// jsonb has no encryption support in the engine, and this column holds the
+// full extracted text of ingested documents (invoices, IDs, contracts).
+// Writers/readers MUST use writeIngestPages / readIngestPages — do not pass
+// a raw IngestPage[] into executor.create (encrypted longText requires string).
+export type IngestPage = {
+  readonly pageNumber: number;
+  readonly text: string;
+};
+
+export type DocumentExtractMeta = {
+  readonly provider: string;
+  readonly ms: number;
+  readonly needsOcr: boolean;
+  readonly pagesParsed: number;
+  readonly totalPages: number;
+};
+
+// documentExtract — implicit entity-projection (r.entity, NOT r.projection):
+// an explicit r.projection would make `forget` non-rebuild-safe and require
+// archiveStream instead of the regular forget path (kumiko-framework#1495).
+// fileRefId points at the source file_refs row; storageKey duplicates it for
+// direct provider access without a join.
+export const documentExtractEntity = createEntity({
+  table: "read_document_extracts",
+  fields: {
+    fileRefId: createTextField({ required: true }),
+    storageKey: createTextField({ required: true }),
+    // Encrypted — holds the full extracted document text (PII). meta is
+    // provider telemetry only and stays plaintext jsonb.
+    pages: createLongTextField({ encrypted: true }),
+    meta: createJsonbField(),
+  },
+});

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

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+// documentIngest — own aggregate-type for the ingest-request stream, one
+// stream per fileRef (aggregateId = fileRefId). Not backed by an r.entity;
+// this is a pure saga-anchor event (kumiko-framework#1497) that the Phase-2
+// worker job (kumiko-enterprise LiteParse provider) subscribes to.
+export const DOCUMENT_INGEST_AGGREGATE_TYPE = "document-ingest";
+
+export const DOCUMENT_INGEST_REQUESTED_EVENT_SHORT = "documentIngest.requested" as const;
+
+// Qualified name — what ctx.unsafeAppendEvent's `type` actually needs
+// (r.defineEvent registers under qn(toKebab(feature), "event",
+// toKebab(shortName)); appendEvent looks up the registry by QN, not the
+// short name — see MSP-apply "event not registered" error otherwise).
+export const DOCUMENT_INGEST_REQUESTED_EVENT_QN =
+  "document-ingest-foundation:event:document-ingest-requested" as const;
+
+export const documentIngestRequestedPayloadSchema = 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),
+});
+export type DocumentIngestRequestedPayload = z.infer<typeof documentIngestRequestedPayloadSchema>;