@cosmicdrift/kumiko-bundled-features 0.400.0 → 0.402.0

package/dist/agent-tools/agent-manifest.js

@@ -3,6 +3,23 @@ import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-type
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { recordManifestDenyQns } from "./manifest-deny-qns.js";
+import { isExplicitlyAgentHidden } from "./tool-catalog.js";
+const FALLBACK_LOCALE = "en";
+/** Requested locale, then English, then the first remaining locale in code-point
+ *  order; `undefined` when the entry has no text at all (the key is then omitted). */
+function pickLabel(labels, locale) {
+    const nonEmpty = (value) => value !== undefined && value !== "" ? value : undefined;
+    const firstLocale = Object.keys(labels)
+        .sort(compareIds)
+        .find((key) => nonEmpty(labels[key]));
+    return (nonEmpty(labels[locale]) ??
+        nonEmpty(labels[FALLBACK_LOCALE]) ??
+        (firstLocale !== undefined ? labels[firstLocale] : undefined));
+}
+function labelProp(labels, locale) {
+    const label = pickLabel(labels, locale);
+    return label === undefined ? {} : { label };
+}
 /** The manifest surfaces one string per locale — a plural entry reads as its
  *  CLDR `other` form since the manifest has no `count` to select a category. */
 function entryAsLabels(entry) {
@@ -73,13 +90,13 @@ function isFilterableField(field) {
 function isPiiField(field) {
     return "pii" in field && field.pii === true;
 }
-function buildField(entityName, fieldName, field, translations, searchableFields) {
+function buildField(entityName, fieldName, field, translations, searchableFields, locale) {
     const options = field.type === "select" || field.type === "multiSelect" ? field.options : undefined;
     const references = field.type === "reference" ? field.entity : undefined;
     return {
         name: fieldName,
         type: field.type,
-        labels: labelsForSuffix(translations, `:entity:${entityName}:field:${fieldName}`),
+        ...labelProp(labelsForSuffix(translations, `:entity:${entityName}:field:${fieldName}`), locale),
         ...(field.description !== undefined && { description: field.description }),
         ...(options !== undefined && { options }),
         ...(references !== undefined && { references }),
@@ -88,29 +105,45 @@ function buildField(entityName, fieldName, field, translations, searchableFields
         ...(isPiiField(field) && { pii: true }),
     };
 }
-/** Entity schemas are emitted unfiltered by design: roles gate handlers, screens,
- *  navs and workspaces, while the handler pipeline gates the values themselves.
- *  The manifest describes shape, never data. */
-function buildEntities(entities, translations, getSearchableFields) {
+/** Shape, never data. Only entities the role reaches are emitted: the manifest is
+ *  prompt payload, so every extra schema costs tokens on each turn. */
+function buildEntities(entities, translations, getSearchableFields, visibleEntityNames, locale) {
     const result = [];
     for (const [entityName, entity] of entities) {
+        if (!visibleEntityNames.has(entityName))
+            continue;
         const searchableFields = new Set(getSearchableFields(entityName));
-        const fields = Object.entries(entity.fields).map(([fieldName, field]) => buildField(entityName, fieldName, field, translations, searchableFields));
+        const fields = Object.entries(entity.fields).map(([fieldName, field]) => buildField(entityName, fieldName, field, translations, searchableFields, locale));
         result.push({
             name: entityName,
-            labels: labelsForSuffix(translations, `:entity:${entityName}`),
+            ...labelProp(labelsForSuffix(translations, `:entity:${entityName}`), locale),
             ...(entity.description !== undefined && { description: entity.description }),
             fields,
         });
     }
     return result;
 }
-function buildFeatures(features) {
+const FEATURE_DESCRIPTION_MAX_CHARS = 300;
+// Only ". " before a capital ends the sentence, so "e.g. the" and "Art. 15" stay whole.
+const SENTENCE_END = /\.\s+(?=\p{Lu})/u;
+/** The manifest is prompt payload; the full text stays in `FeatureDefinition.description`
+ *  for the docs generators. */
+function leadSentence(description) {
+    const text = description.replace(/\s+/g, " ").trim();
+    const end = SENTENCE_END.exec(text);
+    const sentence = end === null ? text : text.slice(0, end.index + 1);
+    return sentence.slice(0, FEATURE_DESCRIPTION_MAX_CHARS);
+}
+function buildFeatures(features, visibleFeatureNames) {
     const result = [];
     for (const [, feature] of features) {
+        if (!visibleFeatureNames.has(feature.name))
+            continue;
         result.push({
             name: feature.name,
-            ...(feature.description !== undefined && { description: feature.description }),
+            ...(feature.description !== undefined && {
+                description: leadSentence(feature.description),
+            }),
             ...(feature.uiHints?.displayLabel !== undefined && {
                 displayLabel: feature.uiHints.displayLabel,
             }),
@@ -152,7 +185,7 @@ function buildHandlerEntry(qn, kind, def, roles, getHandlerEntity, denyQns) {
         return undefined;
     // `agent.expose: true` without a `description` still opts in — the author
     // asked for exposure explicitly, there's just nothing to show as prose.
-    const description = def.description ?? "";
+    const description = def.description !== undefined && def.description !== "" ? def.description : undefined;
     let inputSchema;
     try {
         // A handler whose schema can't be expressed as JSON Schema (transforms,
@@ -168,7 +201,7 @@ function buildHandlerEntry(qn, kind, def, roles, getHandlerEntity, denyQns) {
     return {
         qn,
         kind,
-        description,
+        ...(description !== undefined && { description }),
         risk: exposure.risk,
         inputSchema,
         ...(entity !== undefined && { entity }),
@@ -199,7 +232,7 @@ function assertDenyQnsExist(denyQns, registry) {
         throw new Error(`agent denyQns names handlers that are not registered: ${unknown.join(", ")}`);
     }
 }
-function buildNavs(navs, workspaces, translations, roles, screens) {
+function buildNavs(navs, workspaces, translations, roles, screens, locale) {
     const result = [];
     for (const [, nav] of navs) {
         if (!uiVisible(nav.access, roles))
@@ -215,10 +248,10 @@ function buildNavs(navs, workspaces, translations, roles, screens) {
             continue;
         result.push({
             id: nav.id,
-            labels: entryAsLabels(translations[nav.label] ?? {}),
+            ...labelProp(entryAsLabels(translations[nav.label] ?? {}), locale),
             ...(nav.screen !== undefined && { screen: nav.screen }),
             ...(nav.parent !== undefined && { parent: nav.parent }),
-            workspaces: visibleWorkspaces,
+            ...(visibleWorkspaces.length > 0 && { workspaces: visibleWorkspaces }),
         });
     }
     return withoutOrphanedNavs(result);
@@ -235,6 +268,46 @@ function withoutOrphanedNavs(navs) {
         remaining = reachable;
     }
 }
+// Qualified handler, screen and nav ids all start with the owning feature name.
+function featureNameOf(qualifiedId) {
+    const idx = qualifiedId.indexOf(":");
+    return idx === -1 ? qualifiedId : qualifiedId.slice(0, idx);
+}
+function visibleFeatureNamesOf(handlers, screens, navs) {
+    return new Set([...handlers.map((h) => h.qn), ...screens.map((s) => s.id), ...navs.map((n) => n.id)].map(featureNameOf));
+}
+function entitiesOfQueryToolsFor(registry, roles, denyQns) {
+    const names = [];
+    for (const [qn, def] of registry.getAllQueryHandlers()) {
+        const entityName = registry.getHandlerEntity(qn);
+        if (entityName === undefined || denyQns.has(qn) || isExplicitlyAgentHidden(def))
+            continue;
+        if (hasAccess({ roles }, def.access))
+            names.push(entityName);
+    }
+    return names;
+}
+// A reference target is "entity" or "<feature>:entity"; registry entity keys are the bare name.
+function entityNameOfReference(target) {
+    return target.slice(target.lastIndexOf(":") + 1);
+}
+function referenceTargetsOf(entity) {
+    return Object.values(entity?.fields ?? {}).flatMap((field) => field.type === "reference" ? [entityNameOfReference(field.entity)] : []);
+}
+/** Reachable = tagged on a manifest handler, shown by a manifest screen, or read by a
+ *  registry-derived `get_`/`list_` tool (which takes labels from the manifest entity). */
+function visibleEntityNamesOf(registry, roles, denyQns, handlers, screens) {
+    const reachable = new Set([
+        ...handlers.flatMap((handler) => (handler.entity !== undefined ? [handler.entity] : [])),
+        ...screens.flatMap((screen) => [screen.entity ?? [], screen.detailFor ?? []].flat()),
+        ...entitiesOfQueryToolsFor(registry, roles, denyQns),
+    ]);
+    const entities = registry.getAllEntities();
+    return new Set([
+        ...reachable,
+        ...[...reachable].flatMap((n) => referenceTargetsOf(entities.get(n))),
+    ]);
+}
 function lastSegment(qualifiedId) {
     const idx = qualifiedId.lastIndexOf(":");
     return idx === -1 ? qualifiedId : qualifiedId.slice(idx + 1);
@@ -242,10 +315,31 @@ function lastSegment(qualifiedId) {
 function detailIdParam(screen) {
     return screen.type === "projectionDetail" ? (screen.idParam ?? "id") : "id";
 }
-function screenTitles(translations, screenId, shortId) {
-    return entryAsLabels(translations[`${screenId}.title`] ?? translations[`screen:${shortId}.title`] ?? {});
+function screenTitles(translations, screenId, shortId, locale) {
+    const title = pickLabel(entryAsLabels(translations[`${screenId}.title`] ?? translations[`screen:${shortId}.title`] ?? {}), locale);
+    return title === undefined ? {} : { title };
+}
+function buildScreenEntry(screen, screenWorkspaces, translations, locale) {
+    return {
+        id: screen.id,
+        type: screen.type,
+        ...screenTitles(translations, screen.id, lastSegment(screen.id), locale),
+        // `screen.description` may be a raw i18n key (`registry.getAllTranslations()`
+        // double-prefixes it, see build-app-schema.ts:77-81) — match on suffix like
+        // `labelsForSuffix` does for entity/field labels, else fall back to the
+        // literal string as authored.
+        ...(screen.description !== undefined && {
+            description: pickLabel(labelsForSuffix(translations, screen.description), locale) ?? screen.description,
+        }),
+        ...("entity" in screen && screen.entity !== undefined && { entity: screen.entity }),
+        // A detail screen takes the row id under its idParam; everything else is parameterless.
+        ...(screen.detailFor !== undefined && { params: [detailIdParam(screen)] }),
+        ...(screenWorkspaces.length > 0 && { workspaces: screenWorkspaces }),
+        ...(screen.detailFor !== undefined && { detailFor: screen.detailFor }),
+        ...("handler" in screen && typeof screen.handler === "string" && { handler: screen.handler }),
+    };
 }
-function buildScreens(screens, navs, workspaces, translations, roles, visibleNavIds) {
+function buildScreens(screens, navs, workspaces, translations, roles, visibleNavIds, locale) {
     const allNavs = [...navs.values()];
     const result = [];
     for (const [, screen] of screens) {
@@ -265,37 +359,19 @@ function buildScreens(screens, navs, workspaces, translations, roles, visibleNav
             });
         if (!uiVisible(screen.access, roles) || !reachable)
             continue;
-        const shortId = lastSegment(screen.id);
         const screenWorkspaces = dedupeSorted(accessibleNavs.flatMap((nav) => visibleWorkspaceIds(nav.workspaces, workspaces, roles)));
-        result.push({
-            id: screen.id,
-            type: screen.type,
-            titles: screenTitles(translations, screen.id, shortId),
-            // `screen.description` may be a raw i18n key (`registry.getAllTranslations()`
-            // double-prefixes it, see build-app-schema.ts:77-81) — match on suffix like
-            // `labelsForSuffix` does for entity/field labels, else fall back to the
-            // literal string as authored.
-            ...(screen.description !== undefined && {
-                description: labelsForSuffix(translations, screen.description)["en"] ?? screen.description,
-            }),
-            ...("entity" in screen && screen.entity !== undefined && { entity: screen.entity }),
-            // A detail screen takes the row id under its idParam; everything else is parameterless.
-            params: screen.detailFor !== undefined ? [detailIdParam(screen)] : [],
-            workspaces: screenWorkspaces,
-            ...(screen.detailFor !== undefined && { detailFor: screen.detailFor }),
-            ...("handler" in screen && typeof screen.handler === "string" && { handler: screen.handler }),
-        });
+        result.push(buildScreenEntry(screen, screenWorkspaces, translations, locale));
     }
     return result;
 }
-function buildWorkspaces(workspaces, translations, roles) {
+function buildWorkspaces(workspaces, translations, roles, locale) {
     const result = [];
     for (const [, workspace] of workspaces) {
         if (!uiVisible(workspace.access, roles))
             continue;
         result.push({
             id: workspace.id,
-            labels: entryAsLabels(translations[workspace.label] ?? {}),
+            ...labelProp(entryAsLabels(translations[workspace.label] ?? {}), locale),
             ...(workspace.default === true && { default: true }),
         });
     }
@@ -310,13 +386,14 @@ export function buildAgentManifest(registry, options) {
     const navMap = registry.getAllNavs();
     const { roles } = options;
     assertDenyQnsExist(options.denyQns ?? [], registry);
-    const features = buildFeatures(registry.features);
-    const entities = buildEntities(registry.getAllEntities(), translations, (name) => registry.getSearchableFields(name));
-    const handlers = buildHandlers(registry.getAllQueryHandlers(), registry.getAllWriteHandlers(), roles, (qn) => registry.getHandlerEntity(qn), new Set(options.denyQns ?? []));
+    const denyQns = new Set(options.denyQns ?? []);
+    const handlers = buildHandlers(registry.getAllQueryHandlers(), registry.getAllWriteHandlers(), roles, (qn) => registry.getHandlerEntity(qn), denyQns);
     const screenMap = registry.getAllScreens();
-    const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap);
-    const screens = buildScreens(screenMap, navMap, workspaceMap, translations, roles, new Set(navs.map((nav) => nav.id)));
-    const workspaces = buildWorkspaces(workspaceMap, translations, roles);
+    const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap, options.locale);
+    const screens = buildScreens(screenMap, navMap, workspaceMap, translations, roles, new Set(navs.map((nav) => nav.id)), options.locale);
+    const workspaces = buildWorkspaces(workspaceMap, translations, roles, options.locale);
+    const features = buildFeatures(registry.features, visibleFeatureNamesOf(handlers, screens, navs));
+    const entities = buildEntities(registry.getAllEntities(), translations, (name) => registry.getSearchableFields(name), visibleEntityNamesOf(registry, roles, denyQns, handlers, screens), options.locale);
     const manifest = {
         builtForRoles: [...roles],
         features: sortedByKey(features, (f) => f.name),
@@ -330,6 +407,6 @@ export function buildAgentManifest(registry, options) {
             ...(options.currency && { currency: options.currency }),
         },
     };
-    recordManifestDenyQns(manifest, new Set(options.denyQns ?? []));
+    recordManifestDenyQns(manifest, denyQns);
     return manifest;
 }

package/dist/agent-tools/tool-catalog.d.ts

@@ -1,4 +1,10 @@
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import type { AgentManifest, RegistrySearchView, ToolCatalog, ToolCatalogOptions } from "./types.ts";
+/** The entity CRUD tools are enumerated off the registry, not off the manifest, so
+ *  `resolveAgentExposure` never runs for them. Only an EXPLICIT opt-out may hide one here —
+ *  the resolver's own default is fail-closed on a missing `description`, and CRUD-generated
+ *  handlers never carry one, so reusing it would delete every entity tool in every app. */
+export declare function isExplicitlyAgentHidden(def: QueryHandlerDef): boolean;
 /** Drops the `query`/`write` verb segment from a handler QN, joins the rest with `_`, and
  *  sanitizes to a valid tool-call identifier. Only the FIRST matching segment is dropped —
  *  QNs are `<feature>:query|write:<entity>:<verb>`, so the verb only ever appears once at that

package/dist/agent-tools/tool-catalog.js

@@ -72,7 +72,7 @@ function isDetailHandlerQn(qn, entityName) {
  *  `resolveAgentExposure` never runs for them. Only an EXPLICIT opt-out may hide one here —
  *  the resolver's own default is fail-closed on a missing `description`, and CRUD-generated
  *  handlers never carry one, so reusing it would delete every entity tool in every app. */
-function isExplicitlyAgentHidden(def) {
+export function isExplicitlyAgentHidden(def) {
     return def.agent?.expose === false;
 }
 /** The model's filters feed the WHERE clause, and only the output is field-filtered — a field
@@ -105,10 +105,10 @@ function addToolsForListHandler(registry, qn, entityName, entity, roles, sink) {
         addTool(sink, tool, { kind: "findBy", entityName, fieldName, qn });
     }
 }
-function entityDisplayLabel(entity, entityName, locale) {
+function entityDisplayLabel(entity, entityName) {
     if (entity?.description)
         return entity.description;
-    const label = entity?.labels[locale];
+    const label = entity?.label;
     if (label)
         return label;
     return entityName;
@@ -212,7 +212,7 @@ function stripFieldFromSchema(schema, field) {
     return { ...rest, properties: strippedProperties, required: strippedRequired };
 }
 function handlerDescription(handler) {
-    return handler.description.length > 0 ? handler.description : `Run ${handler.qn}.`;
+    return handler.description ?? `Run ${handler.qn}.`;
 }
 /** Drops the `query`/`write` verb segment from a handler QN, joins the rest with `_`, and
  *  sanitizes to a valid tool-call identifier. Only the FIRST matching segment is dropped —
@@ -373,18 +373,18 @@ function collectEntityHandlerQns(registry, roleFilter, denyQns) {
     }
     return { detailQnByEntity, listQnByEntity, entityListDetailQns };
 }
-function addGetTools(registry, detailQnByEntity, entityByName, locale, sink) {
+function addGetTools(registry, detailQnByEntity, entityByName, sink) {
     const getEntries = [...detailQnByEntity.entries()].sort((a, b) => compareByCodePoint(a[0], b[0]));
     for (const [entityName, qn] of getEntries) {
-        const label = entityDisplayLabel(entityByName.get(entityName), entityName, locale);
+        const label = entityDisplayLabel(entityByName.get(entityName), entityName);
         const { tool, descriptor } = buildGetTool(entityName, qn, label, entityHandlerRisk(registry, qn));
         addTool(sink, tool, descriptor);
     }
 }
-function addListTools(registry, listQnByEntity, entityByName, roles, locale, sink) {
+function addListTools(registry, listQnByEntity, entityByName, roles, sink) {
     const listEntries = [...listQnByEntity.entries()].sort((a, b) => compareByCodePoint(a[0], b[0]));
     for (const [entityName, qn] of listEntries) {
-        const label = entityDisplayLabel(entityByName.get(entityName), entityName, locale);
+        const label = entityDisplayLabel(entityByName.get(entityName), entityName);
         const searchableFields = registry.getSearchableFields(entityName);
         const filterableFields = filterableFieldsOf(entityByName.get(entityName), registry.getEntity(entityName), roles);
         const { tool, descriptor } = buildListTool(entityName, qn, label, searchableFields, filterableFields, entityHandlerRisk(registry, qn));
@@ -472,14 +472,13 @@ function addClientTools(manifest, mode, sink) {
 export function buildToolCatalog(registry, manifest, options) {
     const sink = { tools: [], dispatchTable: new Map(), usedNames: new Set() };
     const roleFilter = { roles: manifest.builtForRoles };
-    const locale = manifest.tenantSettings.locale;
     const entityByName = new Map(manifest.entities.map((entity) => [entity.name, entity]));
     const denyQns = new Set(options.denyQns ?? []);
     assertCatalogMirrorsManifestDenyQns(manifest, denyQns);
     addRegistrySearchTools(registry, roleFilter, denyQns, sink);
     const { detailQnByEntity, listQnByEntity, entityListDetailQns } = collectEntityHandlerQns(registry, roleFilter, denyQns);
-    addGetTools(registry, detailQnByEntity, entityByName, locale, sink);
-    addListTools(registry, listQnByEntity, entityByName, roleFilter.roles, locale, sink);
+    addGetTools(registry, detailQnByEntity, entityByName, sink);
+    addListTools(registry, listQnByEntity, entityByName, roleFilter.roles, sink);
     addQueryHandlerTools(manifest, entityListDetailQns, denyQns, sink);
     if (options.mode !== "read-only") {
         addWriteHandlerTools(manifest, detailQnByEntity, denyQns, sink);

package/dist/agent-tools/types.d.ts

@@ -105,8 +105,8 @@ export type AgentManifestOptions = {
 export type AgentManifestField = {
     readonly name: string;
     readonly type: string;
-    /** Label per app locale, keyed by locale code. */
-    readonly labels: Readonly<Record<string, string>>;
+    /** Label in the requested locale (English, then any other, as fallback); absent when untranslated. */
+    readonly label?: string;
     readonly description?: string;
     readonly options?: readonly string[];
     /** Entity a `reference` field points at. */
@@ -119,14 +119,14 @@ export type AgentManifestField = {
 };
 export type AgentManifestEntity = {
     readonly name: string;
-    readonly labels: Readonly<Record<string, string>>;
+    readonly label?: string;
     readonly description?: string;
     readonly fields: readonly AgentManifestField[];
 };
 export type AgentManifestHandler = {
     readonly qn: string;
     readonly kind: "query" | "write";
-    readonly description: string;
+    readonly description?: string;
     readonly risk: AgentRisk;
     readonly inputSchema: Readonly<Record<string, unknown>>;
     readonly entity?: string;
@@ -136,11 +136,12 @@ export type AgentManifestHandler = {
 export type AgentManifestScreen = {
     readonly id: string;
     readonly type: string;
-    readonly titles: Readonly<Record<string, string>>;
+    readonly title?: string;
     readonly description?: string;
     readonly entity?: string;
-    readonly params: readonly string[];
-    readonly workspaces: readonly string[];
+    /** Only present on detail screens. */
+    readonly params?: readonly string[];
+    readonly workspaces?: readonly string[];
     /** Entity this screen is the detail view for. Distinct from `entity`: a custom
      *  screen can render entity A while being the detail view for B. */
     readonly detailFor?: string;
@@ -149,14 +150,14 @@ export type AgentManifestScreen = {
 };
 export type AgentManifestNav = {
     readonly id: string;
-    readonly labels: Readonly<Record<string, string>>;
+    readonly label?: string;
     readonly screen?: string;
     readonly parent?: string;
-    readonly workspaces: readonly string[];
+    readonly workspaces?: readonly string[];
 };
 export type AgentManifestWorkspace = {
     readonly id: string;
-    readonly labels: Readonly<Record<string, string>>;
+    readonly label?: string;
     readonly default?: true;
 };
 export type AgentManifestFeature = {

package/dist/billing-foundation/consumer-protection/confirmation-mail.js

@@ -1,7 +1,7 @@
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headless";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { Marked } from "marked";
-import { isAllowedDocumentLinkHref, isDocumentPlaceholderHref, } from "../../template-resolver/index.js";
+import { isAllowedDocumentUrlHref, isDocumentPlaceholderHref, } from "../../template-resolver/index.js";
 import { resolveConsentLocale } from "./consent-text.js";
 export const CONFIRMATION_LABELS = {
     de: {
@@ -96,7 +96,7 @@ function formatDate(iso, locale, timeZone) {
 // row as escaped text, so author HTML, images and refused links stay plain text.
 const ROW_END = "\n\n";
 function isMailLinkHref(href) {
-    return isAllowedDocumentLinkHref(href) && !isDocumentPlaceholderHref(href);
+    return isAllowedDocumentUrlHref(href) && !isDocumentPlaceholderHref(href);
 }
 const inlineHtmlMarkdown = new Marked({ gfm: false, breaks: false });
 inlineHtmlMarkdown.use({

package/dist/documents/entity.d.ts

@@ -1,8 +1,10 @@
 import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export type DocumentLinkReadMode = "anyLink" | "allLinks";
 export type DocumentEntityOptions = {
     readonly categories: readonly [string, ...string[]];
     readonly adminRoles: readonly string[];
     readonly readAccess?: NonNullable<EntityDefinition["access"]>["read"];
+    readonly linkReadMode?: DocumentLinkReadMode;
     readonly retention?: EntityDefinition["retention"];
 };
 export declare function createDocumentEntity(options: DocumentEntityOptions): EntityDefinition<{

package/dist/documents/entity.js

@@ -4,6 +4,7 @@ import { DOCUMENT_LINK_ENTITY } from "./constants.js";
 // 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) {
+    const documentLink = { entity: DOCUMENT_LINK_ENTITY, field: "documentId" };
     return createEntity({
         table: "read_filed_documents",
         softDelete: true,
@@ -15,7 +16,9 @@ export function createDocumentEntity(options) {
         }),
         ...(options.retention !== undefined && { retention: options.retention }),
         readGate: {
-            anyLink: { entity: DOCUMENT_LINK_ENTITY, field: "documentId" },
+            ...(options.linkReadMode === "allLinks"
+                ? { allLinks: documentLink }
+                : { anyLink: documentLink }),
             fileOwner: { field: "file" },
             linkExemptRoles: options.adminRoles,
         },

package/dist/documents/feature.d.ts

@@ -1,16 +1,29 @@
 import { type AccessRule, type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import { type DocumentCaptureRule } from "./capture.ts";
+import { type DocumentLinkReadMode } from "./entity.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. */
+    /** Entities a document can be linked to. Linking needs write access to the target: its update handler, or its entity write roles when it has none. */
     readonly linkTargets: readonly [string, ...string[]];
+    /** Display label per category (de, en); a category without one shows its raw value. */
+    readonly categoryLabels?: Readonly<Record<string, {
+        readonly de: string;
+        readonly en: 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"];
+    /**
+     * "anyLink" (default): one readable linked record shows the document. "allLinks": the viewer
+     * must read every record it is linked to, so a link to a shared record (a contact) does not
+     * open a document that also hangs off a record of another team. The file-owner check applies
+     * either way.
+     */
+    readonly linkReadMode?: DocumentLinkReadMode;
     /**
      * 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.

package/dist/documents/feature.js

@@ -5,7 +5,7 @@
 import { defineEntityCreateHandler, defineEntityDeleteHandler, defineEntityDetailHandler, defineEntityListHandler, defineEntityUpdateHandler, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
 import { registerCapture, validateCaptureRules } from "./capture.js";
 import { DEFAULT_ADMIN_ROLES, DEFAULT_DOCUMENT_ACCESS, DEFAULT_EXPIRING_WITHIN_DAYS, DOCUMENT_ENTITY, DOCUMENT_LINK_ENTITY, DOCUMENTS_FEATURE_NAME, } from "./constants.js";
-import { createDocumentEntity, createDocumentLinkEntity } from "./entity.js";
+import { createDocumentEntity, createDocumentLinkEntity, } from "./entity.js";
 import { createDocumentExecutors } from "./executor.js";
 import { createImportDocumentHandler } from "./handlers/import.write.js";
 import { createLinkDocumentHandler, createUnlinkDocumentHandler } from "./handlers/link.write.js";
@@ -32,10 +32,10 @@ function resolveAccess(access) {
     const write = access.write ?? DEFAULT_DOCUMENT_ACCESS;
     return { read: access.read ?? DEFAULT_DOCUMENT_ACCESS, write, delete: access.delete ?? write };
 }
-function categoryOptionLabels(categories) {
+function categoryOptionLabels(categories, labels) {
     return Object.fromEntries(categories.map((category) => [
         `documents:entity:filed-document:field:category:option:${category}`,
-        { en: category, de: category },
+        labels?.[category] ?? { en: category, de: category },
     ]));
 }
 function registerDocuments(r, opts) {
@@ -45,6 +45,7 @@ function registerDocuments(r, opts) {
         categories: opts.categories,
         adminRoles: opts.adminRoles ?? DEFAULT_ADMIN_ROLES,
         ...(opts.readAccess !== undefined && { readAccess: opts.readAccess }),
+        ...(opts.linkReadMode !== undefined && { linkReadMode: opts.linkReadMode }),
         ...(opts.retention !== undefined && { retention: opts.retention }),
     });
     const linkEntity = createDocumentLinkEntity(linkTargets);
@@ -58,11 +59,13 @@ function registerDocuments(r, opts) {
     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.",
+        agent: { risk: "mid" },
     }));
     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.",
+        agent: { risk: "mid" },
     }));
     r.writeHandler(defineEntityDeleteHandler(DOCUMENT_ENTITY, documentEntity, {
         access: access.delete,
@@ -100,12 +103,20 @@ function registerDocuments(r, opts) {
     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) },
+        keys: {
+            ...DOCUMENTS_FEATURE_I18N,
+            ...categoryOptionLabels(opts.categories, opts.categoryLabels),
+        },
     });
 }
 export function createDocumentsFeature(opts) {
     if (opts.expiringWithinDays !== undefined && opts.expiringWithinDays < 0) {
         throw new Error("createDocumentsFeature({ expiringWithinDays }) must not be negative.");
     }
+    for (const category of Object.keys(opts.categoryLabels ?? {})) {
+        if (!opts.categories.includes(category)) {
+            throw new Error(`createDocumentsFeature({ categoryLabels }) names "${category}", which is not in categories.`);
+        }
+    }
     return defineFeature(DOCUMENTS_FEATURE_NAME, (r) => registerDocuments(r, opts));
 }

package/dist/documents/handlers/import.write.js

@@ -53,7 +53,7 @@ export function createImportDocumentHandler(args) {
         name: "import",
         schema: importDocumentPayloadSchema,
         access: { roles: [SYSTEM_ROLE] },
-        agent: { expose: false },
+        agent: { expose: false, risk: "high" },
         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;

package/dist/documents/handlers/link.write.js

@@ -13,6 +13,7 @@ export function createLinkDocumentHandler(args) {
         name: "link",
         schema: documentLinkPayloadSchema,
         access,
+        agent: { risk: "mid" },
         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) => {
             const payload = event.payload;
@@ -37,6 +38,7 @@ export function createUnlinkDocumentHandler(args) {
         name: "unlink",
         schema: documentLinkPayloadSchema,
         access,
+        agent: { risk: "mid" },
         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) => {
             const payload = event.payload;

package/dist/documents/i18n.js

@@ -18,6 +18,20 @@ export const DOCUMENTS_FEATURE_I18N = {
     "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:write:link:title": {
+        en: "Link document to record",
+        de: "Dokument mit Datensatz verknüpfen",
+    },
+    "documents:write:link:field:documentId": { en: "Document", de: "Dokument" },
+    "documents:write:link:field:entityType": { en: "Record type", de: "Datensatztyp" },
+    "documents:write:link:field:entityId": { en: "Record", de: "Datensatz" },
+    "documents:write:unlink:title": {
+        en: "Remove document from record",
+        de: "Dokument von Datensatz lösen",
+    },
+    "documents:write:unlink:field:documentId": { en: "Document", de: "Dokument" },
+    "documents:write:unlink:field:entityType": { en: "Record type", de: "Datensatztyp" },
+    "documents:write:unlink:field:entityId": { en: "Record", de: "Datensatz" },
     "documents.errors.unknown-category": {
         en: "Unknown document category",
         de: "Unbekannte Dokumentenkategorie",

package/dist/documents/index.d.ts

@@ -1,6 +1,7 @@
 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 type { DocumentLinkReadMode } from "./entity.ts";
 export { createDocumentsFeature, type DocumentsAccess, type DocumentsFeatureOptions, } from "./feature.ts";
 export { forTypeQueryQn } from "./queries/for-record.query.ts";
 export { DOCUMENT_COLUMNS } from "./screens.ts";