@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/document-ingest-foundation/feature.ts

@@ -0,0 +1,226 @@
+// kumiko-feature-version: 1
+//
+// 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 {
+  access,
+  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.js";
+import { documentExtractEntity } from "./entity.js";
+import {
+  DOCUMENT_INGEST_AGGREGATE_TYPE,
+  DOCUMENT_INGEST_REQUESTED_EVENT_QN,
+  DOCUMENT_INGEST_REQUESTED_EVENT_SHORT,
+  DOCUMENT_INGEST_SKIPPED_EVENT_QN,
+  DOCUMENT_INGEST_SKIPPED_EVENT_SHORT,
+  documentIngestRequestedPayloadSchema,
+  documentIngestSkippedPayloadSchema,
+} from "./events.js";
+import {
+  forgetExtractOnFileRefDeletedHook,
+  forgetExtractOnFileRefForgottenHook,
+  forgetOrphanedDocumentExtractHook,
+} from "./forget-extract-with-file-ref.js";
+import {
+  EXT_DOCUMENT_INGEST_PROVIDER,
+  resolveDocumentIngestProviders,
+  UNCLAIMED_PROVIDER_SENTINEL,
+} from "./providers.js";
+import { documentExtractTenantDestroyHook } from "./tenant-destroy-hook.js";
+
+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];
+
+// 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, 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",
+    category: "storage",
+    recommended: false,
+  });
+  // tenant-lifecycle hosts EXT_TENANT_DATA — documentExtract.pages is
+  // tenant-subject ciphertext and needs the destroy hook below.
+  r.requires("config", "tenant-lifecycle");
+
+  r.entity("documentExtract", documentExtractEntity);
+  r.useExtension(EXT_TENANT_DATA, "documentExtract", {
+    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", {
+      default: "deu+eng",
+      // Tesseract -l argument syntax: one or more 3-letter language codes
+      // joined by "+" (e.g. "deu+eng"). Unconstrained free text here would
+      // reach the OCR provider call unvalidated (#1501).
+      pattern: { regex: "^[a-z]{3}(\\+[a-z]{3})*$" },
+      write: access.roles("TenantAdmin", "SystemAdmin"),
+      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+    }),
+  );
+  const maxPagesPerFileConfigKey = r.config(
+    "maxPagesPerFile",
+    createTenantConfig("number", {
+      default: 50,
+      // Without a bound a tenant could set 0 (silently kills ingest) or an
+      // unbounded value (OCR worker runs per-file for as long as the PDF
+      // has pages — job-queue starvation) (#1501).
+      bounds: { min: 1, max: 500 },
+      write: access.roles("TenantAdmin", "SystemAdmin"),
+      read: access.roles("TenantAdmin", "SystemAdmin", "User"),
+    }),
+  );
+
+  // "fileName" can carry a real person's name, but it reaches both events already as the
+  // fileRef's own self-subject ciphertext (copied from fileRef.created/restored), which
+  // append() passes through; shredding the fileRef's key shreds it here too.
+  r.defineEvent(DOCUMENT_INGEST_REQUESTED_EVENT_SHORT, documentIngestRequestedPayloadSchema, {
+    piiFields: "none",
+    version: 2,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        // The sentinel can never match a real where.provider filter (providers
+        // may not register under it) — an upcast v1 row reads as unclaimed
+        // instead of silently misrouting to a currently mounted provider.
+        transform: { default: { provider: UNCLAIMED_PROVIDER_SENTINEL } },
+      },
+    ],
+  });
+  r.defineEvent(DOCUMENT_INGEST_SKIPPED_EVENT_SHORT, documentIngestSkippedPayloadSchema, {
+    piiFields: "none",
+  });
+
+  r.multiStreamProjection({
+    name: "request-ingest",
+    apply: {
+      [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 = fileRefIngestFieldsSchema.safeParse(event.payload);
+        // skip: malformed / incomplete payload — don't poison the consumer
+        if (!parsed.success) return;
+        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,
+    },
+  });
+
+  return { ocrLanguageConfigKey, maxPagesPerFileConfigKey };
+});

package/packages/bundled-features/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;
+}

package/packages/bundled-features/src/document-ingest-foundation/forget-extract-with-file-ref.ts

@@ -0,0 +1,84 @@
+// documentExtract is derived data — once its source fileRef is gone (soft
+// delete or forget), the extract has no reason to survive it. A restored
+// fileRef is re-ingested by feature.ts's request-ingest MSP
+// (fileRef.restored), so a fresh extract replaces the forgotten one.
+//
+// forget(), not deleteMany: documentExtract is an ES-managed implicit
+// projection, so forget() replays correctly on rebuild. This MSP itself has
+// no `table`, so rebuildMultiStreamProjection never targets it directly.
+//
+// Also reacts to documentExtract.created: providers write extracts
+// themselves (own executor call), racing this consumer's fileRef.deleted/
+// forgotten handling. Each handler re-checks current fileRef liveness at
+// processing time, so no extract survives regardless of write/delete order —
+// this covers providers that bypass write-document-extract.ts's helper too.
+
+import { createTenantDb, type TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { MultiStreamApplyFn } from "@cosmicdrift/kumiko-framework/engine";
+import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import type { WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { documentExtractsTable } from "./entity.js";
+import { documentExtractExecutor } from "./executor.js";
+import { isFileRefLive } from "./file-ref-liveness.js";
+
+// WriteResult.error is always a plain WriteErrorInfo object, never a
+// KumikoError instance (JSON-serializable for the dispatcher's idempotency-key
+// storage) — compare on .code, not instanceof.
+function isNotFoundWriteError(error: WriteErrorInfo): boolean {
+  return error.code === "not_found";
+}
+
+async function forgetExtractsForFileRef(
+  event: Parameters<MultiStreamApplyFn>[0],
+  tenantDb: TenantDb,
+): Promise<void> {
+  const rows = await tenantDb.selectMany<{ id: string }>(documentExtractsTable, {
+    fileRefId: event.aggregateId,
+  });
+  const user = createSystemUser(event.tenantId);
+  for (const row of rows) {
+    const result = await documentExtractExecutor.forget({ id: row.id }, user, tenantDb);
+    if (result.isSuccess) continue;
+    // Idempotent: a concurrent/redelivered apply that already forgot this
+    // row is not an error — anything else (version conflict, ownership
+    // denial) must surface so the dispatcher retries/dead-letters instead of
+    // silently leaving the extract behind.
+    if (isNotFoundWriteError(result.error)) continue;
+    throw new Error(
+      `document-ingest-foundation: failed to forget documentExtract ${row.id} for fileRef ${event.aggregateId}: ${result.error.message}`,
+    );
+  }
+}
+
+const documentExtractCreatedPayloadSchema = z.object({ fileRefId: z.string().min(1) });
+
+export const forgetOrphanedDocumentExtractHook: MultiStreamApplyFn = async (event, tx) => {
+  const parsed = documentExtractCreatedPayloadSchema.safeParse(event.payload);
+  // skip: malformed payload — don't poison the consumer
+  if (!parsed.success) return;
+  const tenantDb = createTenantDb(tx, event.tenantId);
+  // skip: fileRef still live — the extract is legitimate
+  if (await isFileRefLive(tenantDb, parsed.data.fileRefId)) return;
+  const user = createSystemUser(event.tenantId);
+  const result = await documentExtractExecutor.forget({ id: event.aggregateId }, user, tenantDb);
+  // skip: forgotten now, or already gone via a concurrent/redelivered apply
+  if (result.isSuccess || isNotFoundWriteError(result.error)) return;
+  throw new Error(
+    `document-ingest-foundation: failed to forget orphaned documentExtract ${event.aggregateId}: ${result.error.message}`,
+  );
+};
+
+export const forgetExtractOnFileRefDeletedHook: MultiStreamApplyFn = async (event, tx) => {
+  const tenantDb = createTenantDb(tx, event.tenantId);
+  // skip: fileRef is live again — request-ingest and this consumer poll via
+  // separate cursors, so a delete→restore round-trip can finish before this
+  // consumer sees fileRef.deleted; forgetting would drop the live file's extract.
+  if (await isFileRefLive(tenantDb, event.aggregateId)) return;
+  await forgetExtractsForFileRef(event, tenantDb);
+};
+
+export const forgetExtractOnFileRefForgottenHook: MultiStreamApplyFn = async (event, tx) => {
+  const tenantDb = createTenantDb(tx, event.tenantId);
+  await forgetExtractsForFileRef(event, tenantDb);
+};

package/packages/bundled-features/src/document-ingest-foundation/index.ts

@@ -0,0 +1,34 @@
+// Public API of the document-ingest-foundation bundled-feature.
+
+export {
+  type DocumentExtractMeta,
+  documentExtractEntity,
+  documentExtractsTable,
+  type IngestPage,
+} from "./entity.js";
+export {
+  DOCUMENT_INGEST_AGGREGATE_TYPE,
+  DOCUMENT_INGEST_REQUESTED_EVENT_QN,
+  DOCUMENT_INGEST_REQUESTED_EVENT_SHORT,
+  DOCUMENT_INGEST_SKIPPED_EVENT_QN,
+  DOCUMENT_INGEST_SKIPPED_EVENT_SHORT,
+  type DocumentIngestRequestedPayload,
+  type DocumentIngestSkippedPayload,
+  documentIngestRequestedPayloadSchema,
+  documentIngestSkippedPayloadSchema,
+} from "./events.js";
+export { documentIngestFoundationFeature } from "./feature.js";
+export { readIngestPages, writeIngestPages } from "./pages.js";
+export {
+  type DocumentIngestProviderOptions,
+  documentIngestProviderOptionsSchema,
+  documentIngestProviderTrigger,
+  EXT_DOCUMENT_INGEST_PROVIDER,
+  listIngestibleMimeTypes,
+  type ResolvedDocumentIngestProvider,
+  resolveDocumentIngestProviders,
+} from "./providers.js";
+export {
+  type DocumentExtractWriteResult,
+  writeDocumentExtractForLiveFileRef,
+} from "./write-document-extract.js";

package/packages/bundled-features/src/document-ingest-foundation/pages.ts

@@ -0,0 +1,34 @@
+// Wire-format helpers for `documentExtract.pages` — the column is encrypted
+// longText (jsonb has no encryption support), so writers must persist
+// JSON.stringify(IngestPage[]) and readers must parse back. Centralising
+// the codec here keeps liteparse + recipe consumers lockstep with the
+// entity shape (kumiko-framework#1549/1).
+
+import type { IngestPage } from "./entity.js";
+
+export function writeIngestPages(pages: readonly IngestPage[]): string {
+  return JSON.stringify(pages);
+}
+
+export function readIngestPages(raw: unknown): IngestPage[] {
+  if (raw == null) return [];
+  // Executor decrypt returns the plaintext string; raw SQL / stale jsonb
+  // rows may still surface as an already-parsed array — accept both.
+  const parsed: unknown = typeof raw === "string" ? parseJson(raw) : raw;
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter(isIngestPage);
+}
+
+function parseJson(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function isIngestPage(value: unknown): value is IngestPage {
+  if (value === null || typeof value !== "object") return false;
+  const page = value as { pageNumber?: unknown; text?: unknown };
+  return typeof page.pageNumber === "number" && typeof page.text === "string";
+}

package/packages/bundled-features/src/document-ingest-foundation/providers.ts

@@ -0,0 +1,87 @@
+// document-ingest-foundation — provider extension-point. One shared
+// documentIngest.requested QN fans out to every mounted provider's job,
+// partitioned by documentIngestProviderTrigger's where-filter.
+
+import type { FeatureDefinition, Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { normalizeMimeType } from "@cosmicdrift/kumiko-framework/files";
+import * as z from "zod";
+import { DOCUMENT_INGEST_REQUESTED_EVENT_QN } from "./events.js";
+
+export const EXT_DOCUMENT_INGEST_PROVIDER = "documentIngestProvider" as const;
+
+export const documentIngestProviderOptionsSchema = z.object({
+  mimeTypes: z.array(z.string().min(1)).min(1),
+  maxFileBytes: z.number().int().positive(),
+});
+export type DocumentIngestProviderOptions = z.infer<typeof documentIngestProviderOptionsSchema>;
+
+// r.useExtension options-shape, co-located since the framework never imports upward.
+declare module "@cosmicdrift/kumiko-framework/engine" {
+  interface KumikoExtensionOptionsMap {
+    [EXT_DOCUMENT_INGEST_PROVIDER]: DocumentIngestProviderOptions;
+  }
+}
+
+export type ResolvedDocumentIngestProvider = {
+  readonly name: string;
+  readonly maxFileBytes: number;
+};
+
+// Stamped on upcast v1 documentIngest.requested events; a provider may not
+// claim it, or replayed v1 events would route to that provider.
+export const UNCLAIMED_PROVIDER_SENTINEL = "unknown";
+
+type ExtensionUsages = FeatureDefinition["extensionUsages"];
+
+// Throws on an invalid options shape or two providers claiming the same
+// normalized mimeType — callers decide whether that's boot-fatal.
+export function resolveDocumentIngestProviders(
+  usages: ExtensionUsages,
+): ReadonlyMap<string, ResolvedDocumentIngestProvider> {
+  const byMime = new Map<string, ResolvedDocumentIngestProvider>();
+  for (const usage of usages) {
+    if (usage.extensionName !== EXT_DOCUMENT_INGEST_PROVIDER) continue;
+    if (usage.entityName === UNCLAIMED_PROVIDER_SENTINEL) {
+      throw new Error(
+        `document-ingest-foundation: provider name "${UNCLAIMED_PROVIDER_SENTINEL}" is reserved for upcast legacy events.`,
+      );
+    }
+    const parsed = documentIngestProviderOptionsSchema.safeParse(usage.options);
+    if (!parsed.success) {
+      throw new Error(
+        `document-ingest-foundation: provider "${usage.entityName}" registered invalid options via ` +
+          `r.useExtension(EXT_DOCUMENT_INGEST_PROVIDER, "${usage.entityName}", ...) — ${parsed.error.message}`,
+      );
+    }
+    for (const mimeType of parsed.data.mimeTypes) {
+      const normalized = normalizeMimeType(mimeType);
+      const existing = byMime.get(normalized);
+      if (existing && existing.name !== usage.entityName) {
+        throw new Error(
+          `document-ingest-foundation: providers "${existing.name}" and "${usage.entityName}" both claim mimeType ` +
+            `"${normalized}" — each mimeType may have exactly one registered provider.`,
+        );
+      }
+      byMime.set(normalized, { name: usage.entityName, maxFileBytes: parsed.data.maxFileBytes });
+    }
+  }
+  return byMime;
+}
+
+export function listIngestibleMimeTypes(registry: Registry): readonly string[] {
+  const usages = registry.getExtensionUsages(EXT_DOCUMENT_INGEST_PROVIDER);
+  return [...resolveDocumentIngestProviders(usages).keys()].sort();
+}
+
+export type DocumentIngestProviderJobTrigger = {
+  readonly on: typeof DOCUMENT_INGEST_REQUESTED_EVENT_QN;
+  readonly where: { readonly provider: string };
+};
+
+// The trigger every provider's job must use — filters the shared
+// documentIngest.requested QN down to just this provider's requests.
+export function documentIngestProviderTrigger(
+  providerName: string,
+): DocumentIngestProviderJobTrigger {
+  return { on: DOCUMENT_INGEST_REQUESTED_EVENT_QN, where: { provider: providerName } };
+}

package/packages/bundled-features/src/document-ingest-foundation/tenant-destroy-hook.ts

@@ -0,0 +1,34 @@
+// Tenant-destroy hook for the documentExtract entity-projection (#1621).
+//
+// Per-row forget() through the executor, not a bulk deleteMany: documentExtract
+// is an ES-managed implicit projection, so a store-table write here would be
+// eventless and a later rebuild would replay the historical create events and
+// resurrect every row this hook removed. forget() (Art. 17 hard-purge) is
+// replayed by the implicit projection itself, which keeps the erasure
+// rebuild-safe — the same reasoning as tenant-lifecycle's membership stage,
+// and the reason the feature owns an r.entity instead of an r.projection
+// (kumiko-framework#1495). The `pages` ciphertext dies separately when the
+// pipeline's later `subject-keys` stage erases the tenant subject key.
+
+import { createSystemUser, type TenantDataDestroyHook } from "@cosmicdrift/kumiko-framework/engine";
+import { documentExtractsTable } from "./entity.js";
+import { documentExtractExecutor } from "./executor.js";
+
+export const documentExtractTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
+  const rows = await ctx.db.selectMany<{ id: string }>(documentExtractsTable, {
+    tenantId: ctx.tenantId,
+  });
+  const user = createSystemUser(ctx.tenantId);
+  for (const row of rows) {
+    const result = await documentExtractExecutor.forget({ id: row.id }, user, ctx.db);
+    // Executor writes return {isSuccess:false} instead of throwing — a
+    // discarded result would report this destroy stage "succeeded" while the
+    // extracted document text survives. Throw so the pipeline's retry/abandon
+    // handling sees it.
+    if (!result.isSuccess) {
+      throw new Error(
+        `document-ingest-foundation: failed to forget documentExtract ${row.id} for tenant ${ctx.tenantId}: ${result.error.message}`,
+      );
+    }
+  }
+};

package/packages/bundled-features/src/document-ingest-foundation/write-document-extract.ts

@@ -0,0 +1,57 @@
+// Providers write documentExtract rows themselves (their own executor
+// call on ctx.db) rather than through a request/response API, so this is
+// the one place that write must go through to stay race-safe against a
+// concurrent fileRef delete/forget — see forget-extract-with-file-ref.ts.
+
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { type DocumentExtractMeta, documentExtractsTable, type IngestPage } from "./entity.js";
+import { documentExtractExecutor } from "./executor.js";
+import { isFileRefLive } from "./file-ref-liveness.js";
+import { writeIngestPages } from "./pages.js";
+
+export type DocumentExtractWriteResult =
+  | { readonly kind: "written"; readonly documentExtractId: string }
+  | { readonly kind: "skipped"; readonly reason: "file_ref_deleted" | "already_extracted" };
+
+export async function writeDocumentExtractForLiveFileRef(input: {
+  readonly tenantDb: TenantDb;
+  readonly actor: SessionUser;
+  readonly fileRefId: string;
+  readonly storageKey: string;
+  readonly pages: readonly IngestPage[];
+  readonly meta: DocumentExtractMeta & Readonly<Record<string, unknown>>;
+}): Promise<DocumentExtractWriteResult> {
+  // Early-skip optimization only — a fileRef deleted/forgotten right after
+  // this check still gets caught by forget-extract-with-file-ref.ts's
+  // documentExtract.created handler, which is the actual race-safety guarantee.
+  if (!(await isFileRefLive(input.tenantDb, input.fileRefId))) {
+    return { kind: "skipped", reason: "file_ref_deleted" };
+  }
+  // A redelivered documentIngest.requested, or the one a delete→restore race
+  // re-requests while the old extract is still standing, must not create a
+  // second extract for the same fileRef.
+  const existing = await input.tenantDb.selectMany<{ id: string }>(documentExtractsTable, {
+    fileRefId: input.fileRefId,
+  });
+  if (existing.length > 0) {
+    return { kind: "skipped", reason: "already_extracted" };
+  }
+  const result = await documentExtractExecutor.create(
+    {
+      fileRefId: input.fileRefId,
+      storageKey: input.storageKey,
+      pages: writeIngestPages(input.pages),
+      meta: input.meta,
+    },
+    input.actor,
+    input.tenantDb,
+  );
+  if (!result.isSuccess) {
+    throw new InternalError({
+      message: `document-ingest-foundation: failed to write documentExtract for fileRef ${input.fileRefId}: ${result.error.message}`,
+    });
+  }
+  return { kind: "written", documentExtractId: String(result.data.id) };
+}

package/packages/bundled-features/src/feature-toggles/changes.json

@@ -0,0 +1,31 @@
+[
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "A toggle flip signalled during the initial load survives the snapshot read"
+  },
+  {
+    "version": "0.165.0",
+    "type": "fix",
+    "title": "compose-tier-resolver: fixed requires-cascade",
+    "detail": "Tier resolver now correctly handles the requires-cascade and marks non-toggleable features properly."
+  },
+  {
+    "version": "0.163.0",
+    "type": "fix",
+    "title": "feature-toggles: register `store_global_feature_state` via `r.storeTable()` (exported as …",
+    "detail": "feature-toggles: register `store_global_feature_state` via `r.storeTable()` (exported as `globalFeatureStateTableMeta`). Previously the table was only a plain Drizzle export with no store-table meta, so `collectTableMetas(FEATURES)` never saw it — `kumiko schema generate` reported no changes for any app mounting `createFeatureTogglesFeature()`, and the table was missing in any DB that wasn't manually provisioned (e.g. via `unsafePushTables` in tests). `setupTestStack` now auto-provisions the table like every other `r.storeTable()` feature."
+  },
+  {
+    "version": "0.163.0",
+    "type": "fix",
+    "title": "feature-toggles: fix `composeTierResolverWithGlobalToggles` to actually grant tier-unawar…",
+    "detail": "feature-toggles: fix `composeTierResolverWithGlobalToggles` to actually grant tier-unaware toggleable features. The previous version only ever narrowed the tier resolver's own set — a toggleable feature that no tier's `features` list mentions at all (e.g. a pure operator kill-switch like a self-registration toggle, never differentiated by plan) could never appear, regardless of its declared default or an explicit `true` override, because narrowing can only remove names, never add ones the tier never granted. Now takes a third `registry` argument and unions in `computeEffectiveFeatures`' normal cascade for every feature name absent from `tierResolver(SYSTEM_TENANT_ID)` (the tier-managed set) — tier-managed toggleables keep the narrow-only semantics from before, tier-unaware ones are governed purely by their own default/override. - @cosmicdrift/kumiko-framework@0.163.0 - @cosmicdrift/kumiko-headless@0.163.0 - @cosmicdrift/kumiko-renderer@0.163.0 - @cosmicdrift/kumiko-dispatcher-live@0.163.0 - @cosmicdrift/kumiko-renderer-web@0.163.0"
+  },
+  {
+    "version": "0.162.0",
+    "type": "improvement",
+    "title": "feature-toggles: add `composeTierResolverWithGlobalToggles` to combine a tier-engine `ten…",
+    "detail": "feature-toggles: add `composeTierResolverWithGlobalToggles` to combine a tier-engine `tenantTierResolver` with a global `GlobalFeatureToggleRuntime` into a single `effectiveFeatures` resolver. Apps running both tier-engine (per-tenant feature cuts) and feature-toggles (global operator switches, e.g. a runtime kill-switch not tied to any tier) previously had no way to compose them — the framework only auto-wires one `tenantTierResolver` plugin. The global layer only narrows what the tier grants (an explicit `enabled:false` row removes a feature; no row or `true` leaves the tier's grant untouched) — it never falls back to a toggleable feature's own default, which would otherwise silently disable every tier-gated toggleable feature the moment feature-toggles gets composed in. Also adds `GlobalFeatureToggleRuntime.readOverride(name)` for the raw per-feature override, bypassing the requires() cascade."
+  }
+]