@cosmicdrift/kumiko-samples 0.399.0 → 0.400.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.399.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.399.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/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>;

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

@@ -0,0 +1,32 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { ExpiryState } from "./constants.ts";
+
+export type ExpiryWindow = {
+  readonly today: string;
+  /** Last day (inclusive) that still counts as "expiring". */
+  readonly horizon: string;
+};
+
+// One definition of the boundaries for the counts and for the per-row state, so the
+// overview column and the expiry-overview buckets cannot drift apart.
+export function expiryWindow(
+  ctx: Pick<HandlerContext, "tz">,
+  expiringWithinDays: number,
+): ExpiryWindow {
+  const today = ctx.tz.today(ctx.tz.tenant);
+  return { today: today.toString(), horizon: today.add({ days: expiringWithinDays }).toString() };
+}
+
+// In-process dispatch hands back the date as a PlainDate, the wire form is an ISO string.
+// ISO dates compare correctly as strings; a missing date is "none", not "valid".
+export function expiryStateOf(validUntil: unknown, window: ExpiryWindow): ExpiryState {
+  const day =
+    validUntil instanceof Temporal.PlainDate
+      ? validUntil.toString()
+      : typeof validUntil === "string"
+        ? validUntil.slice(0, 10)
+        : "";
+  if (day === "") return "none";
+  if (day < window.today) return "expired";
+  return day <= window.horizon ? "expiring" : "valid";
+}

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

@@ -0,0 +1,197 @@
+// documents — filed documents (title, category, validity, one file) that become visible on other
+// records through link rows. A document is readable only through a record the viewer can read,
+// and only while the owner of its file is readable too (EntityDefinition.readGate). Documents
+// come from capture rules (a file saved into a configured field) or from the system-only import.
+
+import {
+  type AccessRule,
+  defineEntityCreateHandler,
+  defineEntityDeleteHandler,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
+  defineFeature,
+  type EntityDefinition,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { type DocumentCaptureRule, registerCapture, validateCaptureRules } from "./capture.ts";
+import {
+  DEFAULT_ADMIN_ROLES,
+  DEFAULT_DOCUMENT_ACCESS,
+  DEFAULT_EXPIRING_WITHIN_DAYS,
+  DOCUMENT_ENTITY,
+  DOCUMENT_LINK_ENTITY,
+  DOCUMENTS_FEATURE_NAME,
+} from "./constants.ts";
+import { createDocumentEntity, createDocumentLinkEntity } from "./entity.ts";
+import { createDocumentExecutors } from "./executor.ts";
+import { createImportDocumentHandler } from "./handlers/import.write.ts";
+import { createLinkDocumentHandler, createUnlinkDocumentHandler } from "./handlers/link.write.ts";
+import { DOCUMENTS_FEATURE_I18N } from "./i18n.ts";
+import { rejectForeignPendingFile } from "./pending-file-guard.ts";
+import { createExpiryOverviewQuery } from "./queries/expiry-overview.query.ts";
+import { createForRecordQuery, createForTypeQuery } from "./queries/for-record.query.ts";
+import { createOverviewQuery } from "./queries/overview.query.ts";
+import { createDocumentListScreen } from "./screens.ts";
+import { createDocumentWriteGuard } from "./write-guard.ts";
+
+export type DocumentsFeatureOptions = {
+  /** Allowed document categories; they become the options of the category field. */
+  readonly categories: readonly [string, ...string[]];
+  /** Entities a document can be linked to. Each needs an update handler, which linking requires. */
+  readonly linkTargets: readonly [string, ...string[]];
+  /** Files saved into these fields become documents automatically. */
+  readonly capture?: readonly DocumentCaptureRule[];
+  /** Retention of the document rows, in the entity's own retention vocabulary. */
+  readonly retention?: EntityDefinition["retention"];
+  /** Row-level read rule on the document, AND-ed with the link and file-owner gate. */
+  readonly readAccess?: NonNullable<EntityDefinition["access"]>["read"];
+  /**
+   * Who may use the document handlers. One rule applies to read, write and delete; the split form
+   * sets them apart. Default TenantAdmin and TenantMember; a missing delete follows write.
+   */
+  readonly access?: AccessRule | DocumentsAccess;
+  /** Roles that see every document of their tenant whose file owner they can read, without a link. */
+  readonly adminRoles?: readonly string[];
+  /** Window of the "expiring" bucket in expiry-overview. Default 30 days. */
+  readonly expiringWithinDays?: number;
+};
+
+export type DocumentsAccess = {
+  /** Lists, detail, for-record, the overviews and the list screen. */
+  readonly read?: AccessRule;
+  /** Create, update, link and unlink. */
+  readonly write?: AccessRule;
+  readonly delete?: AccessRule;
+};
+
+type ResolvedDocumentsAccess = Required<DocumentsAccess>;
+
+function isAccessRule(access: AccessRule | DocumentsAccess): access is AccessRule {
+  return "roles" in access || "openToAll" in access;
+}
+
+function resolveAccess(access: AccessRule | DocumentsAccess | undefined): ResolvedDocumentsAccess {
+  if (access === undefined) {
+    return {
+      read: DEFAULT_DOCUMENT_ACCESS,
+      write: DEFAULT_DOCUMENT_ACCESS,
+      delete: DEFAULT_DOCUMENT_ACCESS,
+    };
+  }
+  if (isAccessRule(access)) return { read: access, write: access, delete: access };
+  const write = access.write ?? DEFAULT_DOCUMENT_ACCESS;
+  return { read: access.read ?? DEFAULT_DOCUMENT_ACCESS, write, delete: access.delete ?? write };
+}
+
+function categoryOptionLabels(categories: readonly string[]) {
+  return Object.fromEntries(
+    categories.map((category) => [
+      `documents:entity:filed-document:field:category:option:${category}`,
+      { en: category, de: category },
+    ]),
+  );
+}
+
+function registerDocuments(
+  r: FeatureRegistrar<typeof DOCUMENTS_FEATURE_NAME>,
+  opts: DocumentsFeatureOptions,
+): void {
+  const access = resolveAccess(opts.access);
+  const linkTargets = opts.linkTargets;
+  const documentEntity = createDocumentEntity({
+    categories: opts.categories,
+    adminRoles: opts.adminRoles ?? DEFAULT_ADMIN_ROLES,
+    ...(opts.readAccess !== undefined && { readAccess: opts.readAccess }),
+    ...(opts.retention !== undefined && { retention: opts.retention }),
+  });
+  const linkEntity = createDocumentLinkEntity(linkTargets);
+  const executors = createDocumentExecutors(documentEntity, linkEntity);
+
+  r.requires({ features: ["files"] });
+  r.adoptsBundledLists();
+  r.describe(
+    "Filed documents with title, category, issue and expiry date and one file, shown on the records they are linked to. A document is visible only through a linked record the viewer can read, and only while the record that owns its file is readable too, so linking never widens access to the file. Documents arrive through capture rules (a file saved into a configured field) or through the system-only import for migrations, which keeps the caller's id, refuses an id another record already uses, and stamps createdAt with the import time (issuedAt carries the business date; the event store does not backdate); users link, unlink, edit and delete them. Read a record's documents with for-record, count expired and expiring ones with expiry-overview, list them with an expiry state and an expiring filter with overview (the documents list screen), and add the documents tab to a record screen with documentsTab().",
+  );
+  r.uiHints({ displayLabel: "Documents", category: "data", recommended: false });
+
+  r.entity({ name: DOCUMENT_ENTITY, ...documentEntity });
+  r.entity({ name: DOCUMENT_LINK_ENTITY, ...linkEntity });
+
+  r.writeHandler(
+    defineEntityCreateHandler(DOCUMENT_ENTITY, documentEntity, {
+      access: access.write,
+      description:
+        "Files a new document from an uploaded file; it stays invisible to everyone but the admin roles until it is linked to a record.",
+    }),
+  );
+  const writeGuard = createDocumentWriteGuard(executors, opts.adminRoles ?? DEFAULT_ADMIN_ROLES);
+  r.writeHandler(
+    defineEntityUpdateHandler(DOCUMENT_ENTITY, documentEntity, {
+      access: access.write,
+      description:
+        "Edits a document's title, category and dates from the entity-edit envelope; it does not change what the document is linked to.",
+    }),
+  );
+  r.writeHandler(
+    defineEntityDeleteHandler(DOCUMENT_ENTITY, documentEntity, {
+      access: access.delete,
+      description:
+        "Deletes a document so it disappears from every record it was linked to; the file itself stays with its owner.",
+      agent: { risk: "high" },
+    }),
+  );
+  r.hook({ type: "preSave", target: "filed-document:create", handler: rejectForeignPendingFile });
+  r.hook({ type: "preSave", target: "filed-document:update", handler: rejectForeignPendingFile });
+  r.hook({ type: "preSave", target: "filed-document:update", handler: writeGuard.beforeUpdate });
+  r.hook({ type: "preDelete", target: "filed-document:delete", handler: writeGuard.beforeDelete });
+  r.writeHandler(createLinkDocumentHandler({ access: access.write, executors, linkTargets }));
+  r.writeHandler(createUnlinkDocumentHandler({ access: access.write, executors, linkTargets }));
+  r.writeHandler(
+    createImportDocumentHandler({ executors, categories: opts.categories, linkTargets }),
+  );
+
+  r.queryHandler(
+    defineEntityListHandler(DOCUMENT_ENTITY, documentEntity, {
+      access: access.read,
+      description:
+        "Lists the documents the caller can read, filterable by category and validity date; use for-record to list one record's documents.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityDetailHandler(DOCUMENT_ENTITY, documentEntity, {
+      access: access.read,
+      description: "Reads one document the caller can read, with its file reference and dates.",
+    }),
+  );
+  r.queryHandler(
+    defineEntityListHandler(DOCUMENT_LINK_ENTITY, linkEntity, {
+      access: access.read,
+      description:
+        "Lists the document-to-record link rows whose record the caller can read; filter on entityId for one record's links.",
+    }),
+  );
+  r.queryHandler(createForRecordQuery(access.read, linkTargets));
+  for (const entityType of linkTargets) {
+    r.queryHandler(createForTypeQuery(access.read, linkTargets, entityType));
+  }
+  const expiringWithinDays = opts.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
+  r.queryHandler(createExpiryOverviewQuery(access.read, expiringWithinDays));
+  r.queryHandler(createOverviewQuery(access.read, expiringWithinDays));
+
+  const capture = opts.capture ?? [];
+  registerCapture(r, executors, capture, linkTargets);
+  r.bootCheck((ctx) => validateCaptureRules(ctx, capture, opts.categories, linkTargets));
+
+  r.screen(createDocumentListScreen(access.read, opts.categories));
+  r.translations({
+    keys: { ...DOCUMENTS_FEATURE_I18N, ...categoryOptionLabels(opts.categories) },
+  });
+}
+
+export function createDocumentsFeature(opts: DocumentsFeatureOptions) {
+  if (opts.expiringWithinDays !== undefined && opts.expiringWithinDays < 0) {
+    throw new Error("createDocumentsFeature({ expiringWithinDays }) must not be negative.");
+  }
+  return defineFeature(DOCUMENTS_FEATURE_NAME, (r) => registerDocuments(r, opts));
+}