@cosmicdrift/kumiko-samples 0.398.0 → 0.400.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.398.0",
+  "version": "0.400.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.398.0",
+  "version": "0.400.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -116,6 +116,7 @@
     "./shared/row-bound-grant": "./src/shared/row-bound-grant.ts",
     "./shared/mail-template-body": "./src/shared/mail-template-body.ts",
     "./delivery": "./src/delivery/index.ts",
+    "./documents": "./src/documents/index.ts",
     "./delivery/web": "./src/delivery/web/index.ts",
     "./channel-in-app": "./src/channel-in-app/index.ts",
     "./channel-email": "./src/channel-email/index.ts",
@@ -570,6 +571,10 @@
         "types": "./dist/delivery/index.d.ts",
         "default": "./dist/delivery/index.js"
       },
+      "./documents": {
+        "types": "./dist/documents/index.d.ts",
+        "default": "./dist/documents/index.js"
+      },
       "./delivery/web": {
         "types": "./dist/delivery/web/index.d.ts",
         "default": "./dist/delivery/web/index.js"

package/packages/bundled-features/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Shorter documents checkbox text in the consent box",
+    "detail": "With `consumerProtection.documentsAcknowledgement: true` the checkbox now reads \"I have read and agree to the Terms and the Refund Policy.\" (de: \"Ich habe die AGB und die Erstattungsrichtlinie gelesen und bin mit ihnen einverstanden.\"), or without a refund link only the terms. The privacy policy stays a link. The text is part of `consentTextVersion`, so apps with the option on get a new version hash; consents recorded earlier keep their stored version."
+  },
   {
     "version": "0.398.0",
     "type": "improvement",

package/packages/bundled-features/src/billing-foundation/consumer-protection/consent-text.ts

@@ -45,14 +45,12 @@ const DOCUMENTS_ACKNOWLEDGEMENT_TEXTS: Readonly<
 > = {
   de: {
     withRefund:
-      "Ich habe die AGB, die Erstattungsrichtlinie und die Datenschutzerklärung gelesen. Mit den AGB und der Erstattungsrichtlinie bin ich einverstanden.",
-    withoutRefund:
-      "Ich habe die AGB und die Datenschutzerklärung gelesen. Mit den AGB bin ich einverstanden.",
+      "Ich habe die AGB und die Erstattungsrichtlinie gelesen und bin mit ihnen einverstanden.",
+    withoutRefund: "Ich habe die AGB gelesen und bin mit ihnen einverstanden.",
   },
   en: {
-    withRefund:
-      "I have read the Terms, the Refund Policy and the Privacy Policy, and I agree to the Terms and the Refund Policy.",
-    withoutRefund: "I have read the Terms and the Privacy Policy, and I agree to the Terms.",
+    withRefund: "I have read and agree to the Terms and the Refund Policy.",
+    withoutRefund: "I have read and agree to the Terms.",
   },
 };
 

package/packages/bundled-features/src/channel-in-app/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Inbox cursor, total and navigation target for the shell bell",
+    "detail": "`channel-in-app:query:inbox` accepts a `cursor` and answers `{ rows, nextCursor, total }`; each row carries `target` (`{ screenId, entityId? }` or null) parsed from `data.target`. Build the target with `inAppTarget(screenId, entityId?)`; a malformed target is dropped and the notification is still delivered. The SSE frame `channel-in-app:event:delivered` now carries only `{ id, userId, notificationType }`, and a failing push no longer fails the delivery because the row is already stored. The shared contract lives in `@cosmicdrift/kumiko-types/in-app-notification-types`."
+  },
   {
     "version": "0.354.0",
     "type": "fix",

package/packages/bundled-features/src/channel-in-app/constants.ts

@@ -1,11 +1,11 @@
-export const CHANNEL_IN_APP_FEATURE = "channel-in-app" as const;
+import {
+  IN_APP_NOTIFICATION_FEATURE,
+  IN_APP_NOTIFICATION_QUERIES,
+  IN_APP_NOTIFICATION_WRITES,
+} from "@cosmicdrift/kumiko-types/in-app-notification-types";
 
-export const InAppHandlers = {
-  markRead: "channel-in-app:write:mark-read",
-  markAllRead: "channel-in-app:write:mark-all-read",
-} as const;
+export const CHANNEL_IN_APP_FEATURE = IN_APP_NOTIFICATION_FEATURE;
 
-export const InAppQueries = {
-  inbox: "channel-in-app:query:inbox",
-  unreadCount: "channel-in-app:query:unread-count",
-} as const;
+export const InAppHandlers = IN_APP_NOTIFICATION_WRITES;
+
+export const InAppQueries = IN_APP_NOTIFICATION_QUERIES;

package/packages/bundled-features/src/channel-in-app/feature.ts

@@ -10,7 +10,7 @@ import { inAppMessagesTableMeta } from "./tables.ts";
 export function createChannelInAppFeature(): FeatureDefinition {
   return defineFeature("channel-in-app", (r) => {
     r.describe(
-      "Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.",
+      "Persists notifications to an in-app inbox table so users can page through them via `queries.inbox` (cursor, total, parsed `target`) and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. A notification links to a screen when `data.target` is set with `inAppTarget(screenId, entityId?)`. The renderer shell shows a bell with a live unread badge whenever this feature is mounted. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.",
     );
     r.uiHints({
       displayLabel: "In-App Inbox",

package/packages/bundled-features/src/channel-in-app/handlers/inbox.query.ts

@@ -1,13 +1,17 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { parseStoredNotificationData, targetOfNotificationData } from "../in-app-target.ts";
 import { inAppMessagesTable } from "../tables.ts";
 
+const SERIAL_ID_PATTERN = /^\d{1,15}$/;
+
 export const inboxQuery = defineQueryHandler({
   name: "inbox",
   schema: z.object({
     limit: z.number().min(1).max(100).default(50),
     unreadOnly: z.boolean().default(false),
+    cursor: z.string().regex(SERIAL_ID_PATTERN).optional(),
   }),
   access: {
     openToAll: {
@@ -17,14 +21,34 @@ export const inboxQuery = defineQueryHandler({
     },
   },
   description:
-    "Lists the calling user's own in-app notification messages newest-first, optionally only the unread ones; use it to show or inspect a user's notification inbox.",
+    "Lists the calling user's own in-app notification messages newest-first with a parsed navigation target, optionally only the unread ones. Pass the returned nextCursor as cursor for the next page; total counts all matching messages, not just the page. Use it to show or inspect a user's notification inbox.",
   handler: async (query, ctx) => {
-    const where: Record<string, unknown> = { userId: query.user.id };
-    if (query.payload.unreadOnly) where["isRead"] = false;
-    const rows = await selectMany(ctx.db, inAppMessagesTable, where, {
-      limit: query.payload.limit,
-      orderBy: { col: "createdAt", direction: "desc" },
+    const { limit, unreadOnly, cursor } = query.payload;
+    const ownMessages: Record<string, unknown> = { userId: query.user.id };
+    if (unreadOnly) ownMessages["isRead"] = false;
+
+    const pageWhere =
+      cursor === undefined ? ownMessages : { ...ownMessages, id: { lt: Number(cursor) } };
+    // One extra row tells whether another page exists without a second query.
+    const fetched = await selectMany(ctx.db, inAppMessagesTable, pageWhere, {
+      limit: limit + 1,
+      orderBy: { col: "id", direction: "desc" },
+    });
+    const page = fetched.slice(0, limit);
+    const lastRow = page[page.length - 1];
+    const nextCursor = fetched.length > limit && lastRow ? String(lastRow["id"]) : null;
+
+    const [totalRow] = await ctx.db.aggregate(
+      inAppMessagesTable,
+      { measure: { fn: "count" } },
+      ownMessages,
+    );
+
+    const rows = page.map((row) => {
+      const storedData = row["data"];
+      const data = parseStoredNotificationData(typeof storedData === "string" ? storedData : null);
+      return { ...row, target: targetOfNotificationData(data) };
     });
-    return { rows };
+    return { rows, nextCursor, total: totalRow?.value ?? 0 };
   },
 });

package/packages/bundled-features/src/channel-in-app/handlers/unread-count.query.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.ts";
@@ -16,13 +15,11 @@ export const unreadCountQuery = defineQueryHandler({
   description:
     "Counts the calling user's unread in-app notification messages; use it for an inbox badge or to check whether a user has pending notifications.",
   handler: async (query, ctx) => {
-    // The query helpers in db/query.ts have no aggregate helper, so selectMany returns all matching
-    // rows and count() runs in JS. This is acceptable because unread counts are low-cardinality and
-    // user-scoped, with at most a few hundred rows; use raw .unsafe() with COUNT(*) if that grows.
-    const rows = await selectMany(ctx.db, inAppMessagesTable, {
-      userId: query.user.id,
-      isRead: false,
-    });
-    return { count: rows.length };
+    const [countRow] = await ctx.db.aggregate(
+      inAppMessagesTable,
+      { measure: { fn: "count" } },
+      { userId: query.user.id, isRead: false },
+    );
+    return { count: countRow?.value ?? 0 };
   },
 });

package/packages/bundled-features/src/channel-in-app/in-app-channel.ts

@@ -1,7 +1,12 @@
 import { tenantChannel } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { IN_APP_NOTIFICATION_DELIVERED_EVENT } from "@cosmicdrift/kumiko-types/in-app-notification-types";
 import type { DeliveryChannel } from "../delivery/index.ts";
+import { targetOfNotificationData } from "./in-app-target.ts";
 import { inAppMessagesTable } from "./tables.ts";
 
+const log = createFallbackLogger("channel-in-app");
+
 export const inAppChannel: DeliveryChannel = {
   name: "inApp",
   mode: "inline",
@@ -15,25 +20,34 @@ export const inAppChannel: DeliveryChannel = {
     // address is the user-id string after the ES migration — keep it as-is.
     const userId = address;
 
+    // A malformed target drops only the link, never the notification.
+    const target = targetOfNotificationData(message.data);
+    const storedData =
+      message.data === undefined
+        ? null
+        : JSON.stringify({ ...message.data, target: target ?? undefined });
+
     const row = await ctx.db.insertOne<{ id: string }>(inAppMessagesTable, {
       userId,
       notificationType: message.notificationType,
       title: message.title,
       body: message.body ?? null,
-      data: message.data ? JSON.stringify(message.data) : null,
+      data: storedData,
     });
 
     if (ctx.sseBroker) {
-      await ctx.sseBroker.pushToChannel(tenantChannel(ctx.tenantId), {
-        type: "channel-in-app:event:delivered",
-        data: {
-          id: row?.id,
-          userId,
-          notificationType: message.notificationType,
-          title: message.title,
-          body: message.body,
-        },
-      });
+      // The row is stored, so a failing push (e.g. Redis down) must not turn the delivery into
+      // a failure that gets retried and stored twice. Clients fetch the inbox on reconnect.
+      try {
+        await ctx.sseBroker.pushToChannel(tenantChannel(ctx.tenantId), {
+          type: IN_APP_NOTIFICATION_DELIVERED_EVENT,
+          data: { id: row?.id, userId, notificationType: message.notificationType },
+        });
+      } catch (error) {
+        log.warn("in-app SSE push failed; the notification is stored", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
     }
 
     return { status: "sent", address };

package/packages/bundled-features/src/channel-in-app/in-app-target.ts

@@ -0,0 +1,37 @@
+import type { InAppNotificationTarget } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+import * as z from "zod";
+
+const SCREEN_ID_PATTERN = /^[^\s:]+:screen:[^\s:]+$/;
+
+const targetSchema = z.object({
+  screenId: z.string().regex(SCREEN_ID_PATTERN),
+  entityId: z.string().min(1).optional(),
+});
+
+export function inAppTarget(screenId: string, entityId?: string): InAppNotificationTarget {
+  return entityId === undefined ? { screenId } : { screenId, entityId };
+}
+
+// Returns null for anything that is not a well-formed target, so a malformed `data.target`
+// drops only the link and never the notification.
+export function parseInAppTarget(value: unknown): InAppNotificationTarget | null {
+  const parsed = targetSchema.safeParse(value);
+  if (!parsed.success) return null;
+  const { screenId, entityId } = parsed.data;
+  return inAppTarget(screenId, entityId);
+}
+
+// Reads `target` out of the stored notification data (a JSON string) or out of a raw data object.
+export function targetOfNotificationData(data: unknown): InAppNotificationTarget | null {
+  if (typeof data !== "object" || data === null || !("target" in data)) return null;
+  return parseInAppTarget(data.target);
+}
+
+export function parseStoredNotificationData(stored: string | null): unknown {
+  if (stored === null) return null;
+  try {
+    return JSON.parse(stored);
+  } catch {
+    return null;
+  }
+}

package/packages/bundled-features/src/channel-in-app/index.ts

@@ -1,4 +1,5 @@
 export { CHANNEL_IN_APP_FEATURE, InAppHandlers, InAppQueries } from "./constants.ts";
 export { createChannelInAppFeature } from "./feature.ts";
 export { inAppChannel } from "./in-app-channel.ts";
+export { inAppTarget } from "./in-app-target.ts";
 export { inAppMessagesTable } from "./tables.ts";

package/packages/bundled-features/src/documents/aggregate-id.ts

@@ -0,0 +1,20 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Frozen: changing a namespace re-keys every derived stream and breaks replay.
+const DOCUMENT_FOR_FILE_NAMESPACE = "6d2f7e41-3c58-4b0a-9e17-5a4c8d1b2f93";
+const DOCUMENT_LINK_NAMESPACE = "b83a1c6e-9f20-4d57-a1e4-7c0d52f68b19";
+
+// @wrapper-known uuid-domain
+export function documentIdForFile(tenantId: string, fileRefId: string): string {
+  return uuidv5(`${tenantId}|${fileRefId}`, DOCUMENT_FOR_FILE_NAMESPACE);
+}
+
+// @wrapper-known uuid-domain
+export function documentLinkAggregateId(
+  tenantId: string,
+  documentId: string,
+  entityType: string,
+  entityId: string,
+): string {
+  return uuidv5(`${tenantId}|${documentId}|${entityType}|${entityId}`, DOCUMENT_LINK_NAMESPACE);
+}

package/packages/bundled-features/src/documents/capture.ts

@@ -0,0 +1,125 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type FeatureRegistrar,
+  type SessionUser,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { BootCheckContext } from "@cosmicdrift/kumiko-types/feature";
+import { documentIdForFile } from "./aggregate-id.ts";
+import type { DOCUMENTS_FEATURE_NAME } from "./constants.ts";
+import { ensureDocumentLink, type LinkTarget } from "./ensure-link.ts";
+import type { DocumentExecutors } from "./executor.ts";
+
+// Files saved into `entity.field` become documents of `category`, linked to the saved record
+// itself (when it is a link target) and to `links(row)`.
+// `links()` derives targets from the saved row, whose reference values the save handler has
+// already checked, so its output is trusted app config and needs no write check of its own.
+export type DocumentCaptureRule = {
+  readonly entity: string;
+  readonly field: string;
+  readonly category: string;
+  readonly title?: (row: Readonly<Record<string, unknown>>) => string;
+  readonly links?: (row: Readonly<Record<string, unknown>>) => readonly LinkTarget[];
+};
+
+const MAX_TITLE_LENGTH = 200;
+
+async function captureFile(
+  executors: DocumentExecutors,
+  rule: DocumentCaptureRule,
+  linkTargets: readonly string[],
+  saved: { readonly id: string; readonly data: Readonly<Record<string, unknown>> },
+  fileRefId: string,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<void> {
+  const id = documentIdForFile(user.tenantId, fileRefId);
+  // The title never defaults to the file name, which can carry personal data.
+  const title = (rule.title?.(saved.data) ?? rule.category).slice(0, MAX_TITLE_LENGTH);
+  const created = await executors.document.create(
+    { id, title, category: rule.category, file: fileRefId },
+    user,
+    db,
+  );
+  // version_conflict: the stream exists already, so the file was captured before (and a document
+  // deleted since stays deleted).
+  if (!created.isSuccess && created.error.code !== "version_conflict") {
+    throw new Error(
+      `documents capture failed for ${rule.entity}.${rule.field}: ${created.error.code}`,
+    );
+  }
+  // The gate hides rows from a caller without the registry; existence is the system user's question.
+  const live = await executors.document.detail({ id }, createSystemUser(user.tenantId), db);
+  // skip: the document was deleted after an earlier capture and stays deleted
+  if (live === null) return;
+
+  const targets: LinkTarget[] = [
+    { entityType: rule.entity, entityId: saved.id },
+    // Trusted: derived from the saved row, see DocumentCaptureRule.links.
+    ...(rule.links?.(saved.data) ?? []),
+  ].filter((target) => linkTargets.includes(target.entityType));
+  for (const target of targets) {
+    const linked = await ensureDocumentLink(executors, user, db, id, target);
+    if (!linked.isSuccess) {
+      throw new Error(
+        `documents capture failed to link ${target.entityType}: ${linked.error.code}`,
+      );
+    }
+  }
+}
+
+export function registerCapture(
+  r: FeatureRegistrar<typeof DOCUMENTS_FEATURE_NAME>,
+  executors: DocumentExecutors,
+  rules: readonly DocumentCaptureRule[],
+  linkTargets: readonly string[],
+): void {
+  for (const rule of rules) {
+    r.hook({
+      type: "postSave",
+      target: { allOf: rule.entity },
+      handler: async (result, ctx) => {
+        const value =
+          result.changes[rule.field] ?? (result.isNew ? result.data[rule.field] : undefined);
+        // skip: the file field was not part of this save
+        if (typeof value !== "string") return;
+        await captureFile(
+          executors,
+          rule,
+          linkTargets,
+          { id: String(result.id), data: result.data },
+          value,
+          ctx.user,
+          ctx.db,
+        );
+      },
+    });
+  }
+}
+
+export function validateCaptureRules(
+  { features }: BootCheckContext,
+  rules: readonly DocumentCaptureRule[],
+  categories: readonly string[],
+  linkTargets: readonly string[],
+): void {
+  for (const rule of rules) {
+    const label = `documents capture ${rule.entity}.${rule.field}`;
+    if (!categories.includes(rule.category)) {
+      throw new Error(`${label}: category "${rule.category}" is not in the configured categories.`);
+    }
+    const entity = features.map((f) => f.entities?.[rule.entity]).find((e) => e !== undefined);
+    if (entity === undefined)
+      throw new Error(`${label}: entity "${rule.entity}" is not registered.`);
+    const field = entity.fields[rule.field];
+    if (field?.type !== "file" && field?.type !== "image") {
+      throw new Error(`${label}: the field must be a single file or image field.`);
+    }
+  }
+  const unknownTarget = linkTargets.find(
+    (name) => !features.some((f) => f.entities?.[name] !== undefined),
+  );
+  if (unknownTarget !== undefined) {
+    throw new Error(`documents linkTargets: entity "${unknownTarget}" is not registered.`);
+  }
+}

package/packages/bundled-features/src/documents/constants.ts

@@ -0,0 +1,31 @@
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+export const DOCUMENTS_FEATURE_NAME = "documents";
+
+export const DOCUMENT_ENTITY = "filed-document";
+export const DOCUMENT_LINK_ENTITY = "filed-document-link";
+
+export const DEFAULT_DOCUMENT_ACCESS: AccessRule = { roles: ["TenantAdmin", "TenantMember"] };
+export const DEFAULT_ADMIN_ROLES: readonly string[] = ["TenantAdmin", "SystemAdmin"];
+export const DEFAULT_EXPIRING_WITHIN_DAYS = 30;
+
+export const DOCUMENTS_LIST_SCREEN_ID = "list";
+
+export const DocumentsHandlers = {
+  link: "documents:write:link",
+  unlink: "documents:write:unlink",
+  import: "documents:write:import",
+} as const;
+
+export const DocumentsQueries = {
+  list: "documents:query:filed-document:list",
+  detail: "documents:query:filed-document:detail",
+  forRecord: "documents:query:for-record",
+  expiryOverview: "documents:query:expiry-overview",
+  overview: "documents:query:overview",
+} as const;
+
+export const EXPIRY_STATES = ["expired", "expiring", "valid", "none"] as const;
+export type ExpiryState = (typeof EXPIRY_STATES)[number];
+
+export const EXPIRING_FACET_VALUE = "expiring";

package/packages/bundled-features/src/documents/ensure-link.ts

@@ -0,0 +1,35 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { documentLinkAggregateId } from "./aggregate-id.ts";
+import type { DocumentExecutors } from "./executor.ts";
+
+export type LinkTarget = { readonly entityType: string; readonly entityId: string };
+
+// The link id is deterministic, so a removed link is restored rather than recreated and a
+// concurrent first create converges on the row the winner wrote.
+export async function ensureDocumentLink(
+  executors: DocumentExecutors,
+  user: SessionUser,
+  db: TenantDb,
+  documentId: string,
+  target: LinkTarget,
+) {
+  const id = documentLinkAggregateId(user.tenantId, documentId, target.entityType, target.entityId);
+  const restored = await executors.link.restore({ id }, user, db);
+  if (restored.isSuccess) return restored;
+  const alreadyLive =
+    isPlainObject(restored.error.details) && restored.error.details["reason"] === "not_deleted";
+  if (alreadyLive) return { isSuccess: true as const, data: { id } };
+  if (restored.error.code !== "not_found") return restored;
+
+  const created = await executors.link.create(
+    { id, documentId, entityType: target.entityType, entityId: target.entityId },
+    user,
+    db,
+  );
+  if (created.isSuccess || created.error.code === "version_conflict") {
+    return { isSuccess: true as const, data: { id } };
+  }
+  return created;
+}

package/packages/bundled-features/src/documents/entity.ts

@@ -0,0 +1,103 @@
+import { sql } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createDateField,
+  createEntity,
+  createFileField,
+  createSelectField,
+  createTextField,
+  type EntityDefinition,
+  SYSTEM_ROLE,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DOCUMENT_LINK_ENTITY } from "./constants.ts";
+
+export type DocumentEntityOptions = {
+  readonly categories: readonly [string, ...string[]];
+  readonly adminRoles: readonly string[];
+  readonly readAccess?: NonNullable<EntityDefinition["access"]>["read"];
+  readonly retention?: EntityDefinition["retention"];
+};
+
+// Readable only through a link to a host the viewer can read, and only when the file's owner is
+// readable too (see EntityDefinition.readGate); readAccess narrows further.
+export function createDocumentEntity(options: DocumentEntityOptions) {
+  return createEntity({
+    table: "read_filed_documents",
+    softDelete: true,
+    description:
+      "A filed document: title, category, issue and expiry dates and one file. It is visible only through its links to other records and the owner of its file; the file may stay owned by the record it came from.",
+    // The system user passes the gate; the capture and import checks run as it and would
+    // otherwise miss a document that readAccess hides.
+    ...(options.readAccess !== undefined && {
+      access: { read: { ...options.readAccess, [SYSTEM_ROLE]: "all" } },
+    }),
+    ...(options.retention !== undefined && { retention: options.retention }),
+    readGate: {
+      anyLink: { entity: DOCUMENT_LINK_ENTITY, field: "documentId" },
+      fileOwner: { field: "file" },
+      linkExemptRoles: options.adminRoles,
+    },
+    fields: {
+      title: createTextField({
+        required: true,
+        maxLength: 200,
+        sortable: true,
+        searchable: true,
+        personal: false,
+        reason: "document_title",
+      }),
+      category: createSelectField({
+        options: options.categories,
+        required: true,
+        filterable: true,
+        sortable: true,
+      }),
+      issuedAt: createDateField({ sortable: true }),
+      validUntil: createDateField({ sortable: true, filterable: true }),
+      // Filed business documents belong to the tenant, not to one person.
+      file: createFileField({ required: true, personal: false, reason: "is_business_data" }),
+    },
+    // One live document per file; a deleted one releases the file.
+    indexes: [
+      {
+        columns: ["tenantId", "file"],
+        unique: true,
+        name: "read_filed_documents_file_unique",
+        where: sql`"is_deleted" = false`,
+      },
+    ],
+  });
+}
+
+export function createDocumentLinkEntity(linkTargets: readonly string[]) {
+  return createEntity({
+    table: "read_filed_document_links",
+    softDelete: true,
+    description:
+      "The join row recording that one document belongs to one record, addressed by documentId, entityType and entityId, with exactly one row per triple. A document is visible to whoever can read at least one of its linked records.",
+    parentRef: {
+      entityTypeField: "entityType",
+      entityIdField: "entityId",
+      allowedTypes: linkTargets,
+    },
+    fields: {
+      documentId: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      entityType: createTextField({
+        required: true,
+        maxLength: 64,
+        personal: false,
+        reason: "technical_reference",
+      }),
+      entityId: createTextField({
+        required: true,
+        maxLength: 128,
+        personal: false,
+        reason: "technical_reference",
+      }),
+    },
+  });
+}

package/packages/bundled-features/src/documents/executor.ts

@@ -0,0 +1,13 @@
+import { createEntityExecutor, type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { DOCUMENT_ENTITY, DOCUMENT_LINK_ENTITY } from "./constants.ts";
+
+export function createDocumentExecutors(
+  documentEntity: EntityDefinition,
+  linkEntity: EntityDefinition,
+) {
+  return {
+    document: createEntityExecutor(DOCUMENT_ENTITY, documentEntity).executor,
+    link: createEntityExecutor(DOCUMENT_LINK_ENTITY, linkEntity).executor,
+  };
+}
+export type DocumentExecutors = ReturnType<typeof createDocumentExecutors>;