@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/data-retention/resolver.ts

@@ -1,30 +1,30 @@
-// 3-Schicht-Retention-Resolver.
+// Three-layer retention resolver.
 //
-// Layer 1: Entity-Default       — Feature-Author setzt r.entity({retention})
-// Layer 2: Tenant-Preset        — Tenant-Admin wählt Bundle (RETENTION_PRESETS)
-// Layer 3: Tenant-Override      — per (tenantId, entityName) JSON-Override
+// Layer 1: Entity default       — Feature author sets r.entity({retention})
+// Layer 2: Tenant preset        — Tenant admin selects a bundle (RETENTION_PRESETS)
+// Layer 3: Tenant override      — per (tenantId, entityName) JSON override
 //
-// Resolver-Reihenfolge:
+// Resolution order:
 //   effective = override(tenantId, entityName)
 //             ?? preset[tenant.retentionPreset][entityName]
-//             ?? entity.retention   (Code-Default aus EntityDefinition)
-//             ?? null               (keine Auto-Aktion)
+//             ?? entity.retention   (code default from EntityDefinition)
+//             ?? null               (no automatic action)
 //
-// Cleanup-Job in S2.D2 ruft das pro (tenantId, entityName) und
-// entscheidet was zu tun ist (hardDelete / softDelete / anonymize /
-// blockDelete-mit-Frist-Check).
+// The cleanup job resolves this for each (tenantId, entityName) and
+// decides what to do (hardDelete / softDelete / anonymize /
+// blockDelete with a grace-period check).
 //
-// Cross-Feature-API r.exposesApi("retention.policyFor") (S2.D3)
-// macht das aus user-data-rights heraus konsumierbar — Forget-Flow
-// fragt blockDelete-Felder ab + anonymisiert sie statt zu löschen.
+// The cross-feature API r.exposesApi("retention.policyFor")
+// makes this consumable by user-data-rights — the forget flow
+// queries blockDelete fields and anonymizes them instead of deleting them.
 
 import type { EntityDefinition, RetentionDef } from "@cosmicdrift/kumiko-framework/engine";
 import { RETENTION_PRESETS, type RetentionPresetKey } from "./presets.ts";
 
 /**
- * Roh-Override aus der DB-Tabelle (config-Spalte als JSON-String).
- * Nicht das gleiche wie RetentionDef weil hier alles optional ist —
- * Override darf einzelne Properties überschreiben.
+ * Raw override from the database table (the config column as a JSON string).
+ * Unlike RetentionDef, every property is optional because an override may
+ * replace individual properties.
  */
 export interface RetentionOverride {
   readonly keepFor?: string;
@@ -33,13 +33,13 @@ export interface RetentionOverride {
 }
 
 /**
- * Effektive Policy nach Resolver-Lauf. Source dokumentiert WELCHE
- * Schicht den Wert geliefert hat — Audit-Trail für DPO.
+ * Effective policy after the resolver ran. `source` records WHICH layer
+ * supplied the value, as an audit trail for the DPO.
  *
- * `override-incomplete` bedeutet: Tenant-Override ist gesetzt, aber
- * füllt keepFor weder selbst noch via Preset-/Entity-Fallback.
- * Cleanup-Job logt eine Warning + skippt — anstatt mit Default-"0d"
- * sofort alles zu löschen.
+ * `override-incomplete` means a tenant override is set but fills keepFor
+ * neither itself nor through the preset/entity fallback. The cleanup job
+ * logs a warning and skips instead of deleting everything at once with a
+ * default "0d".
  */
 export interface EffectiveRetentionPolicy {
   readonly entityName: string;
@@ -55,15 +55,15 @@ export interface ResolveRetentionPolicyArgs {
 }
 
 /**
- * Auswertung der drei Schichten. Pure Function — kein DB-Access, alle
- * Inputs werden vom Caller besorgt (Cleanup-Job aggregiert pro Tenant
- * vorher).
+ * Resolves the three layers. This is a pure function with no database
+ * access; the caller supplies all inputs (the cleanup job aggregates them
+ * per tenant beforehand).
  */
 export function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): EffectiveRetentionPolicy {
   const { entityName, entityDef, tenantPreset, tenantOverride } = args;
 
-  // Layer 3: Override wins, aber Override darf Felder weglassen — dann
-  // fallen die einzelnen Properties auf Layer 2/1 zurück.
+  // Layer 3: Override wins, but it may omit fields, which then
+  // fall back to the individual properties from Layer 2 or 1.
   if (tenantOverride !== null) {
     const baseFromPreset =
       tenantPreset !== null ? (RETENTION_PRESETS[tenantPreset]?.[entityName] ?? null) : null;
@@ -73,10 +73,11 @@ export function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): Effect
     const keepFor = tenantOverride.keepFor ?? base?.keepFor;
     const strategy = tenantOverride.strategy ?? base?.strategy;
 
-    // keepFor + strategy sind Pflicht für jede aktive Policy. Wenn
-    // weder Override noch Base sie liefert, ist das Override semantisch
-    // unvollständig — Cleanup-Job soll WARNEN statt mit Default-"0d"
-    // sofort alles löschen. Source-Marker dokumentiert das.
+    // keepFor + strategy are required for every active policy. If
+    // neither the override nor the base supplies them, the override is
+    // semantically incomplete — the cleanup job must warn instead of
+    // immediately deleting everything with the default "0d". The source
+    // marker documents this.
     if (keepFor === undefined || strategy === undefined) {
       return { entityName, policy: null, source: "override-incomplete" };
     }
@@ -102,6 +103,6 @@ export function resolveRetentionPolicy(args: ResolveRetentionPolicyArgs): Effect
     return { entityName, policy: entityDef.retention, source: "entity-default" };
   }
 
-  // Nichts da — Cleanup-Job überspringt diese Entity für diesen Tenant.
+  // No policy is defined, so the cleanup job skips this entity for this tenant.
   return { entityName, policy: null, source: "none" };
 }

package/packages/bundled-features/src/data-retention/run-retention-cleanup.ts

@@ -1,42 +1,41 @@
-// Retention-Cleanup-Runner (S2.D2b) — pure Function, vom retention-cleanup-Cron
-// pro fan-out-Tenant aufgerufen.
+// Retention-Cleanup-Runner — pure function, called by the retention-cleanup cron
+// for each fan-out tenant.
 //
-// Iteriert alle implicit-Entity-Projektionen, loest pro Entity die effektive
-// Retention-Policy (3-Schicht-Resolver, siehe resolver.ts) und wendet die
-// Strategy auf Rows an deren reference-Timestamp aelter als der keepFor-Cutoff
-// ist:
+// Iterates all implicit entity projections, resolves the effective retention
+// policy per entity (3-layer resolver, see resolver.ts), and applies the
+// strategy to rows whose reference timestamp is older than the keepFor cutoff:
 //
-//   - hardDelete  → executor.forget pro Row (Event → rebuild-safe hard purge).
+//   - hardDelete  → executor.forget per row (event → rebuild-safe hard purge).
 //                   Entities with file/image/files/images fields: bytes first
 //                   (incl. derivatives), then the fileRef row(s), then the row;
 //                   shared fileRefs (other owner, other row of the same table)
 //                   stay untouched.
-//   - softDelete  → executor.delete pro Row (Event → rebuild-safe soft-delete),
-//                   nur auf noch-nicht-geloeschte (isDeleted:false-Filter)
-//   - anonymize   → executor.update pro Row mit den Werten der per-Feld
-//                   anonymize-Funktionen; Row bleibt (fields.ts-Contract)
-//   - blockDelete → waehrend keepFor unangetastet (Aufbewahrungs-Pflicht;
-//                   user-forget loest anonymize aus). NACH Ablauf laufen die
-//                   anonymize-Funktionen — Geschaeftsdaten bleiben, Personen-
-//                   Bezug raus (fields.ts:44-47).
+//   - softDelete  → executor.delete per row (event → rebuild-safe soft-delete),
+//                   only on not-yet-deleted rows (isDeleted:false filter)
+//   - anonymize   → executor.update per row with the values of the per-field
+//                   anonymize functions; row remains (fields.ts contract)
+//   - blockDelete → untouched during keepFor (retention requirement;
+//                   user-forget triggers anonymize). AFTER expiration, the
+//                   anonymize functions run — business data remains, the person-
+//                   identifying link is removed (fields.ts:44-47).
 //
-// Über den Executor statt Batch-deleteMany/updateMany: ein eventloser Batch-Write
-// auf die (erased) Projektions-Tabelle wird beim Projection-Rebuild
-// gewischt/resurrektiert — das #648-Loch. Kosten: N Events pro Cleanup statt ein
-// Batch-Statement (per-Row-Ceiling, Batch-Event-Variante als Follow-up).
+// Via the executor instead of batch-deleteMany/updateMany: an eventless batch write
+// to the (erased) projection table is wiped/resurrected during a projection rebuild.
+// Cost: N events per cleanup instead of one batch statement (per-row ceiling, with
+// a batch-event variant later).
 //
-// **Schaerfer als soft-delete-cleanup:** dieser Cron hardDeleted LIVE Rows
-// (keyed auf reference, Default createdAt), nicht bereits-soft-geloeschte.
-// Darum die Spalten-Existenz-Pruefung vor jedem WHERE — eine fehlende/vertippte
-// reference-Spalte wuerde sonst ein malformed/all-matching WHERE ergeben und
-// pauschal loeschen.
+// **Stricter than soft-delete-cleanup:** this cron hard-deletes LIVE rows
+// (keyed on reference, default createdAt), not already-soft-deleted ones.
+// Therefore the column-existence check comes before every WHERE — a missing/mistyped
+// reference column would otherwise produce a malformed/all-matching WHERE and
+// delete everything.
 //
-// **anonymize-Idempotenz ohne Marker-Spalte:** die anonymize-Funktionen sind
-// row-unabhaengig (`() => unknown`) — einmal pro Entity ausgewertet ergeben
-// sie die Ziel-Werte. Eine Row die sie schon traegt wird uebersprungen, der
-// taegliche Re-Lauf appended also null Events. Der WHERE matcht anonymisierte
-// Rows weiter (reference bleibt alt), deshalb id-Cursor-Paging statt einer
-// einzelnen Page — sonst verstopfen erledigte Rows das batchLimit-Fenster.
+// **anonymize idempotence without a marker column:** the anonymize functions are
+// row-independent (`() => unknown`) — evaluated once per entity, they produce
+// the target values. A row that already carries them is skipped, so the
+// daily rerun appends zero events. The WHERE continues to match anonymized
+// rows (reference remains old), hence id-cursor paging instead of a single
+// page — otherwise completed rows clog the batchLimit window.
 
 import {
   collectPiiSubjectFields,
@@ -68,6 +67,7 @@ import {
   type SessionUser,
   type TenantId,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import {
   type FileContext,
   fileRefEntity,
@@ -89,13 +89,13 @@ import { tenantRetentionOverrideTable } from "./schema/tenant-retention-override
 const DEFAULT_BATCH_LIMIT = 1000;
 const DEFAULT_REFERENCE_FIELD = "createdAt";
 
-// Der Boot-Validator (boot-validator/pii-retention.ts FRAMEWORK_TIMESTAMP_FIELDS)
-// erlaubt diese Aliase als retention.reference, auch wenn sie nicht in
-// entity.fields deklariert sind — die physischen Spalten heissen aber anders
-// (table-builder.ts: inserted_at/modified_at). Hier zur Cleanup-Zeit auf das
-// echte Entity-Feld mappen, sonst trifft die Spalten-Existenz-Pruefung unten
-// und der Cron wuerde lautlos nichts tun. deletedAt/lastSeenAt sind echte
-// Felder (softDelete bzw. session) und brauchen keine Uebersetzung.
+// The boot validator (boot-validator/pii-retention.ts FRAMEWORK_TIMESTAMP_FIELDS)
+// permits these aliases as retention.reference even when they are not declared in
+// entity.fields, but the physical columns use different names
+// (table-builder.ts: inserted_at/modified_at). Map them to the actual entity field
+// during cleanup; otherwise the column existence check below would cause the cron
+// to do nothing silently. deletedAt/lastSeenAt are real fields (softDelete and
+// session respectively) and need no translation.
 const FRAMEWORK_REFERENCE_ALIAS: Readonly<Record<string, string>> = {
   createdAt: "insertedAt",
   updatedAt: "modifiedAt",
@@ -108,14 +108,16 @@ export interface RunRetentionCleanupArgs {
   /** Layer-2 preset from resolveTenantRetentionPreset, resolved once per tenant
    *  by the caller rather than per entity here. null = layers 1 and 3 only. */
   readonly preloadedTenantPreset: RetentionPresetKey | null;
-  /** Now-Injection — Tests pinnen den Wert ohne Date-Mock (Pattern keep-for.ts). */
+  /**
+   * Injects the current time so tests can pin it without mocking the date (pattern keep-for.ts).
+   */
   readonly now: Instant;
   readonly batchLimit?: number;
   /** Storage access for hardDelete entities with file/image/files/images fields.
    *  Missing while fileRefs are due → the row stays (skipped "missing_file_storage"),
    *  fail-closed instead of orphaning bytes. */
   readonly files?: FileContext;
-  /** KMS for erasing a hardDeleted row's own subject key (Refs #2057). Defaults
+  /** KMS for erasing a hardDeleted row's own subject key. Defaults
    *  to configuredPiiSubjectKms() (same fallback as run-forget-cleanup.ts);
    *  undefined/no-KMS-configured skips erasure entirely — the row is still
    *  hard-deleted, only crypto-shredding of its DEK is not attempted. */
@@ -137,7 +139,10 @@ export interface RunRetentionCleanupResult {
   readonly softDeleted: number;
   /** Rows deren anonymize-Feld-Funktionen angewendet wurden (anonymize + abgelaufene blockDelete). */
   readonly anonymized: number;
-  /** Anomalien: Policy referenziert eine Spalte die die Tabelle nicht hat, oder anonymize ohne anonymize-Felder. */
+  /**
+   * Anomalies where the policy references a missing table column or anonymize has no anonymize
+   * fields.
+   */
   readonly skipped: readonly RetentionCleanupSkip[];
 }
 
@@ -159,7 +164,7 @@ async function purgeMatchingRows(
   return count;
 }
 
-// --- hardDelete crypto-shredding (Refs #2057) ---
+// --- hardDelete crypto-shredding ---
 //
 // recordOwned/self-pii resolution (subject-resolver.ts) only ever reads
 // `row.id` for these two kinds — resolveRecordSubject uses opts.entityName +
@@ -243,17 +248,14 @@ async function forgetRowAndEraseKeys(args: {
   readonly entityName: string;
   readonly tenantId: TenantId;
   readonly systemUser: SessionUser;
+  readonly rowId: EntityId;
   readonly row: Record<string, unknown>;
   readonly kms: KmsAdapter | undefined;
   readonly registry: Registry;
 }): Promise<{ readonly isSuccess: boolean }> {
   return runInSubTransaction(args.db, async (sp) => {
     const tdb = createTenantDb({ db: sp, tenantId: args.tenantId, mode: "system" });
-    const result = await args.executor.forget(
-      { id: args.row["id"] as EntityId },
-      args.systemUser,
-      tdb,
-    );
+    const result = await args.executor.forget({ id: args.rowId }, args.systemUser, tdb);
     if (!result.isSuccess) return { isSuccess: false };
     await eraseHardDeletedRowKeys({
       kms: args.kms,
@@ -268,7 +270,7 @@ async function forgetRowAndEraseKeys(args: {
   });
 }
 
-// --- hardDelete + file-fields (kumiko-framework#3089) ---
+// --- hardDelete + file-fields ---
 
 // Throws (unsafe key, missing list permission) must fail this row closed,
 // not abort the whole tenant run.
@@ -298,6 +300,7 @@ async function purgeHardDeleteRowWithFiles(args: {
   readonly tenantId: TenantId;
   readonly entityName: string;
   readonly entity: EntityDefinition;
+  readonly rowId: EntityId;
   readonly row: Record<string, unknown>;
   readonly files: FileContext | undefined;
   readonly entityExecutor: ReturnType<typeof createEventStoreExecutor>;
@@ -308,8 +311,7 @@ async function purgeHardDeleteRowWithFiles(args: {
   readonly registry: Registry;
   readonly onSkip: (reason: "missing_file_storage" | "file_delete_failed") => void;
 }): Promise<boolean> {
-  const rowId = String(args.row["id"]);
-  const logContext = `tenant=${args.tenantId} entity=${args.entityName} row=${rowId}`;
+  const logContext = `tenant=${args.tenantId} entity=${args.entityName} row=${String(args.rowId)}`;
   const files = args.files;
   const outcome = await purgeRowFileRefs({
     db: args.db,
@@ -341,6 +343,7 @@ async function purgeHardDeleteRowWithFiles(args: {
       entityName: args.entityName,
       tenantId: args.tenantId,
       systemUser: args.systemUser,
+      rowId: args.rowId,
       row: args.row,
       kms: args.kms,
       registry: args.registry,
@@ -392,7 +395,14 @@ async function purgeHardDeleteRowsWithFiles(args: {
     });
     if (rows.length === 0) break;
     for (const row of rows) {
-      cursor = row["id"] as EntityId; // @cast-boundary db-row
+      const rawId = row["id"];
+      if (typeof rawId !== "string" && typeof rawId !== "number") {
+        throw new InternalError({
+          message: `data-retention: ${args.entityName} row has no usable id (got ${typeof rawId})`,
+        });
+      }
+      const rowId = rawId;
+      cursor = rowId;
       const ok = await purgeHardDeleteRowWithFiles({
         db: args.db,
         table: args.table,
@@ -400,6 +410,7 @@ async function purgeHardDeleteRowsWithFiles(args: {
         tenantId: args.tenantId,
         entityName: args.entityName,
         entity: args.entity,
+        rowId,
         row,
         files: args.files,
         entityExecutor: args.entityExecutor,
@@ -490,9 +501,9 @@ export async function runRetentionCleanup(
 
   // Retention writes go through the executor (events) so a projection rebuild
   // replays the cleanup — a batch deleteMany/updateMany on the (erased)
-  // projection table is eventless and gets wiped/resurrected on rebuild (the
-  // #648 hole this closes). The cron acts as the system actor; the WHERE already
-  // tenant-scopes, so a system-mode TenantDb (no extra filter) is correct.
+  // projection table is eventless and gets wiped/resurrected on rebuild.
+  // The cron acts as the system actor; the WHERE already tenant-scopes, so a
+  // system-mode TenantDb (no extra filter) is correct.
   // ponytail: per-row events, one batchLimit-sized page per entity per run —
   // the daily cron converges (hardDelete removes rows, softDelete's isDeleted
   // filter shrinks the set). A single batched forget/delete event is a follow-up.
@@ -511,8 +522,9 @@ export async function runRetentionCleanup(
   const overrideByEntity = new Map(overrideRows.map((r) => [r.entityName, { config: r.config }]));
 
   for (const proj of registry.getAllProjections().values()) {
-    // Nur implicit-Entity-Projektionen mit Tabelle — wie soft-delete-cleanup.
-    // Custom-Projektionen + unmanaged-Tables (z.B. sessions) sind kein Target.
+    // Only implicit entity projections with a table are targets, as in
+    // soft-delete-cleanup. Custom projections and unmanaged tables (such as
+    // sessions) are excluded.
     if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table) continue;
     const entityName = proj.source;
 
@@ -539,9 +551,9 @@ export async function runRetentionCleanup(
 
     const cutoff = computeCutoff(policy.keepFor, now);
     const where: WhereObject = { [referenceField]: { lt: cutoff } };
-    // Tenant-Scope nur wenn die Tabelle eine tenantId-Spalte hat — identisch zu
-    // soft-delete-cleanup. Ohne diesen Filter wuerde ein Tenant die Rows eines
-    // anderen treffen.
+    // Apply tenant scoping only when the table has a tenantId column, as in
+    // soft-delete-cleanup. Without this filter, one tenant could affect another
+    // tenant's rows.
     if (propertyOf(proj.table, "tenantId") !== undefined) {
       where["tenantId"] = tenantId;
     }
@@ -559,6 +571,7 @@ export async function runRetentionCleanup(
               entityName,
               tenantId,
               systemUser,
+              rowId: id,
               row: { id },
               kms,
               registry,

package/packages/bundled-features/src/data-retention/schema/tenant-retention-override.ts

@@ -5,21 +5,23 @@ import {
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// tenantRetentionOverride — Layer 3 im 3-Schicht-Resolver.
+// tenantRetentionOverride — Layer 3 in the three-layer resolver.
 //
-// Per (tenantId, entityName) eine optionale Override-Config die das
-// Preset (Layer 2) für genau diese eine Entity überschreibt. Use-Cases:
-//   - Anwaltskanzlei in DE: caseFile 6y blockDelete (nicht im Preset)
-//   - Pilot-Tenant der länger speichert für Test
-//   - Branchenspezifische verkürzte Fristen
+// One optional override config per (tenantId, entityName) replaces the
+// preset (Layer 2) for that entity only. Use cases:
+//   - Law firm in DE: caseFile 6y blockDelete (not in the preset)
+//   - Pilot tenant retaining data longer for testing
+//   - Industry-specific shorter retention periods
 //
-// reason ist Pflicht — Audit für DPO + Aufsichtsbehörde nachvollziehbar.
+// reason is required so the decision is auditable by the DPO and supervisory
+// authorities.
 //
-// config ist JSON-String mit `{ keepFor, strategy, reference? }`. Zod-
-// Schema validiert beim set-override-Call (S2.D2 ggf. erweitert).
+// config is a JSON string with `{ keepFor, strategy, reference? }`. The Zod
+// schema validates it when set-override is called.
 //
-// Tenant-1-zu-N: pro Tenant beliebig viele Entity-Overrides. UNIQUE-
-// Index auf (tenantId, entityName) damit pro Entity max ein Override.
+// Tenant one-to-many: each tenant can have any number of entity overrides.
+// A UNIQUE index on (tenantId, entityName) allows at most one override per
+// entity.
 export const tenantRetentionOverrideEntity = createEntity({
   table: "read_tenant_retention_overrides",
   fields: {

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

@@ -46,7 +46,7 @@ import {
 export type DeliveryFeatureOptions = {
   // Access gate for the delivery-log screen and the `log` query it reads —
   // both move together so the nav entry a role sees always matches a
-  // callable handler (#2033). Default access.admin includes TenantAdmin,
+  // callable handler. Default access.admin includes TenantAdmin,
   // who in a line-of-business app is the operator, not the platform — pass
   // access.systemAdmin to keep this platform-only and out of their nav.
   readonly access?: readonly string[];
@@ -99,10 +99,10 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     // boot-validator accepts the projection below because at least one
     // apply-key is a registered domain-event (DELIVERY_ATTEMPT_EVENT).
     // recipientAddress is the real PII (email address); recipientId stays
-    // plaintext — pseudonymous fk, same line as config.userId (#821).
+    // plaintext — pseudonymous fk, same line as config.userId.
     // recipientId is nullable (system-triggered sends to non-users), so the
     // address falls back to the tenant key instead of the plaintext it used
-    // to be — still shreddable, one tenant wide (fw#2776).
+    // to be — still shreddable, one tenant wide.
     r.defineEvent("attempt", deliveryAttemptSchema, {
       piiFields: {
         recipientAddress: { personal: { of: "recipientId", whenAbsent: "tenant" } },

package/packages/bundled-features/src/delivery/handlers/log.query.ts

@@ -208,7 +208,7 @@ export const logQuery = definePagedQueryHandler({
     const nextCursor =
       rows.length === limit && lastRow ? encodeSortCursor(sortColumn, lastRow) : null;
 
-    // recipientAddress is stored encrypted under the recipient's DEK (#799)
+    // recipientAddress is stored encrypted under the recipient's DEK
     // — decrypt for the admin log view; forgotten subjects show [[erased]].
     // The notificationType/recipientAddress → type/recipient rename happens
     // here, not in the client: a projectionList screen has no entity to

package/packages/bundled-features/src/delivery/tables.ts

@@ -53,14 +53,15 @@ export const deliveryAttemptsTable = pgTable(
   (t) => [index(DELIVERY_ATTEMPTS_TENANT_CREATED_INDEX).on(t.tenantId, t.createdAt)],
 );
 
-// **Unmanaged table** — bewusst KEIN createEntity. Begründung:
-//   - id kommt aus dem Aggregate-Stream (kein gen_random_uuid()-DEFAULT)
-//   - kein version/inserted_by/modified_by/modified_at — keine in-place-
-//     Edits, keine Audit-Spalten nötig (idempotent-on-replay via PK-Konflikt)
-//   - created_at statt inserted_at — historischer Naming-Drift, kein Bug
-// App trägt Verantwortung für tenant-scoping in Queries + replay-idempotency.
-// pgTable bleibt source-of-truth für Query-API; Phase 4 leitet das pgTable
-// aus dieser Meta ab.
+// **Unmanaged table** — deliberately has no createEntity because:
+//   - id comes from the aggregate stream (no gen_random_uuid()-DEFAULT)
+//   - no version/inserted_by/modified_by/modified_at: no in-place edits or
+//     audit columns are needed (idempotent-on-replay via PK conflict)
+//   - created_at rather than inserted_at reflects historical naming drift, not
+//     a bug
+// The app is responsible for tenant scoping in queries and replay idempotency.
+// pgTable remains the source of truth for the query API; the pgTable is derived
+// from this metadata.
 export const deliveryAttemptsTableMeta: EntityTableMeta = defineUnmanagedTable({
   tableName: "store_delivery_attempts",
   indexes: [{ name: DELIVERY_ATTEMPTS_TENANT_CREATED_INDEX, columns: ["tenant_id", "created_at"] }],

package/packages/bundled-features/src/delivery/unsubscribe.ts

@@ -31,13 +31,13 @@ const localeClaimSchema = z
   .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{1,8})*$/)
   .optional();
 
-// Shape des verified-JWT-payloads. tenantId kommt als string aus jose und
-// wird NACH erfolgreichem parse() zur Branded TenantId — kein blind-cast.
+// Shape of verified JWT payloads. `tenantId` arrives from jose as a string and
+// becomes a branded `TenantId` only after successful `parse()`—never via a blind cast.
 //
 // `kind` is explicitly typed as "absent or undefined, nothing else" here
 // (not bare `.optional()`, which would also accept any other value on an
-// unrelated key) so an address-token payload — which always carries
-// `kind: "address"` — fails this schema instead of silently parsing with
+// unrelated key) so an address-token payload—which always carries
+// `kind: "address"`—fails this schema instead of silently parsing with
 // `addressHash` mistaken for a userId.
 const unsubscribeJwtPayloadSchema = z.object({
   kind: z.undefined().optional(),

package/packages/bundled-features/src/delivery/upsert-preference.ts

@@ -28,10 +28,9 @@ const executor = createEventStoreExecutor(
   { entityName: "notification-preference" },
 );
 
-// Konkretes Lookup-Result-Shape — nur die Felder die der upsert
-// tatsächlich für den Update-Path braucht. Vermeidet `row["x"] as T` index-
-// access casts; der Generic-Param am fetchOne macht den Cast zentralisiert
-// im Helper (db-row-boundary), nicht 4× pro Callsite.
+// Concrete lookup result shape containing only the fields needed by the upsert update path. Avoids
+// `row["x"] as T` index-access casts; the generic parameter on fetchOne centralizes the cast in the
+// helper (`db-row-boundary`) instead of repeating it at each call site.
 type PreferenceLookupRow = {
   readonly id: string;
   readonly version: number;

package/packages/bundled-features/src/document-ingest-foundation/entity.ts

@@ -6,7 +6,7 @@ import {
   createTextField,
 } from "@cosmicdrift/kumiko-framework/engine";
 
-// Phase-1 (MVP) page shape — LiteParse fills this in (kumiko-enterprise#273).
+// (MVP) page shape — LiteParse fills this in.
 // Kept minimal on purpose: downstream themes (provider, recipe) extend it.
 // Stored as JSON.stringify(IngestPage[]) in the encrypted `pages` column —
 // jsonb has no encryption support in the engine, and this column holds the
@@ -29,7 +29,7 @@ export type DocumentExtractMeta = {
 
 // documentExtract — implicit entity-projection (r.entity, NOT r.projection):
 // an explicit r.projection would make `forget` non-rebuild-safe and require
-// archiveStream instead of the regular forget path (kumiko-framework#1495).
+// archiveStream instead of the regular forget path.
 // fileRefId points at the source file_refs row; storageKey duplicates it for
 // direct provider access without a join.
 export const documentExtractEntity = createEntity({
@@ -42,11 +42,11 @@ export const documentExtractEntity = createEntity({
       reason: "technical_reference",
     }),
     // Holds the full extracted document text (PII). `personal: "tenant"`,
-    // NOT `encrypted: true` (#1621): the master-key path has no erasure subject,
+    // NOT `encrypted: true`: the master-key path has no erasure subject,
     // so nothing here would ever be shreddable. Tenant-subject ciphertext
-    // dies with eraseSubjectKeys on tenant-destroy (#800 pattern). Whose
+    // dies with eraseSubjectKeys on tenant-destroy. Whose
     // subject a third party named inside a document is stays open, same as
-    // inbound-mail-foundation (#957). meta is provider telemetry only and
+    // inbound-mail-foundation. meta is provider telemetry only and
     // stays plaintext jsonb.
     pages: createLongTextField({
       personal: "tenant",

package/packages/bundled-features/src/document-ingest-foundation/events.ts

@@ -4,8 +4,8 @@ import * as z from "zod";
 // stream per fileRef with aggregateId derived from the fileRefId
 // (documentIngestAggregateId), never the fileRefId itself: foreign events on
 // the fileRef stream would break the fileRef's optimistic lock. Not backed by an r.entity;
-// this is a pure saga-anchor event (kumiko-framework#1497) that the Phase-2
-// worker job (kumiko-enterprise LiteParse provider) subscribes to.
+// this is a pure saga-anchor event that the worker job (kumiko-enterprise LiteParse provider)
+// subscribes to.
 export const DOCUMENT_INGEST_AGGREGATE_TYPE = "document-ingest";
 
 // Stream name of stored extract events; differs from the camelCase r.entity name

package/packages/bundled-features/src/document-ingest-foundation/feature.ts

@@ -166,7 +166,7 @@ export function createDocumentIngestFoundationFeature() {
           default: "deu+eng",
           // Tesseract -l argument syntax: one or more 3-letter language codes
           // joined by "+" (e.g. "deu+eng"). Unconstrained free text here would
-          // reach the OCR provider call unvalidated (#1501).
+          // reach the OCR provider call unvalidated.
           pattern: { regex: "^[a-z]{3}(\\+[a-z]{3})*$" },
           write: access.roles("TenantAdmin", "SystemAdmin"),
           read: access.roles("TenantAdmin", "SystemAdmin", "User"),
@@ -178,7 +178,7 @@ export function createDocumentIngestFoundationFeature() {
           default: 50,
           // Without a bound a tenant could set 0 (silently kills ingest) or an
           // unbounded value (OCR worker runs per-file for as long as the PDF
-          // has pages — job-queue starvation) (#1501).
+          // has pages — job-queue starvation).
           bounds: { min: 1, max: 500 },
           write: access.roles("TenantAdmin", "SystemAdmin"),
           read: access.roles("TenantAdmin", "SystemAdmin", "User"),

package/packages/bundled-features/src/document-ingest-foundation/pages.ts

@@ -2,7 +2,7 @@
 // longText (jsonb has no encryption support), so writers must persist
 // JSON.stringify(IngestPage[]) and readers must parse back. Centralising
 // the codec here keeps liteparse + recipe consumers lockstep with the
-// entity shape (kumiko-framework#1549/1).
+// entity shape.
 
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type { IngestPage } from "./entity.ts";

package/packages/bundled-features/src/document-ingest-foundation/tenant-destroy-hook.ts

@@ -1,4 +1,4 @@
-// Tenant-destroy hook for the documentExtract entity-projection (#1621).
+// Tenant-destroy hook for the documentExtract entity-projection.
 //
 // Per-row forget() through the executor, not a bulk deleteMany: documentExtract
 // is an ES-managed implicit projection, so a store-table write here would be
@@ -6,9 +6,9 @@
 // resurrect every row this hook removed. forget() (Art. 17 hard-purge) is
 // replayed by the implicit projection itself, which keeps the erasure
 // rebuild-safe — the same reasoning as tenant-lifecycle's membership stage,
-// and the reason the feature owns an r.entity instead of an r.projection
-// (kumiko-framework#1495). The `pages` ciphertext dies separately when the
-// pipeline's later `subject-keys` stage erases the tenant subject key.
+// and the reason the feature owns an r.entity instead of an r.projection.
+// The `pages` ciphertext dies separately when the pipeline's later
+// `subject-keys` stage erases the tenant subject key.
 
 import { createSystemUser, type TenantDataDestroyHook } from "@cosmicdrift/kumiko-framework/engine";
 import { documentExtractsTable } from "./entity.ts";

package/packages/bundled-features/src/feature-toggles/compose-tier-resolver.ts

@@ -66,7 +66,7 @@ export function composeTierResolverWithGlobalToggles(
       // Non-toggleable (always-on) names must keep reaching `result` through the
       // globalCascade loop below even if this resolver's SYSTEM_TENANT_ID answer
       // satisfies the emptiness guard above without also merging always-on into
-      // every per-tenant tierSet (framework#1528).
+      // every per-tenant tierSet.
       tierManaged = new Set(
         [...managed].filter((name) => {
           const feature = registry.getFeature(name);