@cosmicdrift/kumiko-bundled-features 0.310.0 → 0.312.0

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

@@ -83,12 +83,29 @@ describe("documentIngestFoundationFeature — shape", () => {
     );
   });
 
-  test("registers the fileRef.created MSP", () => {
+  test("registers the fileRef.created/restored MSP and the fileRef delete/forget + orphan-extract cleanup MSP", () => {
     expect(Object.keys(documentIngestFoundationFeature.multiStreamProjections)).toEqual([
       "request-ingest",
+      "forget-extract-with-file-ref",
     ]);
-    const msp = documentIngestFoundationFeature.multiStreamProjections["request-ingest"];
-    expect(Object.keys(msp?.apply ?? {})).toEqual(["fileRef.created"]);
+    const requestIngest = documentIngestFoundationFeature.multiStreamProjections["request-ingest"];
+    expect(Object.keys(requestIngest?.apply ?? {})).toEqual([
+      "fileRef.created",
+      "fileRef.restored",
+    ]);
+    const forgetExtract =
+      documentIngestFoundationFeature.multiStreamProjections["forget-extract-with-file-ref"];
+    expect(Object.keys(forgetExtract?.apply ?? {})).toEqual([
+      "fileRef.deleted",
+      "fileRef.forgotten",
+      "document-extract.created",
+    ]);
+  });
+
+  test("registers the documentIngestProvider extension point", () => {
+    expect(Object.keys(documentIngestFoundationFeature.registrarExtensions)).toContain(
+      "documentIngestProvider",
+    );
   });
 });
 

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

@@ -0,0 +1,204 @@
+// r.bootCheck does NOT run inside setupTestStack, only createApp()'s
+// validateBoot() — most boot-error assertions below call
+// validateDocumentIngestProviderWiring directly; one drives real validateBoot().
+
+import { describe, expect, test } from "bun:test";
+import {
+  defineFeature,
+  type JobTrigger,
+  type Registry,
+  validateBoot,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant/feature";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import { validateDocumentIngestProviderWiring } from "../boot-checks";
+import { DOCUMENT_INGEST_REQUESTED_EVENT_QN } from "../events";
+import { documentIngestFoundationFeature } from "../feature";
+import {
+  type DocumentIngestProviderOptions,
+  documentIngestProviderTrigger,
+  EXT_DOCUMENT_INGEST_PROVIDER,
+  listIngestibleMimeTypes,
+  resolveDocumentIngestProviders,
+} from "../providers";
+
+function makeProviderFeature(name: string, options: DocumentIngestProviderOptions) {
+  return defineFeature(`test-provider-${name}`, (r) => {
+    // requires() only matters to validateBoot's cross-feature checks — the
+    // direct resolveDocumentIngestProviders/validateDocumentIngestProviderWiring
+    // tests below never look at it.
+    r.requires("document-ingest-foundation");
+    r.useExtension(EXT_DOCUMENT_INGEST_PROVIDER, name, options);
+  });
+}
+
+function makeConsumerFeature(jobName: string, trigger: JobTrigger) {
+  return defineFeature(`test-consumer-${jobName}`, (r) => {
+    r.job(jobName, { trigger, runIn: "worker" }, async () => {});
+  });
+}
+
+describe("resolveDocumentIngestProviders", () => {
+  test("resolves a single provider's mimeTypes to itself", () => {
+    const feature = makeProviderFeature("alpha", {
+      mimeTypes: ["application/pdf", "image/png"],
+      maxFileBytes: 1000,
+    });
+
+    const resolved = resolveDocumentIngestProviders(feature.extensionUsages);
+
+    expect(resolved.size).toBe(2);
+    expect(resolved.get("application/pdf")).toEqual({ name: "alpha", maxFileBytes: 1000 });
+    expect(resolved.get("image/png")).toEqual({ name: "alpha", maxFileBytes: 1000 });
+  });
+
+  test("two providers claiming the same mimeType throws", () => {
+    const alpha = makeProviderFeature("alpha", {
+      mimeTypes: ["application/pdf"],
+      maxFileBytes: 1000,
+    });
+    const beta = makeProviderFeature("beta", {
+      mimeTypes: ["application/pdf"],
+      maxFileBytes: 2000,
+    });
+
+    expect(() =>
+      resolveDocumentIngestProviders([...alpha.extensionUsages, ...beta.extensionUsages]),
+    ).toThrow(/both claim mimeType "application\/pdf"/);
+  });
+
+  test("invalid options shape (bypassing the type system, e.g. a dynamic config) throws", () => {
+    const feature = makeProviderFeature(
+      "bad",
+      // Missing maxFileBytes — only reachable by a caller that bypasses the
+      // typed r.useExtension overload (e.g. hand-built dynamic config).
+      { mimeTypes: ["application/pdf"] } as DocumentIngestProviderOptions,
+    );
+
+    expect(() => resolveDocumentIngestProviders(feature.extensionUsages)).toThrow(
+      /registered invalid options/,
+    );
+  });
+});
+
+describe("listIngestibleMimeTypes", () => {
+  test("returns every registered provider's mimeTypes, sorted", () => {
+    const alpha = makeProviderFeature("alpha", {
+      mimeTypes: ["image/png", "application/pdf"],
+      maxFileBytes: 1000,
+    });
+    const beta = makeProviderFeature("beta", { mimeTypes: ["text/csv"], maxFileBytes: 500 });
+    // Minimal test double — the function only calls getExtensionUsages.
+    const registry = {
+      getExtensionUsages: () => [...alpha.extensionUsages, ...beta.extensionUsages],
+    } as unknown as Registry;
+
+    expect(listIngestibleMimeTypes(registry)).toEqual(["application/pdf", "image/png", "text/csv"]);
+  });
+});
+
+describe("documentIngestProviderTrigger", () => {
+  test("builds the {on, where: {provider}} shape every provider job must use", () => {
+    expect(documentIngestProviderTrigger("alpha")).toEqual({
+      on: DOCUMENT_INGEST_REQUESTED_EVENT_QN,
+      where: { provider: "alpha" },
+    });
+  });
+});
+
+describe("validateDocumentIngestProviderWiring", () => {
+  test("zero providers, zero jobs — passes (uploads simply skip as unsupported-mime-type)", () => {
+    expect(() => validateDocumentIngestProviderWiring([])).not.toThrow();
+  });
+
+  test("one provider with a matching wired job — passes", () => {
+    const provider = makeProviderFeature("alpha", {
+      mimeTypes: ["application/pdf"],
+      maxFileBytes: 1000,
+    });
+    const consumer = makeConsumerFeature("process-alpha", documentIngestProviderTrigger("alpha"));
+
+    expect(() => validateDocumentIngestProviderWiring([provider, consumer])).not.toThrow();
+  });
+
+  test("a job triggers on documentIngest.requested without a provider filter — throws", () => {
+    const provider = makeProviderFeature("alpha", {
+      mimeTypes: ["application/pdf"],
+      maxFileBytes: 1000,
+    });
+    const consumer = makeConsumerFeature("process-anything", {
+      on: DOCUMENT_INGEST_REQUESTED_EVENT_QN,
+    });
+
+    expect(() => validateDocumentIngestProviderWiring([provider, consumer])).toThrow(
+      /without a provider filter/,
+    );
+  });
+
+  test("a job's where.provider doesn't match any registered provider — throws", () => {
+    const provider = makeProviderFeature("alpha", {
+      mimeTypes: ["application/pdf"],
+      maxFileBytes: 1000,
+    });
+    const consumer = makeConsumerFeature(
+      "process-ghost",
+      documentIngestProviderTrigger("ghost-provider"),
+    );
+
+    expect(() => validateDocumentIngestProviderWiring([provider, consumer])).toThrow(
+      /filters documentIngest\.requested to provider "ghost-provider"/,
+    );
+  });
+
+  test("a registered provider with no job wired to it — throws", () => {
+    const provider = makeProviderFeature("alpha", {
+      mimeTypes: ["application/pdf"],
+      maxFileBytes: 1000,
+    });
+
+    expect(() => validateDocumentIngestProviderWiring([provider])).toThrow(
+      /Provider "alpha" is registered.*but no job triggers/,
+    );
+  });
+});
+
+describe("validateBoot — proves the feature actually registers the bootCheck", () => {
+  test("two providers colliding on a case-insensitive mimeType fail real boot, not just a direct validateDocumentIngestProviderWiring call", () => {
+    const providerA = makeProviderFeature("provider-a", {
+      mimeTypes: ["application/pdf"],
+      maxFileBytes: 1000,
+    });
+    const providerAConsumer = makeConsumerFeature(
+      "process-provider-a",
+      documentIngestProviderTrigger("provider-a"),
+    );
+    const providerB = makeProviderFeature("provider-b", {
+      // Same mimeType as provider-a modulo case — normalizeMimeType
+      // lowercases both, so this must collide exactly like an exact-match would.
+      mimeTypes: ["Application/PDF"],
+      maxFileBytes: 1000,
+    });
+    const providerBConsumer = makeConsumerFeature(
+      "process-provider-b",
+      documentIngestProviderTrigger("provider-b"),
+    );
+
+    expect(() =>
+      validateBoot([
+        createConfigFeature(),
+        createTenantFeature(),
+        createComplianceProfilesFeature(),
+        createTenantLifecycleFeature(),
+        documentIngestFoundationFeature,
+        providerA,
+        providerAConsumer,
+        providerB,
+        providerBConsumer,
+      ]),
+    ).toThrow(
+      /\[Feature document-ingest-foundation\] r\.bootCheck failed: .*both claim mimeType "application\/pdf"/,
+    );
+  });
+});

package/src/document-ingest-foundation/boot-checks.ts

@@ -0,0 +1,58 @@
+// Every job triggered on documentIngest.requested must filter to exactly one
+// registered provider, and every registered provider must have a job wired
+// to it — otherwise requested ingests for that provider never get picked up.
+
+import type { FeatureDefinition, JobDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { DOCUMENT_INGEST_REQUESTED_EVENT_QN } from "./events";
+import { resolveDocumentIngestProviders } from "./providers";
+
+// undefined = job isn't triggered on documentIngest.requested at all (not our
+// concern here). "" = triggered without a usable where.provider filter.
+function providerFilterOf(trigger: JobDefinition["trigger"]): string | undefined {
+  if (!("on" in trigger)) return undefined;
+  const on = Array.isArray(trigger.on) ? trigger.on : [trigger.on];
+  if (!on.includes(DOCUMENT_INGEST_REQUESTED_EVENT_QN)) return undefined;
+  const provider = trigger.where?.["provider"];
+  return typeof provider === "string" && provider.length > 0 ? provider : "";
+}
+
+export function validateDocumentIngestProviderWiring(features: readonly FeatureDefinition[]): void {
+  const allUsages = features.flatMap((f) => f.extensionUsages);
+  // Throws on invalid options / mimeType collisions.
+  const byMime = resolveDocumentIngestProviders(allUsages);
+  const registeredProviderNames = new Set([...byMime.values()].map((p) => p.name));
+
+  const wiredProviderNames = new Set<string>();
+  for (const feature of features) {
+    for (const jobDef of Object.values(feature.jobs)) {
+      const provider = providerFilterOf(jobDef.trigger);
+      if (provider === undefined) continue;
+      if (provider === "") {
+        throw new Error(
+          `[kumiko:boot] Job "${jobDef.name}" (feature "${feature.name}") triggers on ` +
+            `document-ingest-foundation's documentIngest.requested without a provider filter — every job on ` +
+            `this event must route through documentIngestProviderTrigger("<name>"), or it fires for every ` +
+            `provider's uploads. Use: trigger: documentIngestProviderTrigger("<name>").`,
+        );
+      }
+      if (!registeredProviderNames.has(provider)) {
+        throw new Error(
+          `[kumiko:boot] Job "${jobDef.name}" (feature "${feature.name}") filters documentIngest.requested to ` +
+            `provider "${provider}", but no feature registers that provider via ` +
+            `r.useExtension(EXT_DOCUMENT_INGEST_PROVIDER, "${provider}", ...). Known: ` +
+            `${[...registeredProviderNames].join(", ") || "<none>"}.`,
+        );
+      }
+      wiredProviderNames.add(provider);
+    }
+  }
+
+  for (const name of registeredProviderNames) {
+    if (wiredProviderNames.has(name)) continue;
+    throw new Error(
+      `[kumiko:boot] Provider "${name}" is registered via EXT_DOCUMENT_INGEST_PROVIDER but no job triggers on ` +
+        `documentIngestProviderTrigger("${name}") — files matching its mimeTypes would be requested for ingest ` +
+        `and never processed. Add an r.job with that trigger, or unmount the provider.`,
+    );
+  }
+}

package/src/document-ingest-foundation/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.312.0",
+    "type": "breaking",
+    "title": "document-ingest-foundation is provider-driven; ALLOWED_MIME_TYPES/MAX_FILE_BYTES are gone",
+    "migration": "The hardcoded MIME allowlist and fixed size cap are removed. A provider feature (e.g. kumiko-enterprise's LiteParse) now registers via r.useExtension(EXT_DOCUMENT_INGEST_PROVIDER, \"<name>\", { mimeTypes, maxFileBytes }) and routes its r.job's trigger through documentIngestProviderTrigger(\"<name>\") instead of a bare { on: DOCUMENT_INGEST_REQUESTED_EVENT_QN }. A provider feature must also declare r.requires(\"document-ingest-foundation\") — validateBoot rejects r.useExtension(EXT_DOCUMENT_INGEST_PROVIDER, ...) without it as a missing feature dependency. Boot now throws if: two providers claim the same mimeType, a job triggers on documentIngest.requested without a provider filter, a job filters to an unregistered provider name, or a registered provider has no job wired to it. documentIngest.requested's payload gained a required provider field (event schema version 2; a migration upcasts existing v1 events to provider: \"unknown\", a sentinel that cannot match any real provider filter). A file whose mimeType has no registered provider now appends documentIngest.skipped with reason unsupported-mime-type instead of file-too-large. A fileRef.deleted or fileRef.forgotten event now forgets that fileRef's documentExtract row (new forget-extract-with-file-ref table-less MSP) — previously the extract silently outlived a deleted/forgotten source file. Mounting documentIngestFoundationFeature with zero providers is valid: every upload is simply skipped as unsupported-mime-type. Boot only fails for a misconfigured wiring (unfiltered job on documentIngest.requested, a job filtered to an unregistered provider name, two providers claiming the same mimeType, or a registered provider with no job wired to it)."
+  },
+  {
+    "version": "0.312.0",
+    "type": "fix",
+    "title": "document-ingest-foundation: no documentExtract survives a deleted/forgotten fileRef, even when a provider is still writing one concurrently",
+    "migration": "New export writeDocumentExtractForLiveFileRef(input) — providers that write documentExtract rows themselves (own executor call on ctx.db, outside the request/response flow) should write through this helper instead of calling the executor directly, and only emit their ready/failed follow-up event when the result's `kind` is \"written\" (a \"skipped\" result means the fileRef was already deleted/forgotten and nothing was written). The forget-extract-with-file-ref MSP now also reacts to documentExtract's own created event: if the extract's fileRef is not live at processing time, the consumer forgets that extract immediately. This closes the race where a provider's write and the fileRef's delete/forget interleave in either order — regardless of whether the provider uses the new helper or writes directly, no extract can now outlive its fileRef. The NotFound-tolerance check in the forget path is now a plain `error.code === \"not_found\"` comparison (WriteResult.error is always a plain WriteErrorInfo object, never a KumikoError instance, so `instanceof` never matched here). Test seeds of documentExtract rows with made-up fileRefIds, in any test stack that mounts document-ingest-foundation with a running dispatcher (calls runOnce), are now actively forgotten by this guard once the dispatcher processes the seed's created event — existing such seed patterns need a live (unsoftdeleted) fileRef backing the seeded fileRefId, or must avoid running the dispatcher over that event."
+  },
+  {
+    "version": "0.312.0",
+    "type": "fix",
+    "title": "document-ingest-foundation: a restored fileRef is re-ingested, and fileRef.deleted no longer forgets an extract that is live again",
+    "migration": "The request-ingest MSP now also reacts to fileRef.restored, parsing the entity fields from the event's `previous` snapshot and routing through the same provider-resolution/skip logic as fileRef.created — a delete→restore round-trip re-requests documentIngest.requested instead of leaving the file without an extract. forget-extract-with-file-ref's fileRef.deleted handler now checks the fileRef's current liveness (new isFileRefLive helper) before forgetting: since request-ingest and forget-extract-with-file-ref poll via separate consumer cursors, a fileRef.deleted event processed after a later restore already made the fileRef live again would otherwise forget the extract belonging to the now-live file. fileRef.forgotten still forgets unconditionally — forget stays a final Art. 17 erasure, restore on a forgotten fileRef fails NotFound as before, and no re-ingest happens for it. No consumer/action changes required."
+  },
   {
     "version": "0.306.0",
     "type": "fix",

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

@@ -21,6 +21,9 @@ export const documentIngestRequestedPayloadSchema = z.object({
   fileName: z.string().min(1),
   mimeType: z.string().min(1),
   size: z.number().int().min(0),
+  // Which registered provider claimed this mimeType — the job-trigger
+  // where-filter every provider's job routes through (documentIngestProviderTrigger).
+  provider: z.string().min(1),
 });
 export type DocumentIngestRequestedPayload = z.infer<typeof documentIngestRequestedPayloadSchema>;
 

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

@@ -0,0 +1,12 @@
+// Single shared instance — one createEventStoreExecutor per entity per
+// process is the framework convention, reused by every write path outside
+// the entity's own inline projection (tenant-destroy-hook, forget-extract-with-file-ref).
+
+import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import { documentExtractEntity, documentExtractsTable } from "./entity";
+
+export const documentExtractExecutor = createEventStoreExecutor(
+  documentExtractsTable,
+  documentExtractEntity,
+  { entityName: "document-extract" },
+);

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

@@ -1,15 +1,8 @@
 // kumiko-feature-version: 1
 //
-// document-ingest-foundation — Phase-1 (MVP) skeleton for the shared
-// PDF/Scan/Image → normalized-text ingest primitive. Owns the
-// `documentExtract` entity + tenant-config, and (Theme A, kumiko-framework
-// #1497) the fileRef.created trigger: a multiStreamProjection that validates
-// mime/size and — on OK — appends `documentIngest.requested`, the anchor
-// event the Phase-2 worker job (kumiko-enterprise LiteParse provider) reacts
-// to (event-trigger, not job-trigger — `files` exports no write-handler ref
-// for r.job's trigger.on to hang off, files-post-processing recipe pattern).
-// LiteParse itself lands in kumiko-enterprise#273-275. See
-// CosmicDriftGameStudio/kumiko-framework#1495 for the full phase breakdown.
+// Provider-driven PDF/Scan/Image → normalized-text ingest primitive. No
+// hardcoded mime allowlist or size cap — providers register via
+// EXT_DOCUMENT_INGEST_PROVIDER (see providers.ts).
 
 import { entityEventName } from "@cosmicdrift/kumiko-framework/db";
 import {
@@ -17,8 +10,11 @@ import {
   createTenantConfig,
   defineFeature,
   EXT_TENANT_DATA,
+  type MultiStreamApplyFn,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { normalizeMimeType } from "@cosmicdrift/kumiko-framework/files";
 import * as z from "zod";
+import { validateDocumentIngestProviderWiring } from "./boot-checks";
 import { documentExtractEntity } from "./entity";
 import {
   DOCUMENT_INGEST_AGGREGATE_TYPE,
@@ -29,39 +25,99 @@ import {
   documentIngestRequestedPayloadSchema,
   documentIngestSkippedPayloadSchema,
 } from "./events";
+import {
+  forgetExtractOnFileRefDeletedHook,
+  forgetExtractOnFileRefForgottenHook,
+  forgetOrphanedDocumentExtractHook,
+} from "./forget-extract-with-file-ref";
+import { EXT_DOCUMENT_INGEST_PROVIDER, resolveDocumentIngestProviders } from "./providers";
 import { documentExtractTenantDestroyHook } from "./tenant-destroy-hook";
 
 const FEATURE_NAME = "document-ingest-foundation";
 
 const FILE_REF_CREATED = entityEventName("fileRef", "created");
+const FILE_REF_RESTORED = entityEventName("fileRef", "restored");
+const FILE_REF_DELETED = entityEventName("fileRef", "deleted");
+const FILE_REF_FORGOTTEN = entityEventName("fileRef", "forgotten");
+// Executors write under entityName "document-extract" (executor.ts), not the
+// camelCase r.entity() name — the event type follows the executor.
+const DOCUMENT_EXTRACT_CREATED = entityEventName("document-extract", "created");
+
+type MspApplyContext = Parameters<MultiStreamApplyFn>[2];
 
-// Phase-1 scope (plan doc): PDF + raster images only. xlsx/docx/vision are
-// Phase 2, routed through separate providers, not this MSP.
-const ALLOWED_MIME_TYPES = new Set(["application/pdf", "image/png", "image/jpeg", "image/tiff"]);
-
-// ponytail: fixed cap, not tenant-config — the plan only calls out
-// maxPagesPerFile as tenant-configurable. Runs BEFORE the mime check for
-// the same reason it must run before isComplex() downstream: rejecting on
-// size is O(1), the checks after it are not (Spike: 699-page PDF). Chosen
-// on domain grounds — scanned invoices and official letters routinely land
-// in the 10-20mb range, well above file-routes.ts' unconstrained-upload
-// default (10mb); tests raise maxUploadSize instead of shrinking this.
-const MAX_FILE_BYTES = 25 * 1024 * 1024;
-
-// Narrow fileRef.created's generic entity payload at the MSP boundary.
-// Missing/invalid fields → skip (return), never cast — a bad size would
-// otherwise pass `undefined > MAX_FILE_BYTES` and a later appendDomainEvent
-// schema failure would dead the request-ingest consumer for all tenants.
-const fileRefCreatedPayloadSchema = z.object({
+// Missing/invalid fields → skip, never cast — a bad size would otherwise
+// pass a provider's maxFileBytes comparison and dead-letter the consumer.
+// Shared by fileRef.created (the entity fields directly) and fileRef.restored
+// (the same fields nested under `previous`, the soft-deleted snapshot).
+const fileRefIngestFieldsSchema = z.object({
   storageKey: z.string().min(1),
   fileName: z.string().min(1),
   mimeType: z.string().min(1),
   size: z.number().int().min(0),
 });
+type FileRefIngestFields = z.infer<typeof fileRefIngestFieldsSchema>;
+
+// Shared by fileRef.created and fileRef.restored — a restored fileRef goes
+// through the same provider routing/skip logic as a fresh upload, so a
+// delete→restore round-trip re-requests ingest instead of leaving the file
+// without an extract.
+async function requestIngestForFileRef(
+  event: { readonly aggregateId: string },
+  fileRef: FileRefIngestFields,
+  ctx: MspApplyContext,
+): Promise<void> {
+  const skip = (reason: "file-too-large" | "unsupported-mime-type") =>
+    ctx.unsafeAppendEvent({
+      aggregateId: event.aggregateId,
+      aggregateType: DOCUMENT_INGEST_AGGREGATE_TYPE,
+      type: DOCUMENT_INGEST_SKIPPED_EVENT_QN,
+      payload: {
+        fileRefId: event.aggregateId,
+        storageKey: fileRef.storageKey,
+        fileName: fileRef.fileName,
+        mimeType: fileRef.mimeType,
+        size: fileRef.size,
+        reason,
+      },
+    });
+
+  // Boot already refused an invalid/conflicting provider config — a
+  // throw here can only mean the registry changed since then, handled
+  // like any other apply throw (retry/dead-letter).
+  const providers = resolveDocumentIngestProviders(
+    ctx.registry.getExtensionUsages(EXT_DOCUMENT_INGEST_PROVIDER),
+  );
+  const provider = providers.get(normalizeMimeType(fileRef.mimeType));
+  // skip: no provider claims this mimeType — no ingest requested
+  if (!provider) {
+    await skip("unsupported-mime-type");
+    return;
+  }
+  // skip: over the winning provider's own cap — no ingest requested,
+  // upload itself already succeeded
+  if (fileRef.size > provider.maxFileBytes) {
+    await skip("file-too-large");
+    return;
+  }
+
+  await ctx.unsafeAppendEvent({
+    aggregateId: event.aggregateId,
+    aggregateType: DOCUMENT_INGEST_AGGREGATE_TYPE,
+    type: DOCUMENT_INGEST_REQUESTED_EVENT_QN,
+    payload: {
+      fileRefId: event.aggregateId,
+      storageKey: fileRef.storageKey,
+      fileName: fileRef.fileName,
+      mimeType: fileRef.mimeType,
+      size: fileRef.size,
+      provider: provider.name,
+    },
+  });
+}
 
 export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) => {
   r.describe(
-    "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, and a fileRef.created trigger that validates mime/size and requests ingest via `documentIngest.requested`. LiteParse provider wiring lands in follow-up features.",
+    "Shared PDF/Scan/Image → normalized-text ingest primitive. Owns the `documentExtract` entity (fileRefId, storageKey, per-page text + metadata) as an implicit entity-projection, the per-tenant `ocrLanguage`/`maxPagesPerFile` config keys, the `documentIngestProvider` extension-point providers register accepted mimeTypes/size caps under, and a fileRef.created/fileRef.restored trigger that resolves the provider for a file's mimeType and requests ingest via `documentIngest.requested` tagged with the winning provider — a delete→restore round-trip re-requests ingest the same way a fresh upload does. An orphan-extract guard forgets any `documentExtract` whose fileRef is no longer live at processing time, regardless of how a provider's own write races the fileRef's delete/forget — providers should write through `writeDocumentExtractForLiveFileRef`.",
   );
   r.uiHints({
     displayLabel: "Document Ingest Foundation",
@@ -69,7 +125,7 @@ export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) =
     recommended: false,
   });
   // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
-  // tenant-subject ciphertext and needs the destroy hook below (#1621).
+  // tenant-subject ciphertext and needs the destroy hook below.
   r.requires("config", "tenant-lifecycle");
 
   r.entity("documentExtract", documentExtractEntity);
@@ -77,6 +133,10 @@ export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) =
     destroy: documentExtractTenantDestroyHook,
   });
 
+  // No onRegister: resolution happens at boot and per-apply, not on register.
+  r.extendsRegistrar(EXT_DOCUMENT_INGEST_PROVIDER, {});
+  r.bootCheck(({ features }) => validateDocumentIngestProviderWiring(features));
+
   const ocrLanguageConfigKey = r.config(
     "ocrLanguage",
     createTenantConfig("text", {
@@ -103,9 +163,20 @@ export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) =
   );
 
   // "fileName" can carry a real person's name; the payload has no user-subject
-  // field to encrypt it under, so piiFields stays "none" pending #2776.
+  // field to encrypt it under, so piiFields stays "none" for now.
   r.defineEvent(DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, documentIngestRequestedPayloadSchema, {
     piiFields: "none",
+    version: 2,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        // "unknown" can never match a real where.provider filter — an
+        // upcast v1 row reads as unclaimed instead of silently misrouting to
+        // whichever provider happens to be mounted today.
+        transform: { default: { provider: "unknown" } },
+      },
+    ],
   });
   r.defineEvent(DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestSkippedPayloadSchema, {
     piiFields: "none",
@@ -117,50 +188,32 @@ export const documentIngestFoundationFeature = defineFeature(FEATURE_NAME, (r) =
       [FILE_REF_CREATED]: async (event, _tx, ctx) => {
         // entity-event payloads are generic Record<string, unknown> — parse
         // at the MSP boundary (same pattern as storage-tracking's readNumber).
-        const parsed = fileRefCreatedPayloadSchema.safeParse(event.payload);
+        const parsed = fileRefIngestFieldsSchema.safeParse(event.payload);
         // skip: malformed / incomplete payload — don't poison the consumer
         if (!parsed.success) return;
-        const payload = parsed.data;
-
-        const skip = (reason: "file-too-large" | "unsupported-mime-type") =>
-          ctx.unsafeAppendEvent({
-            aggregateId: event.aggregateId,
-            aggregateType: DOCUMENT_INGEST_AGGREGATE_TYPE,
-            type: DOCUMENT_INGEST_SKIPPED_EVENT_QN,
-            payload: {
-              fileRefId: event.aggregateId,
-              storageKey: payload.storageKey,
-              fileName: payload.fileName,
-              mimeType: payload.mimeType,
-              size: payload.size,
-              reason,
-            },
-          });
-
-        // skip: over the fixed cap — no ingest requested, upload itself already succeeded
-        if (payload.size > MAX_FILE_BYTES) {
-          await skip("file-too-large");
-          return;
-        }
-        // skip: outside the Phase-1 mime allowlist — no ingest requested
-        if (!ALLOWED_MIME_TYPES.has(payload.mimeType)) {
-          await skip("unsupported-mime-type");
-          return;
-        }
-
-        await ctx.unsafeAppendEvent({
-          aggregateId: event.aggregateId,
-          aggregateType: DOCUMENT_INGEST_AGGREGATE_TYPE,
-          type: DOCUMENT_INGEST_REQUESTED_EVENT_QN,
-          payload: {
-            fileRefId: event.aggregateId,
-            storageKey: payload.storageKey,
-            fileName: payload.fileName,
-            mimeType: payload.mimeType,
-            size: payload.size,
-          },
-        });
+        await requestIngestForFileRef(event, parsed.data, ctx);
       },
+      [FILE_REF_RESTORED]: async (event, _tx, ctx) => {
+        // fileRef.restored carries { previous }, the pre-restore soft-deleted
+        // row (event-store-executor-write.ts restore()) — same field shape
+        // as fileRef.created's payload.
+        const parsed = fileRefIngestFieldsSchema.safeParse(event.payload["previous"]);
+        // skip: malformed / incomplete previous snapshot — don't poison the consumer
+        if (!parsed.success) return;
+        await requestIngestForFileRef(event, parsed.data, ctx);
+      },
+    },
+  });
+
+  // fileRef delete/forget cleanup: documentExtract rows are derived data —
+  // once the source file is gone (soft-deleted or Art.17-forgotten), the
+  // extracted text has no reason to survive it either.
+  r.multiStreamProjection({
+    name: "forget-extract-with-file-ref",
+    apply: {
+      [FILE_REF_DELETED]: forgetExtractOnFileRefDeletedHook,
+      [FILE_REF_FORGOTTEN]: forgetExtractOnFileRefForgottenHook,
+      [DOCUMENT_EXTRACT_CREATED]: forgetOrphanedDocumentExtractHook,
     },
   });
 

package/src/document-ingest-foundation/file-ref-liveness.ts

@@ -0,0 +1,10 @@
+// db.fetchOne applies TenantDb's tenant predicate but no isDeleted filter
+// (see event-store-executor-write.ts's restore()/forget() comments) — a
+// soft-deleted fileRef still round-trips as a row here.
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import { fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
+
+export async function isFileRefLive(tenantDb: TenantDb, fileRefId: string): Promise<boolean> {
+  const row = await tenantDb.fetchOne<{ isDeleted: boolean }>(fileRefsTable, { id: fileRefId });
+  return row !== undefined && row.isDeleted !== true;
+}