@cosmicdrift/kumiko-samples 0.386.0 → 0.388.0

package/packages/bundled-features/src/file-derivatives/handlers/public-variant.query.ts

@@ -1,5 +1,5 @@
 // Public-Read of a derived FileRef variant — the anonymous counterpart to
-// GET /files/:id/variant/:name (#1950, auth-gated). Both routes resolve the
+// GET /files/:id/variant/:name (auth-gated). Both routes resolve the
 // same way: the variant spec comes from the FileRef's field declaration
 // (`createImageField({ variants: {...} })`), not a fixed list — an app that
 // declares its own variant name gets it served here too. This route never

package/packages/bundled-features/src/file-derivatives/presets.ts

@@ -3,7 +3,7 @@ import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
 // Ready-made specs to spread into a field's own `variants` declaration
 // (`createImageField({ variants: { thumb, full: { ...full, maxEdge: 4096 } } })`)
 // — not an allow-list. Which names a route serves is decided entirely by
-// what a field declares (#1985), these are just common defaults.
+// what a field declares; these are just common defaults.
 export const thumb = { maxEdge: 160, fit: "cover", format: "webp" } as const satisfies VariantSpec;
 export const card = { maxEdge: 640, fit: "inside", format: "webp" } as const satisfies VariantSpec;
 export const hero = { maxEdge: 1600, fit: "inside", format: "webp" } as const satisfies VariantSpec;

package/packages/bundled-features/src/file-foundation/feature.ts

@@ -8,13 +8,13 @@
 // erasure hit the same store by construction. This feature re-exports the moved
 // symbols unchanged so existing imports keep working.
 //
-// **Pattern-Vorbild:** identisch zu `mail-foundation`. Foundation deklariert
-// extension-point `fileProvider`, Provider-Features (file-provider-s3, -inmemory,
-// -s3-env, später -gcs/-azure-blob) registrieren sich namentlich. Tenant wählt
-// zur Runtime via config-key `provider`.
+// **Pattern reference:** identical to `mail-foundation`. The foundation declares
+// the `fileProvider` extension point; provider features (file-provider-s3,
+// -inmemory, -s3-env, later -gcs/-azure-blob) register themselves by name. The
+// tenant selects one at runtime via the `provider` config key.
 //
-// **Boot-Dependencies:** config (für provider-selector). Kein secrets, weil
-// Foundation selbst keine Secrets hält.
+// **Boot dependencies:** config (for the provider selector). No secrets, because
+// the foundation itself does not hold any secrets.
 
 import {
   access,

package/packages/bundled-features/src/file-foundation/index.ts

@@ -10,6 +10,7 @@ export {
 export {
   type FileRefContent,
   FileRefTooLargeError,
+  FileStorageUnavailableError,
   fileContextForTenant,
   fileContextFromResolver,
   readFileRefContent,

package/packages/bundled-features/src/file-foundation/read-file-ref-content.ts

@@ -53,6 +53,12 @@ export class FileRefTooLargeError extends Error {
   }
 }
 
+export class FileStorageUnavailableError extends Error {
+  constructor() {
+    super("readFileRefContent: no file storage is available for the file's tenant");
+  }
+}
+
 // fileName of the row is never used: it is personal data and may be a PII ciphertext.
 export async function readFileRefContent(args: {
   readonly db: DbRunner | TenantDb;
@@ -82,7 +88,7 @@ export async function readFileRefContent(args: {
   }
   const files = args.filesForTenant(row.tenantId);
   if (files === undefined) {
-    throw new Error("readFileRefContent: no file storage is available for the file's tenant");
+    throw new FileStorageUnavailableError();
   }
   const content = await files.refFromFileRef(row).read();
   return { content, contentType: row.mimeType, tenantId: row.tenantId, size };

package/packages/bundled-features/src/file-provider-inmemory/feature.ts

@@ -1,21 +1,21 @@
 // kumiko-feature-version: 1
 //
-// file-provider-inmemory — In-Memory-FileProvider für die file-
-// foundation Plugin-API. Speichert Files in einem per-Tenant-Map
-// statt in S3/Hetzner-Object-Storage. Für Demos, Sample-Apps und
-// Tests ohne MinIO-Container.
+// file-provider-inmemory — In-memory file provider for the file-
+// foundation plugin API. Stores files in a per-tenant Map instead
+// of S3/Hetzner object storage. Intended for demos, sample apps,
+// and tests without a MinIO container.
 //
-// **Was diese Feature liefert:**
-//   1. Plugin-Registration via `r.useExtension("fileProvider",
+// **What this feature provides:**
+//   1. Plugin registration via `r.useExtension("fileProvider",
 //      "inmemory", { build })`.
-//   2. **Pro-Tenant Storage.** Jeder Tenant kriegt einen eigenen
-//      InMemoryFileProvider — Tenant-Isolation by-design, keine
-//      Pfad-Konvention nötig.
+//   2. **Per-tenant storage.** Each tenant gets its own
+//      InMemoryFileProvider, providing tenant isolation by design
+//      without requiring a path convention.
 //
-// **Pattern-Vorbild:** mirrors file-provider-s3.
+// **Pattern reference:** mirrors file-provider-s3.
 //
-// **NICHT für Production.** Buffer ist Process-Memory, geht beim
-// Restart verloren + wächst monoton mit jedem write.
+// **NOT for production.** The buffer is process memory, is lost on
+// restart, and grows monotonically with every write.
 
 import type {
   FileProviderContext,
@@ -50,7 +50,7 @@ export function listKeys(tenantId: string): readonly string[] {
   return providersByTenant.get(tenantId)?.keys() ?? [];
 }
 
-/** Demo/Test-Helper: leere den Tenant-Storage. */
+/** Demo/test helper: clears a tenant's storage. */
 export function clearStorage(tenantId: string): void {
   providersByTenant.get(tenantId)?.clear();
 }
@@ -70,9 +70,9 @@ export function createFileProviderInMemoryFeature() {
         category: "storage",
         recommended: false,
       });
-      // Kein requires auf "config" oder "secrets" — der
-      // In-Memory-Provider hat keine Config + kein Secret. Nur die
-      // file-foundation muss da sein (Plugin-extension-point).
+      // No requirement for "config" or "secrets": the
+      // in-memory provider has neither configuration nor secrets. Only
+      // file-foundation must be present as the plugin extension point.
       r.requires({ features: ["file-foundation"] });
 
       const plugin: FileProviderPlugin = {

package/packages/bundled-features/src/file-provider-s3/env-named-feature.ts

@@ -13,8 +13,6 @@ export type NamedS3EnvProviderOptions = {
   readonly name: string;
   /** Env prefix of the credential set, e.g. `RELEASES_S3_`. */
   readonly envPrefix: string;
-  /** Tolerate missing credentials at boot; the provider then fails on its first file operation. */
-  readonly lazy?: boolean;
 };
 
 /** An additional S3 provider next to `"s3-env"`, reading its credentials from `<envPrefix>BUCKET` etc. */

package/packages/bundled-features/src/file-provider-s3/feature.ts

@@ -1,22 +1,22 @@
 // kumiko-feature-version: 1
 //
-// file-provider-s3 — concrete S3-implementation for the
-// file-foundation plugin-API.
+// file-provider-s3 — concrete S3 implementation for the
+// file-foundation plugin API.
 //
-// **Was diese Feature liefert:**
-//   1. Provider-spezifische Tenant-Config (bucket/region/endpoint/
-//      forcePathStyle/accessKeyId) und Secret (s3.secretAccessKey).
-//      Self-contained — file-foundation kennt diese nicht.
-//   2. Plugin-Registration via `r.useExtension("fileProvider", "s3",
-//      { build })`. file-foundation's Factory findet den Plugin via
-//      registry.
-//   3. build(ctx, tenantId) liest config + secret, ruft `createS3Provider`
-//      aus ./lib auf. Der EINZIGE Cross-Feature-Import
-//      des Plugins — bewusst lokal gehalten.
+// **What this feature provides:**
+//   1. Provider-specific tenant config (bucket/region/endpoint/
+//      forcePathStyle/accessKeyId) and secret (s3.secretAccessKey).
+//      Self-contained — file-foundation does not know about these.
+//   2. Plugin registration via `r.useExtension("fileProvider", "s3",
+//      { build })`. file-foundation's factory finds the plugin through
+//      the registry.
+//   3. build(ctx, tenantId) reads the config and secret, then calls
+//      `createS3Provider` from ./lib. This is the plugin's only
+//      cross-feature import, intentionally kept local.
 //
-// **Pattern-Vorbild:** mirrors mail-transport-smtp.
+// **Pattern reference:** mirrors mail-transport-smtp.
 //
-// **Boot-Dependencies:** config + secrets + file-foundation.
+// **Boot dependencies:** config + secrets + file-foundation.
 
 import type {
   FileProviderContext,
@@ -101,8 +101,8 @@ function createTenantConfigFileProviderS3Feature() {
         },
       });
 
-      // Plugin-Registration. entityName "s3" ist was tenants in
-      // file-foundation's `provider` config-key setzen.
+      // Plugin registration. The entityName "s3" is what tenants set in
+      // file-foundation's `provider` config key.
       const plugin: FileProviderPlugin = {
         build: async (ctx: FileProviderContext, tenantId: string) => buildS3Provider(ctx, tenantId), // @wrapper-known semantic-alias
       };

package/packages/bundled-features/src/file-provider-s3/lib/s3-provider.ts

@@ -5,7 +5,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/files";
 
 // =============================================================================
-// Operator-Pflicht-Setup (Multipart-Upload-Cleanup)
+// Required operator setup (multipart-upload cleanup)
 // =============================================================================
 //
 // `writeStream` uses Bun's S3 writer for real multipart streaming. S3
@@ -15,7 +15,7 @@ import {
 // OPEN in S3 and bills storage for the parts already uploaded — until a
 // lifecycle rule aborts it.
 //
-// **Pflicht-Operator-Setup auf jedem Bucket:**
+// **Required operator setup on every bucket:**
 //
 //   {
 //     "Rules": [{
@@ -31,7 +31,7 @@ import {
 // R2 and Minio support the same syntax.
 //
 // =============================================================================
-// Operator-Pflicht-Setup (IAM: list permission)
+// Required operator setup (IAM: list permission)
 // =============================================================================
 //
 // GDPR-forget/tenant-destroy erasure (user-data-rights-defaults) calls
@@ -181,9 +181,9 @@ export function createS3Provider(config: S3ProviderConfig): FileStorageProvider
       options?: SignedUrlOptions,
     ): Promise<string> {
       assertSafeStorageKey(key);
-      // contentDisposition wird von Bun als response-content-disposition
-      // Query-Param signiert (Response-Override fuer den GET-Download) —
-      // der Browser sieht den Original-Dateinamen statt des UUID-Keys.
+      // Bun signs contentDisposition as the response-content-disposition
+      // query parameter (a response override for the GET download) —
+      // the browser sees the original filename instead of the UUID key.
       return client.presign(key, {
         expiresIn: expiresInSeconds,
         method: "GET",

package/packages/bundled-features/src/files/README.md

@@ -15,7 +15,7 @@ bewirtschaftet. Das öffnet die Tür für Cross-Feature-Hooks:
 ## Was es NICHT macht
 
 - **Keine Upload-/Download-Routes** — die bleiben in
-  `framework/src/api/server.ts` via `options.files`-Bootstrap.
+  `framework/src/api/server-routes.ts` (`mountFileRoutes`).
   Multipart-Form-Body und Binary-Streaming passen nicht ins Write/Query-
   Handler-Pattern; ein Refactor zu `r.httpRoute` wäre orthogonal zu
   diesem Sprint.

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

@@ -1,7 +1,7 @@
-// files — full Event-Sourcing für File-Metadata. Die Implementierung (Entity,
-// files:event:*-Events, Inline-Projektion) lebt seit dem ES-Umbau im
-// Framework neben file-routes + fileRefsTable, weil file-routes hart davon
-// abhängt (appendDomainEventCore verlangt registrierte Events + Projektion).
-// Dieses Modul re-exportiert nur, damit der App-Import-Pfad
-// `@cosmicdrift/kumiko-bundled-features/files` stabil bleibt.
+// files — complete event sourcing for file metadata. The implementation (entity,
+// files:event:*-events, inline projection) lives in the framework alongside
+// file-routes and fileRefsTable because file-routes depends on registered events
+// and a projection, as required by appendDomainEventCore.
+// This module only re-exports the feature to keep the app import path
+// `@cosmicdrift/kumiko-bundled-features/files` stable.
 export { createFilesFeature, fileRefEntity } from "@cosmicdrift/kumiko-framework/files";

package/packages/bundled-features/src/files-tenant-data/handlers/sweep-orphaned-derivatives.job.ts

@@ -1,5 +1,5 @@
 // Backfill/GC job for derivatives orphaned by a forget/tenant-destroy that ran
-// before #2461 wired binary cleanup into those flows (#2474). Those older runs
+// before binary cleanup was wired into those flows. Those older runs
 // left the FileRef row gone with no audit trail of what was ever forgotten —
 // so this sweep works forward from the deterministic derivative-key grammar
 // alone: for every key under a tenant's storage prefix that parses as a
@@ -8,8 +8,8 @@
 // a soft-deleted one sitting in trash — means the derivative is still
 // legitimate; only genuinely unreferenced derivatives are swept.
 //
-// Manual trigger only (no cron) — an operator runs this once after upgrading
-// past #2461, or on demand for spot-checks.
+// Manual trigger only (no cron) — an operator runs this once after upgrading,
+// or on demand for spot-checks.
 //
 // Row unit for runChunkedMigration is a discovered derivative CANDIDATE KEY,
 // not a tenant: one tenant's storage listing produces a variable number of
@@ -91,7 +91,7 @@ export async function sweepOrphanedDerivativesJob(
       }
       tenantCursor = tenants.at(-1)?.id;
       for (const tenant of tenants) {
-        const tenantId = tenant.id as TenantId;
+        const tenantId = tenant.id;
         let provider: FileStorageProvider;
         try {
           provider = await resolver(tenantId);
@@ -131,7 +131,7 @@ export async function sweepOrphanedDerivativesJob(
   ): Promise<"migrated" | "skipped" | "failed"> {
     // No isDeleted filter: a soft-deleted (trashed, not yet forgotten) fileRef
     // still legitimately backs its derivatives — only an ABSENT row (forgotten,
-    // or a tenant destroyed before #2461 with no row left at all) makes a
+    // or a tenant destroyed with no row left at all) makes a
     // derivative orphaned.
     const owners = await selectMany(
       db,

package/packages/bundled-features/src/files-tenant-data/hooks.ts

@@ -1,5 +1,5 @@
 // EXT_TENANT_DATA + EXT_STORAGE_PROVIDER destroy hooks for the `fileRef`
-// entity (#2474). Kept apart from the `files` feature (like folders-user-data
+// entity. Kept apart from the `files` feature (like folders-user-data
 // does for EXT_USER_DATA) so file consumers without the tenant-lifecycle
 // pipeline don't pull a hard dependency — `files` stays usable standalone.
 //
@@ -10,18 +10,17 @@
 //     isDeleted filter: tenant-destroy purges trashed rows too, a destroyed
 //     tenant has no "restore from trash" future. ALSO sweeps, per row, any
 //     storageKey that does NOT sit under one of this tenant's own
-//     tenantStoragePrefixes() — the shape a tenant-handover (kumiko-
-//     framework#3035) leaves behind: the fileRef row's tenantId moved to
-//     this tenant, but the bytes stayed under the SOURCE tenant's prefix
-//     (moving them would mean copying bytes, which the handover design
-//     explicitly rejects). Must run here, not in the "files" stage below —
-//     that stage's own prefix sweep only reaches keys under ITS tenant's
-//     prefixes by construction, and by the time it runs this hook has
-//     already forgotten (hard-deleted) the rows it would need to read the
-//     storageKey off. Deleted by STEM prefix (storageKeyStemPrefix), not the
-//     exact key: a derived variant (thumbnail, resized render) has no
-//     `file_refs` row of its own, so only the stem reaches original +
-//     derivatives together.
+//     tenantStoragePrefixes() — the shape a tenant-handover leaves behind:
+//     the fileRef row's tenantId moved to this tenant, but the bytes stayed
+//     under the SOURCE tenant's prefix (moving them would mean copying bytes,
+//     which the handover design explicitly rejects). Must run here, not in
+//     the "files" stage below — that stage's own prefix sweep only reaches
+//     keys under ITS tenant's prefixes by construction, and by the time it
+//     runs this hook has already forgotten (hard-deleted) the rows it would
+//     need to read the storageKey off. Deleted by STEM prefix
+//     (storageKeyStemPrefix), not the exact key: a derived variant
+//     (thumbnail, resized render) has no `file_refs` row of its own, so only
+//     the stem reaches original + derivatives together.
 //   - fileRefStorageDestroyHook ("files" stage, EXT_STORAGE_PROVIDER): wipes
 //     every BINARY (original + derivatives + anything else) under the
 //     tenant's storage prefixes. A full prefix sweep per tenantStoragePrefixes()
@@ -32,19 +31,18 @@
 //     (the provider's own list() prefix already scopes it). Still catches a
 //     blob with no fileRef row at all (the orphan case the row-driven sweep
 //     above cannot see) — REFINED, not replaced, to skip a key a FOREIGN
-//     tenant's fileRef row still references (a tenant-handover, kumiko-
-//     framework#3035, leaves the row's tenantId moved but the storageKey
-//     under THIS tenant's prefix unchanged). By the time this stage runs,
-//     the "app-data" stage (stages.ts DESTRUCTION_STAGES: "app-data" before
-//     "files") has already hard-deleted every row THIS tenant owned, so any
-//     surviving row a listed key still matches is, by construction, a
-//     foreign tenant's — no tenant comparison needed, existence is enough.
-//     The exception is computed from the SURVIVING row's storageKeyStemPrefix
-//     (mirroring the deletion side above), not the listed key's exact match:
-//     a derivative has no fileRef row of its own, so excluding only exact
-//     matches would still delete it out from under the tenant that claimed
-//     its original. Batched: one existence query per chunk of listed keys,
-//     not one query per key.
+//     tenant's fileRef row still references (a tenant-handover leaves the
+//     row's tenantId moved but the storageKey under THIS tenant's prefix
+//     unchanged). By the time this stage runs, the "app-data" stage
+//     (stages.ts DESTRUCTION_STAGES: "app-data" before "files") has already
+//     hard-deleted every row THIS tenant owned, so any surviving row a listed
+//     key still matches is, by construction, a foreign tenant's — no tenant
+//     comparison needed, existence is enough. The exception is computed from
+//     the SURVIVING row's storageKeyStemPrefix (mirroring the deletion side
+//     above), not the listed key's exact match: a derivative has no fileRef row
+//     of its own, so excluding only exact matches would still delete it out
+//     from under the tenant that claimed its original. Batched: one existence
+//     query per chunk of listed keys, not one query per key.
 
 import { createEventStoreExecutor, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import {

package/packages/bundled-features/src/files-tenant-data/index.ts

@@ -1,5 +1,5 @@
 // GDPR tenant-destroy + orphaned-derivative backfill coverage for the `files`
-// feature's `fileRef` entity (#2474). Kept apart from `files` — like
+// feature's `fileRef` entity. Kept apart from `files` — like
 // folders-user-data does for EXT_USER_DATA — so file consumers without the
 // tenant-lifecycle pipeline don't pull a hard dependency; `files` stays usable
 // standalone (e.g. user-data-rights-demo mounts `files` + user-data-rights

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

@@ -127,7 +127,7 @@ export type FoldersFeatureOptions = {
   /** Row-level ownership on the folder-assignment rows themselves — orthogonal
    *  to `access`, which only gates whether a caller may dispatch set/clear/list
    *  at all. Not needed to keep a caller from reading assignments on host
-   *  entities they can't see: that gate is default-on since fw#2766 and derives
+   *  entities they can't see: that gate is default-on and derives
    *  from the entity's `parentRef`. Use `ownership.read` for an ADDITIONAL row
    *  rule on the assignment row itself; it is AND-ed with the host-visibility
    *  gate. Applies only to `folder-assignment`; the `folder` catalog stays

package/packages/bundled-features/src/folders/web/folder-manager.tsx

@@ -521,8 +521,8 @@ export function FolderManager({
 
   // The bucket itself must stay in the tree even when nothing is currently
   // unfiled — it's the only drop target to un-file a leaf back out of a
-  // folder. Regression: #671/5 — an empty `unfiled` array made the bucket
-  // vanish entirely, silently removing that escape hatch.
+  // folder. An empty `unfiled` array made the bucket vanish entirely, silently
+  // removing that escape hatch.
   const hasUnfiled = filing !== undefined;
   if (hasUnfiled) {
     out.push(bucketRow(stripeNext()));

package/packages/bundled-features/src/folders/web/tree.ts

@@ -47,11 +47,11 @@ export function buildFolderTree(rows: readonly FolderRow[]): readonly FolderNode
   return build(null, 0);
 }
 
-// "Immobilie Berlin / Person Müller" for a folder id, walking parentId up.
-// Empty string if the id is unknown. The row-count cap stops a (currently
-// impossible — no reparent yet) parent cycle from spinning forever — `< `,
-// not `<=` (658/4): a cycle of exactly rows.length nodes must stop AT the
-// cap, not run one iteration past it.
+// Returns a path such as "Properties / Berlin" for a folder id by walking
+// parentId upward, or an empty string if the id is unknown. The row-count cap
+// stops a parent cycle (currently impossible, since there is no reparent yet)
+// from spinning forever. Use `<`, not `<=`: a cycle of exactly rows.length
+// nodes must stop at the cap, not run one iteration past it.
 export function folderPath(rows: readonly FolderRow[], id: string, separator = " / "): string {
   const byId = new Map(rows.map((r) => [r.id, r]));
   const names: string[] = [];

package/packages/bundled-features/src/form-draft/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Encrypted drafts without a PII key service raise an error",
+    "detail": "Reading a ciphertext draft with no PII subject key service configured throws instead of returning an empty draft, so the stale-draft cleanup defers it and no longer releases its file refs as if it were empty."
+  },
   {
     "version": "0.379.0",
     "type": "breaking",

package/packages/bundled-features/src/form-draft/db/queries/cleanup.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
+import { toPostgresArrayLiteral, unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { readStoredDraft } from "../../decrypt-draft.ts";
@@ -22,7 +22,7 @@ export type StaleDraftRow = {
 // once; a draft saved exactly once (create, never updated) has no
 // modified_at yet, so falls back to inserted_at.
 //
-// Reads the blob + tenantId BEFORE anything is deleted (issue #1915) — the
+// Reads the blob + tenantId BEFORE anything is deleted — the
 // caller (cleanup.job.ts) walks each row's blob for FileRefs and releases
 // them per-tenant via ctx._fileProviderResolver, then deletes the batch
 // per-row via formDraftExecutor.delete (event-sourced, not raw SQL — a
@@ -48,7 +48,7 @@ export async function selectStaleDraftsBatch(
      AND NOT ("id"::text = ANY($3::text[]))
      ORDER BY COALESCE("modified_at", "inserted_at") ASC
      LIMIT $2`,
-    [olderThanDays, batchSize, [...excludeIds]],
+    [olderThanDays, batchSize, toPostgresArrayLiteral([...excludeIds])],
   );
   return Promise.all(
     rows.map(async (row) => {

package/packages/bundled-features/src/form-draft/db/queries/owned-file-refs.ts

@@ -8,7 +8,7 @@ import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 
 // Narrows a draft blob's raw FileRef-shaped storageKeys (collectDraftFileRefKeys
-// output — extracted from free-form, client-supplied JSON, issue #1889) down to
+// output — extracted from free-form, client-supplied JSON) down to
 // the ones with a real, non-deleted file_refs row owned by this exact
 // (tenantId, ownerId). Without this, a crafted draft value like
 // { storageKey: "<someone-else's-real-key>" } would reach the storage

package/packages/bundled-features/src/form-draft/decrypt-draft.ts

@@ -4,6 +4,7 @@ import {
   decryptPiiFieldValues,
   isPiiCiphertext,
 } from "@cosmicdrift/kumiko-framework/crypto";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { type FormDraftBlob, formDraftBlobSchema } from "./schemas.ts";
 
 // Raw reads (fetchOne/selectMany/SQL) return the stored column, which is
@@ -13,7 +14,9 @@ import { type FormDraftBlob, formDraftBlobSchema } from "./schemas.ts";
 export async function readStoredDraft(stored: unknown): Promise<FormDraftBlob | null> {
   let plain = stored;
   const kms = configuredPiiSubjectKms();
-  if (isPiiCiphertext(stored) && kms) {
+  if (isPiiCiphertext(stored)) {
+    // A silent null would make the stale-draft cleanup treat the draft as empty and leak its file refs.
+    if (!kms) throw new InternalError({ message: "form-draft: pii kms not configured" });
     const out = await decryptPiiFieldValues({ draft: stored }, ["draft"], kms, {
       requestId: requestContext.get()?.requestId ?? "form-draft:read",
     });

package/packages/bundled-features/src/form-draft/entity.ts

@@ -11,8 +11,8 @@ import { FORM_DRAFT_KEY_MAX_LENGTH, FORM_DRAFT_UNIQUE_KEY_CONSTRAINT } from "./w
 // (tenant, ownerId): the same key from two different users, or the same
 // user in two different tenants, is a different draft.
 //
-// Boundary (issue #1889): form-draft never holds anything that already
-// lives in a domain stream — it's a Zwischenstand BEFORE the domain entity
+// Boundary: form-draft never holds anything that already
+// lives in a domain stream — it's an intermediate state BEFORE the domain entity
 // is created. Consumers delete the draft (discard handler) once the real
 // submit succeeds; partially-created domain data past that point is the
 // consuming app's concern, not this feature's.
@@ -34,7 +34,7 @@ export const formDraftEntity = createEntity({
       personal: false,
       reason: "technical_reference",
     }),
-    // The blob shape is fixed by issue #1889, not left to the caller:
+    // The blob shape is fixed, not left to the caller:
     // { values: Record<string, unknown>, stepIndex: number, savedAt: string }.
     // Free-form because `values` mirrors whatever fields the in-progress
     // form has, so it can carry arbitrary user-entered PII. Encrypted under

package/packages/bundled-features/src/form-draft/feature.ts

@@ -1,9 +1,8 @@
 // form-draft — a per-user, per-tenant working copy of an in-progress form,
-// saved BEFORE the real domain entity exists. Backing for wizard-mode resume
-// (kumiko-framework#1884/#1883): a caller-assigned draftKey (typically
-// screenId + optional hostEntityId) round-trips { values, stepIndex,
-// savedAt } through save/discard/get. See entity.ts for the ownership +
-// uniqueness model.
+// saved BEFORE the real domain entity exists. Backing for wizard-mode resume.
+// A caller-assigned draftKey (typically screenId + optional hostEntityId)
+// round-trips { values, stepIndex, savedAt } through save/discard/get. See
+// entity.ts for the ownership + uniqueness model.
 
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";

package/packages/bundled-features/src/form-draft/handlers/discard.write.ts

@@ -79,7 +79,7 @@ export const discardDraftWrite = defineWriteHandler({
       // Fail-closed erase of file_refs rows FIRST (outside the best-effort
       // storage-hygiene loop). releaseDraftFileRefs swallows per-key errors
       // by design — routing forget through it would report discarded:true
-      // while leaving the row behind (#1922 / review #2009).
+      // while leaving the row behind.
       for (const ref of ownedRefs) {
         const forgetResult = await fileRefExecutor.forget({ id: ref.id }, event.user, ctx.db);
         if (!forgetResult.isSuccess) return forgetResult;

package/packages/bundled-features/src/form-draft/release-file-refs.ts

@@ -1,7 +1,7 @@
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type { FormDraftBlob } from "./schemas.ts";
 
-// The draft blob's `values` is free-form by design (issue #1889: form-draft
+// The draft blob's `values` is free-form by design: form-draft
 // never knows the consuming form's field schema, only { values, stepIndex,
 // savedAt }). A FileRef pointer is therefore recognised purely by shape —
 // any object anywhere in `values` carrying a non-empty string `storageKey`
@@ -48,11 +48,11 @@ export function collectDraftFileRefKeys(
 //
 // Takes an already-decided key list, not the draft blob — callers must run
 // collectDraftFileRefKeys() output through db/queries' owned-storage-key
-// filter first. `values` is free-form, client-supplied JSON (issue #1889);
-// releasing a key straight out of it without verifying a real, owned
-// file_refs row exists would let a crafted `{ storageKey: "<victim's key>" }`
-// delete someone else's file — the same ownership check file-routes.ts runs
-// before every read/delete (loadFileForTenant + FileAccessGuard).
+// filter first. `values` is free-form, client-supplied JSON; releasing a key
+// straight out of it without verifying a real, owned file_refs row exists
+// would let a crafted `{ storageKey: "<victim's key>" }` delete someone
+// else's file — the same ownership check file-routes.ts runs before every
+// read/delete (loadFileForTenant + FileAccessGuard).
 export async function releaseDraftFileRefs(
   keys: readonly string[],
   deleteBinary: (storageKey: string) => Promise<void>,

package/packages/bundled-features/src/form-draft/schemas.ts

@@ -17,9 +17,9 @@ const draftValuesSchema = z
     `values exceeds the ${FORM_DRAFT_VALUES_MAX_BYTES}-byte limit`,
   );
 
-// The draft blob shape — fixed by issue #1889 here, not left for consumers
+// The draft blob shape — fixed here, not left for consumers
 // to invent per-app. `stepIndex` is in from the start so wizard-mode resume
-// (kumiko-framework#1884) doesn't need a later migration.
+// doesn't need a later migration.
 export const formDraftBlobSchema = z.object({
   values: z.record(z.string(), z.unknown()),
   stepIndex: z.number().int().min(0),
@@ -41,7 +41,7 @@ export type SaveDraftPayload = z.infer<typeof saveDraftPayloadSchema>;
 // row right after the domain entity write already carries the same
 // storageKeys forward — releasing them here would destroy files the entity
 // now depends on. Only an actual abandon/abort flow should pass
-// releaseFiles: true (issue #1915's "explicit abort" case).
+// releaseFiles: true (the "explicit abort" case).
 export const discardDraftPayloadSchema = z.object({
   draftKey: draftKeySchema,
   releaseFiles: z.boolean().optional(),

package/packages/bundled-features/src/form-draft/web/constants.ts

@@ -1,6 +1,4 @@
 // form-draft bundle constants — feature-name + qualified handler/query names.
-//
-// Part of CosmicDriftGameStudio/kumiko-framework#1883 (wizard mode), issue #1889.
 
 import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
 

package/packages/bundled-features/src/host-routing/README.md

@@ -92,5 +92,5 @@ allowlists stay in the app: wrap the dispatch function and fall through to it.
 
 - `tenantBy: (host, db) => TenantId | null` resolves every host that is neither the apex nor a fixed host (profile subdomains, custom domains). The tenant must be enabled and active; null means 404 for pages and `tenant_required` for the API. `createHostTenantIdResolver(options, db)` exposes the same mapping for managed-pages' `resolveApexTenant`.
 - `tenantPathPrefix` is optional in host and resolver mode and serves `<prefix>/<key>` on the apex. The API half still takes the apex anchor there; an app that needs a path-named tenant on API calls resolves it itself.
-- `redirects: [{ from, to, host?, status? }]` run before host classification. `to` is configured, never derived from the request.
+- `redirects: [{ from, to, host?, status? }]` run before host classification inside hostDispatch, i.e. only for requests that reach the HTML fallback (no static file, no API route); a `from` that matches a static file or `/api/...` never fires. `to` is configured, never derived from the request.
 - `apexAnonymousQueryAllowlist: { "example.com": ["feature:query:x"] }` limits the anonymous apex anchor to the listed query types on that host, for `/api/query` and `/api/stream`; other paths keep the anchor. `example.com` and `www.example.com` share one entry (a host without its own uses the other's). Combined with `tenantBy: "path"` it throws at boot, because the client names its tenant there (X-Tenant wins over the resolver) and would bypass the allowlist.

package/packages/bundled-features/src/host-routing/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Redirects documented as hostDispatch-only",
+    "detail": "The redirects option and README state that redirects run inside hostDispatch, so only for requests that reach the HTML fallback; a from matching a static file or an API route never fires. The shared existence lookup of the host and resolver modes is one helper."
+  },
   {
     "version": "0.376.0",
     "type": "improvement",