@cosmicdrift/kumiko-samples 0.398.0 → 0.400.0

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));
+}

package/packages/bundled-features/src/documents/handlers/import.write.ts

@@ -0,0 +1,157 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntityExecutor,
+  defineWriteHandler,
+  type HandlerEvents,
+  type SessionUser,
+  SYSTEM_ROLE,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  ConflictError,
+  NotFoundError,
+  ValidationError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { FILE_REF_ENTITY_NAME } from "@cosmicdrift/kumiko-framework/files";
+import { DOCUMENT_ENTITY } from "../constants.ts";
+import { ensureDocumentLink } from "../ensure-link.ts";
+import type { DocumentExecutors } from "../executor.ts";
+import { type ImportDocumentPayload, importDocumentPayloadSchema } from "../schemas.ts";
+
+type ImportArgs = {
+  readonly executors: DocumentExecutors;
+  readonly categories: readonly string[];
+  readonly linkTargets: readonly string[];
+};
+
+async function fileRefExists(
+  registry: Parameters<WriteHandlerDef["handler"]>[1]["registry"],
+  fileRefId: string,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<boolean> {
+  const entity = registry.getEntity(FILE_REF_ENTITY_NAME);
+  if (entity === undefined) return false;
+  const row = await createEntityExecutor(FILE_REF_ENTITY_NAME, entity).executor.detail(
+    { id: fileRefId },
+    user,
+    db,
+  );
+  return row !== null;
+}
+
+type StreamLoader = Pick<HandlerEvents, "load">;
+
+// The stream, not the projected row: a row-level readAccess can hide a document from the system
+// user, and a deleted document still has its stream.
+async function streamTypeOf(events: StreamLoader, id: string): Promise<string | undefined> {
+  const [first] = await events.load(id, { atVersion: 1 });
+  return first?.aggregateType;
+}
+
+// undefined: the document exists now, created here or by an earlier run of the same import.
+async function createUnlessImported(
+  executors: DocumentExecutors,
+  events: StreamLoader,
+  payload: ImportDocumentPayload,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<WriteFailure | undefined> {
+  const existingType = await streamTypeOf(events, payload.id);
+  if (existingType === undefined) {
+    const created = await executors.document.create(
+      {
+        id: payload.id,
+        title: payload.title,
+        category: payload.category,
+        file: payload.fileRefId,
+        ...(payload.issuedAt !== undefined && { issuedAt: payload.issuedAt }),
+        ...(payload.validUntil !== undefined && { validUntil: payload.validUntil }),
+      },
+      user,
+      db,
+    );
+    if (created.isSuccess) return undefined;
+    if (created.error.code !== "version_conflict") return created;
+  }
+  // Stream ids are unique per tenant across aggregate types: an existing stream is the retry of
+  // this import only when it is a document, otherwise linking would point at nothing.
+  const streamType = existingType ?? (await streamTypeOf(events, payload.id));
+  if (streamType === DOCUMENT_ENTITY) return undefined;
+  return writeFailure(
+    new ConflictError({
+      message: `documents import: id ${payload.id} belongs to another record`,
+      i18nKey: "documents.errors.import-id-taken",
+      details: { id: payload.id },
+    }),
+  );
+}
+
+// For one-off migrations run as a job: the caller picks the document id, so a re-run converges
+// on the same document instead of duplicating it. Never callable by a user.
+export function createImportDocumentHandler(args: ImportArgs) {
+  const { executors, categories, linkTargets } = args;
+  return defineWriteHandler({
+    name: "import",
+    schema: importDocumentPayloadSchema,
+    access: { roles: [SYSTEM_ROLE] },
+    agent: { expose: false },
+    description:
+      "Creates a document with a caller-chosen id from an existing file, links it to the given records and optionally leaves it deleted; a repeat call with the same id changes nothing, and an id already used by another record fails. The document's createdAt is the time of the import; issuedAt carries the business date. Reserved for the system user, meant for data migrations.",
+    handler: async (event, ctx) => {
+      const payload = event.payload;
+      if (!categories.includes(payload.category)) {
+        return writeFailure(
+          new ValidationError({
+            fields: [
+              {
+                path: "category",
+                code: "unknown_category",
+                i18nKey: "documents.errors.unknown-category",
+                params: { category: payload.category },
+              },
+            ],
+          }),
+        );
+      }
+      const badTarget = payload.links.find((link) => !linkTargets.includes(link.entityType));
+      if (badTarget !== undefined) {
+        return writeFailure(
+          new ValidationError({
+            fields: [
+              {
+                path: "links",
+                code: "unknown_link_target",
+                i18nKey: "documents.errors.unknown-link-target",
+                params: { entityType: badTarget.entityType },
+              },
+            ],
+          }),
+        );
+      }
+      if (!(await fileRefExists(ctx.registry, payload.fileRefId, event.user, ctx.db))) {
+        return writeFailure(new NotFoundError(FILE_REF_ENTITY_NAME, payload.fileRefId));
+      }
+
+      const notImported = await createUnlessImported(
+        executors,
+        ctx.events,
+        payload,
+        event.user,
+        ctx.db,
+      );
+      if (notImported !== undefined) return notImported;
+      for (const link of payload.links) {
+        const linked = await ensureDocumentLink(executors, event.user, ctx.db, payload.id, link);
+        if (!linked.isSuccess) return linked;
+      }
+      if (payload.deleted === true) {
+        const removed = await executors.document.delete({ id: payload.id }, event.user, ctx.db);
+        if (!removed.isSuccess && removed.error.code !== "not_found") return removed;
+      }
+      return { isSuccess: true as const, data: { id: payload.id, entity: DOCUMENT_ENTITY } };
+    },
+  });
+}

package/packages/bundled-features/src/documents/handlers/link.write.ts

@@ -0,0 +1,103 @@
+import {
+  type AccessRule,
+  defineWriteHandler,
+  parentVisibilityFor,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { documentLinkAggregateId } from "../aggregate-id.ts";
+import { DOCUMENT_ENTITY } from "../constants.ts";
+import { ensureDocumentLink } from "../ensure-link.ts";
+import type { DocumentExecutors } from "../executor.ts";
+import { documentLinkPayloadSchema } from "../schemas.ts";
+import { canWriteLinkTarget } from "../target-write-check.ts";
+
+type LinkHandlerArgs = {
+  readonly access: AccessRule;
+  readonly executors: DocumentExecutors;
+  readonly linkTargets: readonly string[];
+};
+
+// Unreadable document, foreign target type and unwritable target answer alike (not found), so
+// the call is no probe for what exists.
+export function createLinkDocumentHandler(args: LinkHandlerArgs) {
+  const { access, executors, linkTargets } = args;
+  return defineWriteHandler({
+    name: "link",
+    schema: documentLinkPayloadSchema,
+    access,
+    description:
+      "Makes a document visible on another record by linking it to that record; the caller must be able to read the document and edit the record.",
+    handler: async (event, ctx): Promise<WriteResult<unknown>> => {
+      const payload = event.payload;
+      const notFound = () => writeFailure(new NotFoundError(DOCUMENT_ENTITY, payload.documentId));
+      if (!linkTargets.includes(payload.entityType)) return notFound();
+      const document = await executors.document.detail(
+        { id: payload.documentId },
+        event.user,
+        ctx.db,
+        {
+          parentVisibility: parentVisibilityFor(ctx, event.user),
+        },
+      );
+      if (document === null) return notFound();
+      if (
+        !(await canWriteLinkTarget(
+          ctx.registry,
+          payload.entityType,
+          payload.entityId,
+          event.user,
+          ctx.db,
+        ))
+      ) {
+        return notFound();
+      }
+      return ensureDocumentLink(executors, event.user, ctx.db, payload.documentId, payload);
+    },
+  });
+}
+
+export function createUnlinkDocumentHandler(args: LinkHandlerArgs) {
+  const { access, executors, linkTargets } = args;
+  return defineWriteHandler({
+    name: "unlink",
+    schema: documentLinkPayloadSchema,
+    access,
+    description:
+      "Removes a document from a record it was linked to, reporting success when no link existed; the document and its file stay.",
+    handler: async (event, ctx): Promise<WriteResult<unknown>> => {
+      const payload = event.payload;
+      const notFound = () => writeFailure(new NotFoundError(DOCUMENT_ENTITY, payload.documentId));
+      if (!linkTargets.includes(payload.entityType)) return notFound();
+      const document = await executors.document.detail(
+        { id: payload.documentId },
+        event.user,
+        ctx.db,
+        {
+          parentVisibility: parentVisibilityFor(ctx, event.user),
+        },
+      );
+      if (document === null) return notFound();
+      if (
+        !(await canWriteLinkTarget(
+          ctx.registry,
+          payload.entityType,
+          payload.entityId,
+          event.user,
+          ctx.db,
+        ))
+      ) {
+        return notFound();
+      }
+      const id = documentLinkAggregateId(
+        event.user.tenantId,
+        payload.documentId,
+        payload.entityType,
+        payload.entityId,
+      );
+      const existing = await executors.link.detail({ id }, event.user, ctx.db);
+      if (existing === null) return { isSuccess: true as const, data: { id } };
+      return executors.link.delete({ id }, event.user, ctx.db);
+    },
+  });
+}

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

@@ -0,0 +1,35 @@
+type LocalizedString = { readonly en: string; readonly de: string };
+
+export const DOCUMENTS_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
+  "documents:feature.label": { en: "Documents", de: "Dokumente" },
+  "screen:list.title": { en: "Documents", de: "Dokumente" },
+  "documents:tab.title": { en: "Documents", de: "Dokumente" },
+  "documents:overview.expired": { en: "Expired documents", de: "Abgelaufene Dokumente" },
+  "documents:overview.expiring": { en: "Documents expiring soon", de: "Bald ablaufende Dokumente" },
+  "documents:entity:filed-document:field:title": { en: "Title", de: "Titel" },
+  "documents:entity:filed-document:field:category": { en: "Category", de: "Kategorie" },
+  "documents:entity:filed-document:field:issuedAt": { en: "Issued", de: "Ausgestellt" },
+  "documents:entity:filed-document:field:validUntil": { en: "Valid until", de: "Gültig bis" },
+  "documents:entity:filed-document:field:file": { en: "File", de: "Datei" },
+  "documents:list.facet.expiry": { en: "Expiry", de: "Ablauf" },
+  "documents:list.facet.expiring": {
+    en: "Expired or expiring soon",
+    de: "Abgelaufen oder bald ablaufend",
+  },
+  "documents:list.expiry.expired": { en: "Expired", de: "Abgelaufen" },
+  "documents:list.expiry.expiring": { en: "Expiring soon", de: "Läuft bald ab" },
+  "documents:list.expiry.valid": { en: "Valid", de: "Gültig" },
+  "documents:list.expiry.none": { en: "No expiry date", de: "Ohne Ablaufdatum" },
+  "documents.errors.unknown-category": {
+    en: "Unknown document category",
+    de: "Unbekannte Dokumentenkategorie",
+  },
+  "documents.errors.unknown-link-target": {
+    en: "This record type takes no documents",
+    de: "Diesem Datensatztyp lassen sich keine Dokumente zuordnen",
+  },
+  "documents.errors.import-id-taken": {
+    en: "This id already belongs to another record",
+    de: "Diese ID gehört bereits zu einem anderen Datensatz",
+  },
+};

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

@@ -0,0 +1,22 @@
+export { documentIdForFile, documentLinkAggregateId } from "./aggregate-id.ts";
+export type { DocumentCaptureRule } from "./capture.ts";
+export {
+  DEFAULT_ADMIN_ROLES,
+  DEFAULT_DOCUMENT_ACCESS,
+  DOCUMENT_ENTITY,
+  DOCUMENT_LINK_ENTITY,
+  DOCUMENTS_FEATURE_NAME,
+  DOCUMENTS_LIST_SCREEN_ID,
+  DocumentsHandlers,
+  DocumentsQueries,
+  EXPIRY_STATES,
+  type ExpiryState,
+} from "./constants.ts";
+export {
+  createDocumentsFeature,
+  type DocumentsAccess,
+  type DocumentsFeatureOptions,
+} from "./feature.ts";
+export { forTypeQueryQn } from "./queries/for-record.query.ts";
+export { DOCUMENT_COLUMNS } from "./screens.ts";
+export { documentExpiryPanels, documentsTab } from "./tab.ts";

package/packages/bundled-features/src/documents/pending-file-guard.ts

@@ -0,0 +1,36 @@
+import {
+  createEntityExecutor,
+  createSystemUser,
+  type PreSaveHookFn,
+  SYSTEM_ROLE,
+  SYSTEM_USER_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import { FILE_REF_ENTITY_NAME, fileRefEntity } from "@cosmicdrift/kumiko-framework/files";
+import { DOCUMENT_ENTITY } from "./constants.ts";
+
+const fileRefs = createEntityExecutor(FILE_REF_ENTITY_NAME, fileRefEntity).executor;
+
+// One live document per file (unique on tenant + file): a member who names a colleague's pending
+// upload would block the colleague's own later save of that file, because capture could no longer
+// create its document. Files a job made (system uploader) and files already bound to a record stay
+// allowed; for the latter the readGate's file-owner check covers it.
+export const rejectForeignPendingFile: PreSaveHookFn = async (changes, ctx) => {
+  const file = changes["file"];
+  if (typeof file !== "string" || file === ctx.previous["file"]) return changes;
+  if (ctx.user.roles.includes(SYSTEM_ROLE)) return changes;
+  const ref = await fileRefs.detail({ id: file }, createSystemUser(ctx.user.tenantId), ctx.db);
+  // skip: a missing file is rejected by the framework's own file-reference check
+  if (ref === null) return changes;
+  const uploader = ref["insertedById"];
+  const unbound = ref["entityId"] === null || ref["entityId"] === undefined;
+  if (
+    unbound &&
+    typeof uploader === "string" &&
+    uploader !== ctx.user.id &&
+    uploader !== SYSTEM_USER_ID
+  ) {
+    throw new NotFoundError(DOCUMENT_ENTITY, file);
+  }
+  return changes;
+};

package/packages/bundled-features/src/documents/queries/expiry-overview.query.ts

@@ -0,0 +1,46 @@
+import { type AccessRule, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { expiryWindow } from "../expiry.ts";
+import { expiryOverviewPayloadSchema } from "../schemas.ts";
+import { linkedDocumentIds, listDocuments } from "./list-page.ts";
+
+type Filter = { readonly field: string; readonly op: string; readonly value: unknown };
+
+// Counts come from the document list itself (totalCount), so they follow the same read gate
+// as the rows a user can open.
+export function createExpiryOverviewQuery(access: AccessRule, expiringWithinDays: number) {
+  return defineQueryHandler({
+    name: "expiry-overview",
+    schema: expiryOverviewPayloadSchema,
+    access,
+    liveEntities: ["filed-document", "filed-document-link"],
+    description:
+      "Counts the documents the caller can read by validity: expired, expiring within the configured window, valid beyond it and without an expiry date; optionally for one record only.",
+    handler: async (query, ctx) => {
+      const payload = query.payload;
+      const { today, horizon } = expiryWindow(ctx, expiringWithinDays);
+      const scope: Filter[] = [];
+      if (payload.entityType !== undefined && payload.entityId !== undefined) {
+        const ids = await linkedDocumentIds(ctx, {
+          entityType: payload.entityType,
+          entityId: payload.entityId,
+        });
+        if (ids.length === 0) return { expired: 0, expiring: 0, valid: 0, none: 0 };
+        scope.push({ field: "id", op: "in", value: ids });
+      }
+      const count = async (extra: Filter[]) =>
+        (await listDocuments(ctx, { limit: 1, totalCount: true, filters: [...scope, ...extra] }))
+          .total ?? 0;
+
+      const [all, expired, expiring, valid] = await Promise.all([
+        count([]),
+        count([{ field: "validUntil", op: "lt", value: today }]),
+        count([
+          { field: "validUntil", op: "gte", value: today },
+          { field: "validUntil", op: "lte", value: horizon },
+        ]),
+        count([{ field: "validUntil", op: "gt", value: horizon }]),
+      ]);
+      return { expired, expiring, valid, none: all - expired - expiring - valid };
+    },
+  });
+}