@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/entity-handlers.js

@@ -1,13 +1,16 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { listAggregatePayloadSchema, } from "@cosmicdrift/kumiko-types/list-aggregate-types";
 import * as z from "zod";
 import { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "../db/eagerload.js";
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { answerListAggregate } from "../db/list-aggregate-labels.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { acknowledgeConventionCrossTenant, reportConventionCrossTenantUse, } from "../db/tenant-db.js";
 import { InternalError } from "../errors/index.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
+import { entityListRuntime } from "./entity-list-runtime-options.js";
 import { assertReason } from "./escape-hatch-reason.js";
 import { dropEmptyWriteOnlyValues } from "./field-access.js";
 import { instructionFieldNames } from "./instruction-fields.js";
@@ -90,14 +93,14 @@ export const entityListSchema = z.object({
         .object({
         field: z.string(),
         op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
-        // Value ist `unknown` zur Compile-Zeit; Server-Side prüft beim
-        // Build der WHERE-Clause ob der Type zum Field passt. z.unknown()
-        // lässt alles durch; Type-Check kommt im executor.list.
+        // `unknown` at compile time; the server checks while building the WHERE
+        // clause that the value's type matches the field. z.unknown() accepts
+        // everything, so the type check occurs in executor.list.
         value: z.unknown(),
     })
         .optional(),
-    // User-gewählte Faceted-Filter (dynamisch). Additiv zum statischen
-    // `filter` — executor.list verknüpft alle mit AND.
+    // User-selected faceted filters are dynamic and additive to the static
+    // `filter`; executor.list combines all of them with AND.
     filters: z
         .array(z.object({
         field: z.string(),
@@ -105,6 +108,7 @@ export const entityListSchema = z.object({
         value: z.unknown(),
     }))
         .optional(),
+    aggregate: listAggregatePayloadSchema.optional(),
 });
 function parseHandlerName(name, validVerbs) {
     const colonIdx = name.indexOf(":");
@@ -277,10 +281,10 @@ export function defineEntityWriteHandler(name, entity, options) {
                     changes: dropEmptyWriteOnlyValues(entity, submitted.changes),
                 };
                 const streamTenantId = await foreignRowTenantFor(event.user, payload.id, db, ctx);
-                // skipUnchanged (#464): API-driven updates diff against the stored
+                // skipUnchanged: API-driven updates diff against the stored
                 // row so a resubmitted-but-identical field doesn't force a fresh
                 // pii/encrypted ciphertext. Direct executor.update() callers (e.g.
-                // KEK-rotation, the user-data-rights #494 backfill) don't go through
+                // KEK-rotation, the user-data-rights backfill) don't go through
                 // this handler and keep today's always-re-encrypt behavior, which
                 // they rely on to intentionally force a fresh event/ciphertext.
                 return executor.update(payload, event.user, db, {
@@ -350,7 +354,7 @@ export function defineEntityQueryHandler(name, entity, options) {
     const executor = createEventStoreExecutor(table, entity, { entityName });
     let schema;
     let handler;
-    // Tier 2.7e server-eagerload: when the entity has reference fields, the
+    // Server-side eager loading: when the entity has reference fields, the
     // handler resolves the UUIDs against the referenced entities after the
     // main query. The `_refs` property lands on every row; the renderer-side
     // useReferenceLookup stays as a fallback (for apps that write custom
@@ -384,35 +388,19 @@ export function defineEntityQueryHandler(name, entity, options) {
         case "list":
             schema = entityListSchema;
             handler = async (query, ctx) => {
-                // Tier 2.7e Audit-Fix: SearchAdapter aus ctx durchreichen,
-                // damit payload.search zur Laufzeit gegen Meilisearch/InMem
-                // läuft (Remote-Combobox-Search). Der executor wird beim
-                // Definition-Time gebaut, kennt den Adapter also nicht —
-                // Runtime-Override holt das.
+                // Pass the SearchAdapter from ctx through so payload.search is executed
+                // against Meilisearch/InMem at runtime (remote combobox search). The
+                // executor is built at definition time and cannot know the adapter, so the
+                // runtime override supplies it.
                 const listPayload = query.payload; // @cast-boundary engine-payload
                 const db = dbFor(ctx);
-                const result = await executor.list(listPayload, query.user, db, {
-                    ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
-                    ...(ctx.includeDeleted === true && { includeDeleted: true }),
-                    // fw#2660 — registry access only exists at request time, so the
-                    // searchable-reference cache + entity resolver travel through the
-                    // same runtime-override extension point as searchAdapter above.
-                    referenceSearch: {
-                        fields: ctx.registry.getSearchableReferences(entityName),
-                        resolveEntity: (name) => ctx.registry.getEntity(name),
-                    },
-                    referenceSort: {
-                        fields: ctx.registry.getSortableReferences(entityName),
-                        resolveEntity: (name) => ctx.registry.getEntity(name),
-                    },
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
-                });
-                const eagerLoadViewer = {
-                    user: query.user,
-                    parentVisibility: { entities: ctx.registry.getAllEntities() },
-                };
+                const { runtimeOptions, eagerLoadViewer, resolveEntity } = entityListRuntime(ctx, entityName, query.user);
+                if (listPayload.aggregate !== undefined) {
+                    return answerListAggregate(executor, { ...listPayload, aggregate: listPayload.aggregate }, query.user, db, runtimeOptions, { entity, resolveEntity, viewer: eagerLoadViewer });
+                }
+                const result = await executor.list(listPayload, query.user, db, runtimeOptions);
                 const enrichedRows = hasRefFields
-                    ? await enrichWithReferences(result.rows, entity, (name) => ctx.registry.getEntity(name), db, eagerLoadViewer)
+                    ? await enrichWithReferences(result.rows, entity, resolveEntity, db, eagerLoadViewer)
                     : result.rows;
                 return { ...result, rows: augmentDerivedFields(enrichedRows, entity) };
             };

package/dist/engine/entity-list-runtime-options.d.ts

@@ -0,0 +1,8 @@
+import type { ListRuntimeOptions } from "@cosmicdrift/kumiko-types/event-store-executor-types";
+import type { EagerLoadEntityResolver, EagerLoadViewer } from "../db/eagerload.ts";
+import type { HandlerContext, SessionUser } from "./types/index.ts";
+export declare function entityListRuntime(ctx: HandlerContext, entityName: string, user: SessionUser): {
+    readonly runtimeOptions: ListRuntimeOptions;
+    readonly eagerLoadViewer: EagerLoadViewer;
+    readonly resolveEntity: EagerLoadEntityResolver;
+};

package/dist/engine/entity-list-runtime-options.js

@@ -0,0 +1,18 @@
+// Registry access only exists at request time, so the searchable/sortable-reference
+// caches, the entity resolver and the join-row read gate travel through the
+// runtime-override extension point of the executor verbs.
+export function entityListRuntime(ctx, entityName, user) {
+    const parentVisibility = { entities: ctx.registry.getAllEntities() };
+    const resolveEntity = (name) => ctx.registry.getEntity(name);
+    return {
+        runtimeOptions: {
+            ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+            ...(ctx.includeDeleted === true && { includeDeleted: true }),
+            referenceSearch: { fields: ctx.registry.getSearchableReferences(entityName), resolveEntity },
+            referenceSort: { fields: ctx.registry.getSortableReferences(entityName), resolveEntity },
+            parentVisibility,
+        },
+        eagerLoadViewer: { user, parentVisibility },
+        resolveEntity,
+    };
+}

package/dist/engine/event-def.js

@@ -2,7 +2,7 @@ import { normalizeEventPiiSubject } from "@cosmicdrift/kumiko-types/handlers";
 import { ZodObject } from "zod";
 import { qn, toKebab } from "./qualified-name.js";
 // A payload field that still holds null/undefined after parsing — the case
-// where an event-PII owner field yields no subject at append time (fw#2776).
+// where an event-PII owner field yields no subject at append time.
 // A `.default(...)` accepts undefined but parses to a value, so it is not
 // absentable.
 function isAbsentable(field) {
@@ -90,7 +90,7 @@ function validateEventPiiFields(featureName, eventName, schema, piiFields) {
  */
 export function createEventDef(options) {
     const { feature, name: eventName, schema } = options;
-    // Fail-closed PII stance gate (fw#2558) — runs before anything else so
+    // Fail-closed PII stance gate — runs before anything else so
     // an untyped JS consumer (no compiler to stop it) still can't register
     // an event without declaring whether its payload carries personal data.
     const missingStanceError = () => new Error(`[Feature ${feature}] defineEvent("${eventName}") must declare an explicit PII stance. Pass { piiFields: { <payloadField>: { personal: { of: "<userIdField>" } } } } for payload fields owned by a user (or { personal: "tenant" } / { personal: "self" } for tenant- or record-scoped subjects), or { piiFields: "none" } when the payload holds none.`);

package/dist/engine/extension-names.d.ts

@@ -8,14 +8,14 @@ import type { UserDataExtensionOptions } from "./extensions/user-data.ts";
 import type { AssignableFromRole } from "./role-assignment.ts";
 import { TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin } from "./tier-resolver-extension.ts";
 /**
- * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
+ * `userData` — user-data rights hooks (GDPR Articles 15, 17, and 20).
  *
- * Erwartete Hook-Methoden:
+ * Expected hook methods:
  *   - `export(userId, ctx) => Promise<UserDataExport>`
  *   - `delete(userId, strategy: "delete" | "anonymize", ctx) => Promise<void>`
  *
- * Registriert von: `user-data-rights` (Sprint 2).
- * Genutzt von: jedes Feature mit User-Referenzen (tasks, comments, files, ...).
+ * Registered by: `user-data-rights`.
+ * Used by: every feature with user references (tasks, comments, files, ...).
  */
 export declare const EXT_USER_DATA: "userData";
 export declare const EXT_USER_DATA_ORDER: {
@@ -41,17 +41,16 @@ export declare const EXT_TENANT_DATA: "tenantData";
  */
 export declare const EXT_STORAGE_PROVIDER: "storageProvider";
 /**
- * `fileProvider` — File-Storage-Provider-Plugin-Selection (file-foundation).
+ * `fileProvider` — file-storage provider plugin selection (file-foundation).
  *
- * Provider-Features (file-provider-s3, -inmemory, -s3-env) registrieren eine
- * Implementierung via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
- * der per-Tenant Config-Key `provider` waehlt zur Runtime eine aus. Der
- * Framework-Resolver (`createFileProviderForTenant`) liest das, damit Upload-
- * Routes, `ctx.files` UND die DSGVO-Jobs denselben Store treffen.
+ * Provider features (file-provider-s3, -inmemory, -s3-env) register an
+ * implementation via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
+ * the per-tenant config key `provider` selects one at runtime. The framework
+ * resolver (`createFileProviderForTenant`) reads it so upload routes,
+ * `ctx.files`, and GDPR jobs all use the same store.
  *
- * Framework-seitig besessen, damit kein String-Drift entsteht — file-
- * foundation MUSS Extension-Point + Config-Key unter genau diesen Namen
- * registrieren.
+ * The framework owns this contract to prevent string drift — file-foundation
+ * MUST register the extension point and config key under exactly these names.
  */
 export declare const EXT_FILE_PROVIDER: "fileProvider";
 export declare const FILE_PROVIDER_CONFIG_KEY: "file-foundation:config:provider";
@@ -85,7 +84,7 @@ export declare const EXT_DERIVATIVE_RENDERER: "derivativeRenderer";
  * serves nothing for that entityType, not even a 403 (404, so existence isn't
  * confirmed to an unauthorised caller).
  *
- * Registered/consumed by: `file-derivatives`' public variant route (#1951).
+ * Registered/consumed by: `file-derivatives`' public variant route.
  */
 export declare const EXT_DERIVATIVE_PUBLIC_PREDICATE: "derivativePublicPredicate";
 /**
@@ -150,9 +149,9 @@ export declare const EXT_TENANT_LIFECYCLE_STATUS: "tenantLifecycleStatus";
 export declare const EXT_ASSIGNABLE_ROLE: "assignableRole";
 export declare const TENANT_MEMBERSHIPS_QUERY: "tenant:query:memberships";
 /**
- * Union aller standardisierten Extension-Namen der Datenschutz-Surface.
- * Nicht alle Extensions im System sind in dieser Liste — andere
- * Features koennen weiterhin eigene Extension-Namen registrieren.
+ * Union of standardized extension names for the privacy surface.
+ * Not every extension in the system is included — other features can still
+ * register their own extension names.
  */
 export type KumikoExtensionName = typeof EXT_USER_DATA | typeof EXT_TENANT_DATA | typeof EXT_STORAGE_PROVIDER | typeof EXT_SEARCH_ADAPTER | typeof EXT_EXTERNAL_RESOURCE | typeof EXT_INFRA_RESOURCE | typeof EXT_FILE_PROVIDER | typeof EXT_DERIVATIVE_RENDERER | typeof EXT_DERIVATIVE_PUBLIC_PREDICATE | typeof EXT_DERIVATIVE_OVERLAY_RESOLVER | typeof EXT_PRINCIPAL_STATUS | typeof EXT_TENANT_LIFECYCLE_STATUS | typeof EXT_ASSIGNABLE_ROLE;
 /** The four `destroyTenant(tenantId, ctx)`-only resource-cleanup extension points. */

package/dist/engine/extension-names.js

@@ -1,42 +1,42 @@
 import { TENANT_TIER_RESOLVER_EXT } from "./tier-resolver-extension.js";
-// Standardisierte Extension-Namen fuer Datenschutz-Hook-Achsen.
+// Standardized extension names for privacy-hook axes.
 //
-// Features registrieren Extensions via:
+// Features register extensions via:
 //   r.extendsRegistrar(EXT_USER_DATA, { hooks: { ... } });
 //
-// Andere Features haengen sich ein via:
+// Other features attach to them via:
 //   r.useExtension(EXT_USER_DATA, "myEntity", { ...hookImpls });
 //
-// Hintergrund: Magic-Strings driften zwischen Bundled-Features (Beispiel:
-// text-content nutzt "Admin" als Rolle, tenant-handler nutzt "TenantAdmin").
-// Constants sind die einzige Quelle der Wahrheit; String-Literale werden
-// in den Sprint-Touchpoints schrittweise ersetzt. Boot-Validator
-// (validateExtensionUsages) checkt dass jedes useExtension einen
-// passenden extendsRegistrar findet — Tippfehler in Constants →
-// Compile-Time-Fail.
+// Background: magic strings drift between bundled features (for example,
+// text-content uses "Admin" as a role, while tenant-handler uses
+// "TenantAdmin"). Constants are the single source of truth; string literals
+// are gradually replaced at the relevant integration points. The boot
+// validator (validateExtensionUsages) checks that every useExtension has a
+// matching extendsRegistrar, so typos in constants cause a compile-time
+// failure.
 //
-// Hook-Signaturen + Boot-Validation pro Extension-Achse kommen mit dem
-// jeweiligen registrierenden Sprint:
-//   userData / tenantData         → Sprint 2 (user-data-rights, retention)
-//   storageProvider                → Sprint 4 (storage-encryption)
-//   searchAdapter / external /     → Sprint 5 (tenant-lifecycle)
+// Hook signatures and boot validation for each extension axis are added by
+// the feature that registers that axis:
+//   userData / tenantData         → (user-data-rights, retention)
+//   storageProvider                → (storage-encryption)
+//   searchAdapter / external /     → (tenant-lifecycle)
 //   infraResource
 /**
- * `userData` — User-Daten-Rights-Hooks (DSGVO Art. 15 + 17 + 20).
+ * `userData` — user-data rights hooks (GDPR Articles 15, 17, and 20).
  *
- * Erwartete Hook-Methoden:
+ * Expected hook methods:
  *   - `export(userId, ctx) => Promise<UserDataExport>`
  *   - `delete(userId, strategy: "delete" | "anonymize", ctx) => Promise<void>`
  *
- * Registriert von: `user-data-rights` (Sprint 2).
- * Genutzt von: jedes Feature mit User-Referenzen (tasks, comments, files, ...).
+ * Registered by: `user-data-rights`.
+ * Used by: every feature with user references (tasks, comments, files, ...).
  */
 export const EXT_USER_DATA = "userData";
-// Order-Bänder für EXT_USER_DATA-Hooks (forget-Pipeline). Der Kontrakt war
-// implizit über zwei Packages verteilt (-100 in custom-fields, 0 in
-// user-data-rights) — ein Host-Hook mit order < REDACT_BEFORE_OWNER liefe
-// VOR den Redaktoren und brächte den Strip-nach-owner-null-Bug zurück
-// (DSGVO-Art.-17-Regression). Regel: Redaktoren < 0 <= owner-mutierende Hooks.
+// Ordering bands for EXT_USER_DATA hooks (forget pipeline). The contract was
+// implicit across two packages (-100 in custom-fields, 0 in
+// user-data-rights), so a host hook with order < REDACT_BEFORE_OWNER would run
+// BEFORE the redactors and reintroduce the strip-after-owner-null bug
+// (GDPR Article 17 regression). Rule: redactors < 0 <= owner-mutating hooks.
 export const EXT_USER_DATA_ORDER = {
     REDACT_BEFORE_OWNER: -100,
     DEFAULT: 0,
@@ -60,23 +60,22 @@ export const EXT_TENANT_DATA = "tenantData";
  */
 export const EXT_STORAGE_PROVIDER = "storageProvider";
 /**
- * `fileProvider` — File-Storage-Provider-Plugin-Selection (file-foundation).
+ * `fileProvider` — file-storage provider plugin selection (file-foundation).
  *
- * Provider-Features (file-provider-s3, -inmemory, -s3-env) registrieren eine
- * Implementierung via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
- * der per-Tenant Config-Key `provider` waehlt zur Runtime eine aus. Der
- * Framework-Resolver (`createFileProviderForTenant`) liest das, damit Upload-
- * Routes, `ctx.files` UND die DSGVO-Jobs denselben Store treffen.
+ * Provider features (file-provider-s3, -inmemory, -s3-env) register an
+ * implementation via `r.useExtension(EXT_FILE_PROVIDER, "<name>", { build })`;
+ * the per-tenant config key `provider` selects one at runtime. The framework
+ * resolver (`createFileProviderForTenant`) reads it so upload routes,
+ * `ctx.files`, and GDPR jobs all use the same store.
  *
- * Framework-seitig besessen, damit kein String-Drift entsteht — file-
- * foundation MUSS Extension-Point + Config-Key unter genau diesen Namen
- * registrieren.
+ * The framework owns this contract to prevent string drift — file-foundation
+ * MUST register the extension point and config key under exactly these names.
  */
 export const EXT_FILE_PROVIDER = "fileProvider";
-// Qualifizierter Config-Key, den das file-foundation-Feature registriert
-// (Format `<feature>:config:<key>`). Akzeptierte Kopplung: der Framework-
-// Resolver liegt UNTER dem Feature und liest den Key per String. Umbenennen
-// des file-foundation-Features MUSS diese Konstante mitziehen.
+// Qualified config key registered by the file-foundation feature
+// (format `<feature>:config:<key>`). This coupling is intentional: the
+// framework resolver is below the feature and reads the key by string. Renaming
+// the file-foundation feature MUST be accompanied by changing this constant.
 export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider";
 // Two roles: boot gate (validateBoot requires its presence once file/image
 // fields are in use) AND the ENV source of the config key above, bridged via
@@ -114,7 +113,7 @@ export const EXT_DERIVATIVE_RENDERER = "derivativeRenderer";
  * serves nothing for that entityType, not even a 403 (404, so existence isn't
  * confirmed to an unauthorised caller).
  *
- * Registered/consumed by: `file-derivatives`' public variant route (#1951).
+ * Registered/consumed by: `file-derivatives`' public variant route.
  */
 export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate";
 /**

package/dist/engine/extensions/escape-hatch-usage.js

@@ -1,4 +1,4 @@
-// fw#2914 — reads the { escapeHatch: { reason } } convention off a
+// reads the { escapeHatch: { reason } } convention off a
 // `r.useExtension(...)` registration's untyped options bag. Registration-time
 // validation (feature-ui-extensions.ts's useExtension) already rejects an
 // empty reason, but options stays `Record<string, unknown>`, so orchestrators

package/dist/engine/extensions/tenant-data.js

@@ -1,7 +1,7 @@
-// Hook-Signatur-Types für EXT_TENANT_DATA (DSGVO tenant-scoped destroy).
+// Hook signature types for EXT_TENANT_DATA (GDPR tenant-scoped destruction).
 //
 // Mirror of engine/extensions/user-data.ts at tenant granularity.
-// tenant-lifecycle orchestrates destroy via registry.getExtensionUsages(EXT_TENANT_DATA).
+// tenant-lifecycle orchestrates destruction via registry.getExtensionUsages(EXT_TENANT_DATA).
 export function isTenantDataExtensionHooks(o) {
     return typeof o === "object" && o !== null && "destroy" in o && typeof o.destroy === "function";
 }

package/dist/engine/extensions/user-data.d.ts

@@ -2,15 +2,15 @@ import type { TenantDb } from "../../db/tenant-db.ts";
 import type { Registry, TenantId } from "../types/index.ts";
 type UserId = string;
 /**
- * Strategie für den Forget-Pfad pro Entity:
- *   - "delete":    Row physisch entfernen (Profil, Eigene Notizen, Sessions).
- *   - "anonymize": User-Reference auf null + Display-Felder auf
- *                  "[Geloescht]" — typisch für geteilte Daten (Tasks,
- *                  Comments) damit andere User die History nicht verlieren.
+ * Strategy for the forget path per entity:
+ *   - "delete":    Physically remove the row (profile, personal notes, sessions).
+ *   - "anonymize": Set the user reference to null and display fields to
+ *                  "[Geloescht]" — typical for shared data (tasks,
+ *                  comments) so other users do not lose the history.
  *
- * Cleanup-Job (Sprint 2 data-retention) entscheidet pro Entity über
- * Retention-Policy, welche Strategie greift. blockDelete-Entries lösen
- * IMMER `anonymize` aus damit Aufbewahrungs-Pflicht respektiert wird.
+ * The cleanup job applies the retention policy per entity to select the
+ * strategy. blockDelete entries ALWAYS use `anonymize` to respect retention
+ * obligations.
  */
 export type UserDataDeleteStrategy = "delete" | "anonymize";
 /**
@@ -27,7 +27,7 @@ export type UserDataDeleteStrategy = "delete" | "anonymize";
  */
 export type TenantUserModel = "single-user" | "multi-user";
 /**
- * fw#2914 — `db` is a tenant-filtered `TenantDb`, bound to `tenantId`
+ * `db` is a tenant-filtered `TenantDb`, bound to `tenantId`
  * (or the per-user sub-tx in the forget path). Unfiltered access needs
  * `escapeHatch: { reason }` on the `r.useExtension(...)` registration,
  * then `ctx.db.unsafeRaw()`.
@@ -82,15 +82,15 @@ export interface UserDataHookCtx {
     readonly userEmailBeforeDelete?: string | null;
 }
 /**
- * Pro Feature/Entity-Snippet das im Export-Bundle landet. Sprint 2
- * orchestriert die JSON-Serialisierung; Hooks geben Plain-Records.
+ * Feature/entity snippet included in the export bundle. The export job
+ * orchestrates JSON serialization; hooks return plain records.
  */
 export interface UserDataExportSnippet {
     readonly entity: string;
     readonly rows: ReadonlyArray<Record<string, unknown>>;
     /**
-     * Optional: signed-URLs für File-Refs. user-data-rights packt sie
-     * separat ins ZIP unter `files/`. Andere Hooks lassen das leer.
+     * Optional signed URLs for file references. user-data-rights puts them
+     * separately in the ZIP under `files/`. Other hooks leave this empty.
      */
     readonly fileRefs?: ReadonlyArray<{
         readonly fileRefId: string;
@@ -99,22 +99,21 @@ export interface UserDataExportSnippet {
     }>;
 }
 /**
- * Export-Hook: Sammelt alle Daten einer Entity die zu einem User
- * gehören. Wird im Daten-Export-Job pro registrierter Entity einmal
- * aufgerufen. Idempotent — kann mehrfach aufgerufen werden ohne
- * Side-Effects.
+ * Export hook: collects all data belonging to a user for an entity. It is
+ * called once per registered entity by the data export job. Idempotent — it
+ * can be called multiple times without side effects.
  *
- * Sprint 2 user-data-rights ruft das via Iteration über alle
- * `r.useExtension(EXT_USER_DATA, ...)`-Registrierungen.
+ * The data-rights runner invokes this by iterating over all
+ * `r.useExtension(EXT_USER_DATA, ...)` registrations.
  */
 export type UserDataExportHook = (ctx: UserDataHookCtx) => Promise<UserDataExportSnippet | null>;
 /**
- * Forget-Hook: Löscht oder anonymisiert die Entity-Rows die zu einem
- * User gehören. Strategy kommt vom Cleanup-Job (kann per Entity
- * unterschiedlich sein wegen Retention-Policy).
+ * Forget hook: deletes or anonymizes entity rows belonging to a user. The
+ * cleanup job supplies the strategy, which may differ by entity because of
+ * the retention policy.
  *
- * Idempotent — wenn der Job zweimal läuft (Crash-Recovery), darf der
- * Hook nicht crashen.
+ * Idempotent — if the job runs twice during crash recovery, the hook must not
+ * crash.
  *
  * Return additive to `void`: a hook can return `{status:"ok"}` or
  * `{status:"incomplete", reason}` to signal a partial success to the

package/dist/engine/factories.d.ts

@@ -7,13 +7,13 @@ export declare function createTextField<R extends true | false = false>(override
 };
 /**
  * Long-form text field for source-code, markdown, blog-posts, email-
- * templates — anything that can be megabytes large. Type-level differs
- * from `text`: keine sortable/searchable/filterable/format options.
- * DB-mapping ist identisch zu text (PG text ist unbounded).
+ * templates — anything that can be megabytes large. Its type-level API
+ * differs from `text`: it has no sortable/searchable/filterable/format options.
+ * The DB mapping is identical to text (`PG text` is unbounded).
  *
- * Soft-cap default: kein maxLength (PG text ist 1 GB hart begrenzt).
- * Setze einen explicit `maxLength` wenn du ein verirrtes Browser-Paste
- * früh ablehnen willst (z.B. 1_000_000 = 1 MB).
+ * Soft-cap default: no maxLength (`PG text` has a 1 GB hard limit).
+ * Set an explicit `maxLength` to reject an accidental browser paste early
+ * (for example, `1_000_000 = 1 MB`).
  */
 /**
  * Read-time computed field for `EntityDefinition.derivedFields` (NOT `fields`).
@@ -112,12 +112,12 @@ export declare function createDateField<R extends true | false = false>(override
     required: R;
 };
 /**
- * UTC-Instant — für Ereignisse die zu einem bestimmten Zeitpunkt passieren
- * (createdAt, loginAt, actualPickupAt). Temporal.Instant intern.
+ * UTC instant for events occurring at a specific point in time
+ * (createdAt, loginAt, actualPickupAt). Uses Temporal.Instant internally.
  *
- * Mit `locatedBy: "<name>Tz"` wird das Feld zum Wall-Clock-Pair eines
- * Termins an einem Ort — bevorzuge dafür `createLocatedTimestampField()`,
- * das EIN atomares Feld statt eines lose verdrahteten Pairs erzeugt.
+ * With `locatedBy: "<name>Tz"`, the field becomes a wall-clock pair for an
+ * appointment at a location — prefer `createLocatedTimestampField()` instead,
+ * which creates one atomic field rather than a loosely connected pair.
  */
 export declare function createTimestampField<R extends true | false = false>(overrides?: Partial<Omit<TimestampFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
     required?: R;
@@ -125,8 +125,9 @@ export declare function createTimestampField<R extends true | false = false>(ove
     required: R;
 };
 /**
- * IANA-Zonenname (z.B. "Europe/Berlin"). Wird im Boot/Schema-Validator
- * via `Intl.supportedValuesOf("timeZone")` geprüft (kommt im Zod-Schritt).
+ * IANA time-zone name (for example, "Europe/Berlin"). The boot/schema
+ * validator checks it using `Intl.supportedValuesOf("timeZone")` during the
+ * Zod step.
  */
 export declare function createTzField<R extends true | false = false>(overrides?: Partial<Omit<TzFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> & PersonalAnnotationsNoFind & {
     required?: R;