@cosmicdrift/kumiko-bundled-features 0.310.0 → 0.312.0

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

@@ -1,13 +1,22 @@
 // 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).
+// documentIngest.requested, gated on the mounted provider's mimeTypes/size
+// cap. Mounts small test provider features instead of relying on any
+// hardcoded allowlist/cap — there is none anymore.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  defineFeature,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
 import {
   createInMemoryFileProvider,
+  fileRefEntity,
+  fileRefsTable,
   type InMemoryFileProvider,
 } from "@cosmicdrift/kumiko-framework/files";
 import {
@@ -16,12 +25,83 @@ import {
   TestUsers,
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { waitFor } from "@cosmicdrift/kumiko-framework/testing";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import { createComplianceProfilesFeature } from "../../compliance-profiles";
 import { createConfigFeature } from "../../config";
 import { createTenantFeature } from "../../tenant/feature";
 import { tenantEntity } from "../../tenant/schema/tenant";
 import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import { documentExtractEntity, documentExtractsTable } from "../entity";
+import { documentIngestRequestedPayloadSchema } from "../events";
 import { documentIngestFoundationFeature } from "../feature";
+import { writeIngestPages } from "../pages";
+import { documentIngestProviderTrigger, EXT_DOCUMENT_INGEST_PROVIDER } from "../providers";
+import { writeDocumentExtractForLiveFileRef } from "../write-document-extract";
+
+// Small test providers — mirror kumiko-enterprise's LiteParse shape without
+// pulling it in: A claims pdf/png, B claims docx, each with a deliberately
+// tiny cap so the "oversized" case doesn't need a multi-MB fixture.
+const PROVIDER_A_NAME = "test-provider-a";
+const PROVIDER_A_MAX_BYTES = 200;
+const PROVIDER_B_NAME = "test-provider-b";
+const PROVIDER_B_MAX_BYTES = 500;
+const DOCX_MIME_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+const providerAProcessed: Array<{ readonly fileRefId: string }> = [];
+const providerBProcessed: Array<{ readonly fileRefId: string }> = [];
+
+const testProviderAFeature = defineFeature("test-document-ingest-provider-a", (r) => {
+  r.requires("document-ingest-foundation");
+  r.useExtension(EXT_DOCUMENT_INGEST_PROVIDER, PROVIDER_A_NAME, {
+    mimeTypes: ["application/pdf", "image/png"],
+    maxFileBytes: PROVIDER_A_MAX_BYTES,
+  });
+  r.job(
+    "test-provider-a-worker",
+    { trigger: documentIngestProviderTrigger(PROVIDER_A_NAME), runIn: "worker" },
+    async (rawPayload, ctx) => {
+      const payload = documentIngestRequestedPayloadSchema.parse(rawPayload);
+      // Idempotent, mirrors LiteParse: a redelivered documentIngest.requested
+      // must not create a second extract for the same fileRef.
+      const existing = await ctx.db.selectMany(documentExtractsTable, {
+        fileRefId: payload.fileRefId,
+      });
+      if (existing.length === 0) {
+        await writeDocumentExtractForLiveFileRef({
+          tenantDb: ctx.db,
+          actor: ctx.systemUser,
+          fileRefId: payload.fileRefId,
+          storageKey: payload.storageKey,
+          pages: [{ pageNumber: 1, text: "invoice text" }],
+          meta: {
+            provider: PROVIDER_A_NAME,
+            ms: 1,
+            needsOcr: false,
+            pagesParsed: 1,
+            totalPages: 1,
+          },
+        });
+      }
+      providerAProcessed.push({ fileRefId: payload.fileRefId });
+    },
+  );
+});
+
+const testProviderBFeature = defineFeature("test-document-ingest-provider-b", (r) => {
+  r.requires("document-ingest-foundation");
+  r.useExtension(EXT_DOCUMENT_INGEST_PROVIDER, PROVIDER_B_NAME, {
+    mimeTypes: [DOCX_MIME_TYPE],
+    maxFileBytes: PROVIDER_B_MAX_BYTES,
+  });
+  r.job(
+    "test-provider-b-worker",
+    { trigger: documentIngestProviderTrigger(PROVIDER_B_NAME), runIn: "worker" },
+    async (payload) => {
+      providerBProcessed.push({ fileRefId: payload["fileRefId"] as string });
+    },
+  );
+});
 
 let stack: TestStack;
 let provider: InMemoryFileProvider;
@@ -41,6 +121,19 @@ const pngBytes = new Uint8Array([
   ...Array(64).fill(0),
 ]);
 const textBytes = new TextEncoder().encode("plain text, not a supported mime type");
+const oversizedPdfBytes = new Uint8Array(PROVIDER_A_MAX_BYTES + 100);
+// Real ZIP local-file-header signature — validateFileContent content-verifies
+// docx uploads against it independent of options.accept.
+const docxBytes = new Uint8Array([0x50, 0x4b, 0x03, 0x04, ...Array(32).fill(0)]);
+
+const fileRefExecutor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+  entityName: "fileRef",
+});
+const documentExtractExecutorForSeed = createEventStoreExecutor(
+  documentExtractsTable,
+  documentExtractEntity,
+  { entityName: "document-extract" },
+);
 
 beforeAll(async () => {
   provider = createInMemoryFileProvider();
@@ -51,8 +144,13 @@ beforeAll(async () => {
       createComplianceProfilesFeature(),
       createTenantLifecycleFeature(),
       documentIngestFoundationFeature,
+      testProviderAFeature,
+      testProviderBFeature,
     ],
     files: { storageProvider: provider },
+    // Distinct prefix: avoids sharing a BullMQ queue namespace with any other
+    // setupTestStack call on the same test Redis.
+    jobs: { consumerLane: "worker", queueNamePrefix: `document-ingest-foundation-${generateId()}` },
   });
   await unsafeCreateEntityTable(stack.db, tenantEntity);
 });
@@ -63,9 +161,11 @@ afterAll(async () => {
 
 beforeEach(async () => {
   provider.clear();
+  providerAProcessed.length = 0;
+  providerBProcessed.length = 0;
   stack.events.reset();
   await asRawClient(stack.db).unsafe(
-    `TRUNCATE kumiko_events, kumiko_event_consumers, file_refs RESTART IDENTITY CASCADE`,
+    `TRUNCATE kumiko_events, kumiko_event_consumers, file_refs, read_document_extracts RESTART IDENTITY CASCADE`,
   );
   await stack.eventDispatcher?.ensureRegistered();
 });
@@ -104,8 +204,45 @@ async function loadIngestSkippedEvents(): Promise<{ payload: Record<string, unkn
   return rows as { payload: Record<string, unknown> }[];
 }
 
+async function loadIngestRequestedEventsForFileRef(
+  fileRefId: string,
+): Promise<{ payload: Record<string, unknown> }[]> {
+  const rows = await asRawClient(stack.db).unsafe(
+    `SELECT payload FROM kumiko_events WHERE type = $1 AND payload->>'fileRefId' = $2 ORDER BY id ASC`,
+    ["document-ingest-foundation:event:document-ingest-requested", fileRefId],
+  );
+  return rows as { payload: Record<string, unknown> }[];
+}
+
+async function loadIngestSkippedEventsForFileRef(
+  fileRefId: string,
+): Promise<{ payload: Record<string, unknown> }[]> {
+  const rows = await asRawClient(stack.db).unsafe(
+    `SELECT payload FROM kumiko_events WHERE type = $1 AND payload->>'fileRefId' = $2 ORDER BY id ASC`,
+    ["document-ingest-foundation:event:document-ingest-skipped", fileRefId],
+  );
+  return rows as { payload: Record<string, unknown> }[];
+}
+
+async function seedDocumentExtract(tenantId: TenantId, fileRefId: string): Promise<string> {
+  const user = createSystemUser(tenantId);
+  const tdb = createTenantDb(stack.db, tenantId);
+  const result = await documentExtractExecutorForSeed.create(
+    {
+      fileRefId,
+      storageKey: `s3://bucket/${fileRefId}`,
+      pages: writeIngestPages([{ pageNumber: 1, text: "invoice text" }]),
+      meta: { provider: PROVIDER_A_NAME, ms: 1, needsOcr: false, pagesParsed: 1, totalPages: 1 },
+    },
+    user,
+    tdb,
+  );
+  if (!result.isSuccess) throw new Error(`seed failed: ${result.error.message}`);
+  return String(result.data.id);
+}
+
 describe("fileRef.created → documentIngest.requested", () => {
-  test("PDF upload requests ingest with the fileRef pointer, no binary", async () => {
+  test("PDF upload requests ingest with the fileRef pointer, no binary, tagged with the winning provider", async () => {
     const { id, storageKey } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
 
     await stack.eventDispatcher?.runOnce();
@@ -118,10 +255,11 @@ describe("fileRef.created → documentIngest.requested", () => {
       fileName: "invoice.pdf",
       mimeType: "application/pdf",
       size: pdfBytes.length,
+      provider: PROVIDER_A_NAME,
     });
   });
 
-  test("image/png upload also requests ingest (Phase-1 mime allowlist)", async () => {
+  test("image/png upload also requests ingest — same provider claims both mimeTypes", async () => {
     await uploadFile("scan.png", pngBytes, "image/png");
 
     await stack.eventDispatcher?.runOnce();
@@ -129,7 +267,47 @@ describe("fileRef.created → documentIngest.requested", () => {
     expect(await loadIngestRequestedEvents()).toHaveLength(1);
   });
 
-  test("unsupported mime type is skipped — no ingest requested, skip is observable", async () => {
+  test("provider's job actually receives the request via the where-filtered trigger", async () => {
+    const { id } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(providerAProcessed).toHaveLength(1);
+    });
+
+    expect(providerAProcessed).toEqual([{ fileRefId: id }]);
+  });
+
+  test("two mounted providers stay isolated — a pdf only reaches provider A's job, a docx only reaches provider B's job", async () => {
+    const { id: pdfId } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+    const { id: docxId } = await uploadFile("report.docx", docxBytes, DOCX_MIME_TYPE);
+
+    await stack.eventDispatcher?.runOnce();
+
+    const requested = await loadIngestRequestedEvents();
+    expect(requested).toHaveLength(2);
+    expect(requested).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          payload: expect.objectContaining({ fileRefId: pdfId, provider: PROVIDER_A_NAME }),
+        }),
+        expect.objectContaining({
+          payload: expect.objectContaining({ fileRefId: docxId, provider: PROVIDER_B_NAME }),
+        }),
+      ]),
+    );
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(providerAProcessed).toHaveLength(1);
+      expect(providerBProcessed).toHaveLength(1);
+    });
+
+    expect(providerAProcessed).toEqual([{ fileRefId: pdfId }]);
+    expect(providerBProcessed).toEqual([{ fileRefId: docxId }]);
+  });
+
+  test("unsupported mime type is skipped — no provider claims it, no ingest requested", async () => {
     const { id, storageKey } = await uploadFile("notes.txt", textBytes, "text/plain");
 
     await stack.eventDispatcher?.runOnce();
@@ -139,7 +317,7 @@ describe("fileRef.created → documentIngest.requested", () => {
     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.
+    // concern — the no-provider-claims-it miss is.
     expect(skipped[0]?.payload).toMatchObject({
       fileRefId: id,
       storageKey,
@@ -149,38 +327,8 @@ describe("fileRef.created → documentIngest.requested", () => {
     expect(String(skipped[0]?.payload["mimeType"])).toStartWith("text/plain");
   });
 
-  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
-      (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: 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,
-      ],
-    );
+  test("file over the winning provider's maxFileBytes is skipped as file-too-large", async () => {
+    const { id, storageKey } = await uploadFile("huge.pdf", oversizedPdfBytes, "application/pdf");
 
     await stack.eventDispatcher?.runOnce();
 
@@ -188,12 +336,442 @@ describe("fileRef.created → documentIngest.requested", () => {
     const skipped = await loadIngestSkippedEvents();
     expect(skipped).toHaveLength(1);
     expect(skipped[0]?.payload).toEqual({
-      fileRefId: "00000000-0000-4000-8000-0000000000ff",
-      storageKey: "huge.pdf",
+      fileRefId: id,
+      storageKey,
       fileName: "huge.pdf",
       mimeType: "application/pdf",
-      size: oversizedSize,
+      size: oversizedPdfBytes.length,
       reason: "file-too-large",
     });
   });
 });
+
+describe("fileRef delete/forget cleanup", () => {
+  test("fileRef.deleted forgets the associated documentExtract row, leaving other fileRefs' extracts untouched", async () => {
+    const { id: fileRefId } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+    const extractId = await seedDocumentExtract(admin.tenantId, fileRefId);
+    const { id: otherFileRefId } = await uploadFile("other.pdf", pdfBytes, "application/pdf");
+    const otherExtractId = await seedDocumentExtract(admin.tenantId, otherFileRefId);
+
+    const token = await stack.jwt.sign(admin);
+    const res = await stack.app.request(`/api/files/${fileRefId}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await selectMany(stack.db, documentExtractsTable, { id: extractId })).toHaveLength(0);
+    expect(await selectMany(stack.db, documentExtractsTable, { id: otherExtractId })).toHaveLength(
+      1,
+    );
+  });
+
+  test("fileRef.forgotten forgets the associated documentExtract row, leaving other fileRefs' extracts untouched", async () => {
+    const { id: fileRefId } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+    const extractId = await seedDocumentExtract(admin.tenantId, fileRefId);
+    const { id: otherFileRefId } = await uploadFile("other.pdf", pdfBytes, "application/pdf");
+    const otherExtractId = await seedDocumentExtract(admin.tenantId, otherFileRefId);
+
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const result = await fileRefExecutor.forget({ id: fileRefId }, user, tdb);
+    if (!result.isSuccess) throw new Error(`fileRef forget failed: ${result.error.message}`);
+
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await selectMany(stack.db, documentExtractsTable, { id: extractId })).toHaveLength(0);
+    expect(await selectMany(stack.db, documentExtractsTable, { id: otherExtractId })).toHaveLength(
+      1,
+    );
+  });
+
+  test("fileRef.deleted with no documentExtract row leaves the cleanup consumer healthy", async () => {
+    const { id: fileRefId } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+
+    const token = await stack.jwt.sign(admin);
+    const res = await stack.app.request(`/api/files/${fileRefId}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    expect(res.status).toBe(200);
+
+    // fileRef.deleted is the latest event at this point (fileRef.created
+    // already happened during upload) — its id is the bar the cleanup
+    // consumer's cursor must clear to prove it actually processed it,
+    // not just an earlier event, without throwing.
+    const [deletedEventRow] = (await asRawClient(stack.db).unsafe(
+      `SELECT id FROM kumiko_events ORDER BY id DESC LIMIT 1`,
+    )) as { id: string }[];
+    if (!deletedEventRow) throw new Error("fileRef.deleted event not found");
+
+    await stack.eventDispatcher?.runOnce();
+
+    const rows = await asRawClient(stack.db).unsafe(
+      `SELECT status, last_error, last_processed_event_id FROM kumiko_event_consumers WHERE name = $1`,
+      ["document-ingest-foundation:projection:forget-extract-with-file-ref"],
+    );
+    const consumer = (
+      rows as { status: string; last_error: string | null; last_processed_event_id: string }[]
+    )[0];
+    expect(consumer?.last_error).toBeNull();
+    // bigint columns round-trip as strings through the pg driver.
+    expect(Number(consumer?.last_processed_event_id)).toBeGreaterThanOrEqual(
+      Number(deletedEventRow.id),
+    );
+  });
+});
+
+async function deleteFileRef(fileRefId: string): Promise<void> {
+  const token = await stack.jwt.sign(admin);
+  const res = await stack.app.request(`/api/files/${fileRefId}`, {
+    method: "DELETE",
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(res.status).toBe(200);
+}
+
+describe("fileRef.restored → re-ingest", () => {
+  test("delete → runOnce → restore → waitFor re-requests ingest and produces a fresh extract", async () => {
+    const { id: fileRefId, storageKey } = await uploadFile(
+      "invoice.pdf",
+      pdfBytes,
+      "application/pdf",
+    );
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(1);
+    });
+
+    await deleteFileRef(fileRefId);
+    await stack.eventDispatcher?.runOnce();
+    expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(0);
+
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const restoreResult = await fileRefExecutor.restore({ id: fileRefId }, user, tdb);
+    if (!restoreResult.isSuccess) {
+      throw new Error(`restore failed: ${restoreResult.error.message}`);
+    }
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(1);
+    });
+
+    const requested = await loadIngestRequestedEventsForFileRef(fileRefId);
+    expect(requested).toHaveLength(2);
+    expect(requested[1]?.payload).toEqual({
+      fileRefId,
+      storageKey,
+      fileName: "invoice.pdf",
+      mimeType: "application/pdf",
+      size: pdfBytes.length,
+      provider: PROVIDER_A_NAME,
+    });
+  });
+
+  test("delete → restore with no dispatcher pass in between still ends with exactly one live extract", async () => {
+    const { id: fileRefId } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(1);
+    });
+
+    // No runOnce between delete and restore: the forget-extract-with-file-ref
+    // consumer only sees fileRef.deleted once it next runs, by which point
+    // the fileRef may already be live again — its own separate cursor makes
+    // this race possible on every real deploy, not just in this test.
+    await deleteFileRef(fileRefId);
+
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const restoreResult = await fileRefExecutor.restore({ id: fileRefId }, user, tdb);
+    if (!restoreResult.isSuccess) {
+      throw new Error(`restore failed: ${restoreResult.error.message}`);
+    }
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(providerAProcessed.filter((p) => p.fileRefId === fileRefId)).toHaveLength(2);
+    });
+
+    expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(1);
+  });
+
+  test("delete → restore reconciled in the same pass the job already won leaves the extract intact", async () => {
+    const { id: fileRefId } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+    const extractId = await seedDocumentExtract(admin.tenantId, fileRefId);
+
+    await deleteFileRef(fileRefId);
+
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const restoreResult = await fileRefExecutor.restore({ id: fileRefId }, user, tdb);
+    if (!restoreResult.isSuccess) {
+      throw new Error(`restore failed: ${restoreResult.error.message}`);
+    }
+
+    // The seeded extract stands in for a provider job that won the race: it
+    // exists for the now-live fileRef before the forget consumer ever sees
+    // the still-pending fileRef.deleted.
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await selectMany(stack.db, documentExtractsTable, { id: extractId })).toHaveLength(1);
+  });
+
+  test("delete → restore of an unsupported mime type produces two skipped events", async () => {
+    const { id: fileRefId } = await uploadFile("notes.txt", textBytes, "text/plain");
+
+    await stack.eventDispatcher?.runOnce();
+    expect(await loadIngestSkippedEventsForFileRef(fileRefId)).toHaveLength(1);
+
+    await deleteFileRef(fileRefId);
+
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const restoreResult = await fileRefExecutor.restore({ id: fileRefId }, user, tdb);
+    if (!restoreResult.isSuccess) {
+      throw new Error(`restore failed: ${restoreResult.error.message}`);
+    }
+
+    await stack.eventDispatcher?.runOnce();
+
+    const skipped = await loadIngestSkippedEventsForFileRef(fileRefId);
+    expect(skipped).toHaveLength(2);
+    expect(skipped.every((row) => row.payload["reason"] === "unsupported-mime-type")).toBe(true);
+  });
+
+  test("forget makes restore fail — no re-ingest, only the original upload's requested event survives", async () => {
+    const { id: fileRefId } = await uploadFile("invoice.pdf", pdfBytes, "application/pdf");
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(1);
+    });
+
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const forgetResult = await fileRefExecutor.forget({ id: fileRefId }, user, tdb);
+    if (!forgetResult.isSuccess) {
+      throw new Error(`forget failed: ${forgetResult.error.message}`);
+    }
+
+    await stack.eventDispatcher?.runOnce();
+
+    const restoreResult = await fileRefExecutor.restore({ id: fileRefId }, user, tdb);
+    expect(restoreResult.isSuccess).toBe(false);
+    // code, not instanceof: WriteResult.error is always a plain WriteErrorInfo
+    // object (JSON-serializable for the dispatcher's idempotency-key storage),
+    // never a KumikoError instance.
+    if (!restoreResult.isSuccess) {
+      expect(restoreResult.error).toMatchObject({ code: "not_found" });
+    }
+
+    await stack.eventDispatcher?.runOnce();
+
+    expect(await loadIngestRequestedEventsForFileRef(fileRefId)).toHaveLength(1);
+    expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(0);
+  });
+});
+
+describe("orphan extract guard", () => {
+  const testMeta = {
+    provider: PROVIDER_A_NAME,
+    ms: 1,
+    needsOcr: false,
+    pagesParsed: 1,
+    totalPages: 1,
+  };
+
+  test("writeDocumentExtractForLiveFileRef writes for a live fileRef, skips (no row) for a deleted or forgotten one", async () => {
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const actor = createSystemUser(admin.tenantId);
+
+    const { id: liveFileRefId, storageKey: liveStorageKey } = await uploadFile(
+      "invoice.pdf",
+      pdfBytes,
+      "application/pdf",
+    );
+    const writtenResult = await writeDocumentExtractForLiveFileRef({
+      tenantDb: tdb,
+      actor,
+      fileRefId: liveFileRefId,
+      storageKey: liveStorageKey,
+      pages: [{ pageNumber: 1, text: "invoice text" }],
+      meta: testMeta,
+    });
+    expect(writtenResult.kind).toBe("written");
+    expect(
+      await selectMany(stack.db, documentExtractsTable, { fileRefId: liveFileRefId }),
+    ).toHaveLength(1);
+
+    const { id: deletedFileRefId, storageKey: deletedStorageKey } = await uploadFile(
+      "deleted.pdf",
+      pdfBytes,
+      "application/pdf",
+    );
+    await deleteFileRef(deletedFileRefId);
+    const skippedForDeleted = await writeDocumentExtractForLiveFileRef({
+      tenantDb: tdb,
+      actor,
+      fileRefId: deletedFileRefId,
+      storageKey: deletedStorageKey,
+      pages: [{ pageNumber: 1, text: "invoice text" }],
+      meta: testMeta,
+    });
+    expect(skippedForDeleted).toEqual({ kind: "skipped", reason: "file_ref_deleted" });
+    expect(
+      await selectMany(stack.db, documentExtractsTable, { fileRefId: deletedFileRefId }),
+    ).toHaveLength(0);
+
+    const { id: forgottenFileRefId, storageKey: forgottenStorageKey } = await uploadFile(
+      "forgotten.pdf",
+      pdfBytes,
+      "application/pdf",
+    );
+    const forgetResult = await fileRefExecutor.forget({ id: forgottenFileRefId }, actor, tdb);
+    if (!forgetResult.isSuccess) throw new Error(`forget failed: ${forgetResult.error.message}`);
+    const skippedForForgotten = await writeDocumentExtractForLiveFileRef({
+      tenantDb: tdb,
+      actor,
+      fileRefId: forgottenFileRefId,
+      storageKey: forgottenStorageKey,
+      pages: [{ pageNumber: 1, text: "invoice text" }],
+      meta: testMeta,
+    });
+    expect(skippedForForgotten).toEqual({ kind: "skipped", reason: "file_ref_deleted" });
+    expect(
+      await selectMany(stack.db, documentExtractsTable, { fileRefId: forgottenFileRefId }),
+    ).toHaveLength(0);
+  });
+
+  test("a provider write bypassing the helper, landing after fileRef.deleted was already processed, still gets forgotten", async () => {
+    const { id: fileRefId, storageKey } = await uploadFile(
+      "invoice.pdf",
+      pdfBytes,
+      "application/pdf",
+    );
+    await deleteFileRef(fileRefId);
+    // forget-extract-with-file-ref has already processed fileRef.deleted at
+    // this point — a provider write landing after is exactly the race the
+    // documentExtract.created handler exists for.
+    await stack.eventDispatcher?.runOnce();
+
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const lateWriteResult = await documentExtractExecutorForSeed.create(
+      {
+        fileRefId,
+        storageKey,
+        pages: writeIngestPages([{ pageNumber: 1, text: "invoice text" }]),
+        meta: testMeta,
+      },
+      user,
+      tdb,
+    );
+    if (!lateWriteResult.isSuccess) {
+      throw new Error(`late write failed: ${lateWriteResult.error.message}`);
+    }
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(0);
+    });
+  });
+
+  test("a provider write bypassing the helper, landing after fileRef.forgotten was already processed, still gets forgotten", async () => {
+    const { id: fileRefId, storageKey } = await uploadFile(
+      "invoice.pdf",
+      pdfBytes,
+      "application/pdf",
+    );
+    const user = createSystemUser(admin.tenantId);
+    const tdb = createTenantDb(stack.db, admin.tenantId);
+    const forgetResult = await fileRefExecutor.forget({ id: fileRefId }, user, tdb);
+    if (!forgetResult.isSuccess) throw new Error(`forget failed: ${forgetResult.error.message}`);
+    await stack.eventDispatcher?.runOnce();
+
+    const lateWriteResult = await documentExtractExecutorForSeed.create(
+      {
+        fileRefId,
+        storageKey,
+        pages: writeIngestPages([{ pageNumber: 1, text: "invoice text" }]),
+        meta: testMeta,
+      },
+      user,
+      tdb,
+    );
+    if (!lateWriteResult.isSuccess) {
+      throw new Error(`late write failed: ${lateWriteResult.error.message}`);
+    }
+
+    await waitFor(async () => {
+      await stack.eventDispatcher?.runOnce();
+      expect(await selectMany(stack.db, documentExtractsTable, { fileRefId })).toHaveLength(0);
+    });
+  });
+});
+
+describe("fileRef.created — no provider mounted", () => {
+  let noProviderStack: TestStack;
+  let noProviderFileProvider: InMemoryFileProvider;
+
+  beforeAll(async () => {
+    noProviderFileProvider = createInMemoryFileProvider();
+    noProviderStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createTenantFeature(),
+        createComplianceProfilesFeature(),
+        createTenantLifecycleFeature(),
+        documentIngestFoundationFeature,
+      ],
+      files: { storageProvider: noProviderFileProvider },
+      jobs: {
+        consumerLane: "worker",
+        queueNamePrefix: `document-ingest-foundation-no-provider-${generateId()}`,
+      },
+    });
+    await unsafeCreateEntityTable(noProviderStack.db, tenantEntity);
+  });
+
+  afterAll(async () => {
+    await noProviderStack.cleanup();
+  });
+
+  test("pdf upload is skipped as unsupported-mime-type — mounting the feature with zero providers is valid", async () => {
+    const token = await noProviderStack.jwt.sign(admin);
+    const formData = new FormData();
+    formData.append(
+      "file",
+      new File([Buffer.from(pdfBytes)], "invoice.pdf", { type: "application/pdf" }),
+    );
+    const uploadRes = await noProviderStack.app.request("/api/files", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      body: formData,
+    });
+    expect(uploadRes.status).toBe(201);
+
+    await noProviderStack.eventDispatcher?.runOnce();
+
+    const requested = await asRawClient(noProviderStack.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE type = $1`,
+      ["document-ingest-foundation:event:document-ingest-requested"],
+    );
+    expect(requested).toHaveLength(0);
+
+    const skipped = await asRawClient(noProviderStack.db).unsafe(
+      `SELECT payload FROM kumiko_events WHERE type = $1`,
+      ["document-ingest-foundation:event:document-ingest-skipped"],
+    );
+    expect(skipped).toHaveLength(1);
+    expect((skipped as { payload: Record<string, unknown> }[])[0]?.payload).toMatchObject({
+      reason: "unsupported-mime-type",
+    });
+  });
+});