@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,205 @@
+// @runtime client
+// FolderSection — drop-in single-folder picker for ANY entity. Unlike tags
+// (many-to-many multi-combobox), an entity lives in exactly ONE folder, so this
+// is a single-select combobox with a "no folder" option plus a compact row to
+// create-and-file a brand-new folder. Folder writes are immediate (set/clear are
+// idempotent), so the section owns its state and refetches after each action —
+// it is NOT part of a host form's save.
+//
+// Two ways to mount (both need foldersClient() registered once, for i18n):
+//   - standalone:   <FolderSection entityName="credit" entityId={creditId} />
+//   - extension:    a screen-schema section with
+//                   component: { react: { __component: FOLDER_SECTION_EXTENSION_NAME } }
+//                   (RenderEdit passes { entityName, entityId }).
+
+import {
+  useDispatcher,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import { FoldersHandlers, FoldersQueries } from "../constants.js";
+import { type FolderRow, folderPath } from "./tree.js";
+
+type AssignmentRow = {
+  readonly folderId: string;
+  readonly entityType: string;
+  readonly entityId: string;
+};
+type FolderListResponse = { readonly rows: readonly FolderRow[] };
+type AssignmentListResponse = { readonly rows: readonly AssignmentRow[] };
+
+// Sentinel for the "no folder" combobox option — selecting it clears the
+// assignment. Empty string can't collide with a folder id (uuid).
+const NO_FOLDER = "";
+
+export function FolderSection({
+  entityName,
+  entityId,
+}: {
+  readonly entityName: string;
+  readonly entityId: string | null;
+}): ReactNode {
+  const { Banner, Button, Field, Input, Text } = usePrimitives();
+  const t = useTranslation();
+  const dispatcher = useDispatcher();
+  const enabled = entityId !== null;
+  const catalog = useQuery<FolderListResponse>(FoldersQueries.folderList, {}, { enabled });
+  const assignments = useQuery<AssignmentListResponse>(
+    FoldersQueries.assignmentList,
+    {
+      // entityType server-side, not just entityId: it collapses the parent-ref
+      // read gate to this one host entity instead of every registered one.
+      filters: [
+        { field: "entityType", op: "eq", value: entityName },
+        { field: "entityId", op: "eq", value: entityId },
+      ],
+    },
+    { enabled },
+  );
+  const [newName, setNewName] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [errorKey, setErrorKey] = useState<string | null>(null);
+
+  if (entityId === null) {
+    return (
+      <Banner variant="info" testId="folder-section-create-mode">
+        <Text>{t("folders.section.createMode")}</Text>
+      </Banner>
+    );
+  }
+  if (
+    (catalog.loading && catalog.data === null) ||
+    (assignments.loading && assignments.data === null)
+  ) {
+    return (
+      <Banner variant="loading" testId="folder-section-loading">
+        <Text>{t("folders.section.loading")}</Text>
+      </Banner>
+    );
+  }
+  const queryError = catalog.error ?? assignments.error;
+  if (queryError) {
+    return (
+      <Banner variant="error" testId="folder-section-error">
+        <Text>{t(queryError.i18nKey, queryError.i18nParams)}</Text>
+      </Banner>
+    );
+  }
+
+  const folders = catalog.data?.rows ?? [];
+  const currentFolderId =
+    (assignments.data?.rows ?? []).find((r) => r.entityType === entityName)?.folderId ?? NO_FOLDER;
+  const options = [
+    { value: NO_FOLDER, label: t("folders.section.none") },
+    ...folders.map((f) => ({ value: f.id, label: folderPath(folders, f.id) })),
+  ];
+
+  const refetch = async (): Promise<void> => {
+    await Promise.all([catalog.refetch(), assignments.refetch()]);
+  };
+
+  const apply = async (write: () => Promise<boolean>): Promise<void> => {
+    setBusy(true);
+    setErrorKey(null);
+    try {
+      if (await write()) await refetch();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
+    const result = await dispatcher.write(type, payload);
+    if (!result.isSuccess) {
+      setErrorKey(result.error.i18nKey);
+      return false;
+    }
+    return true;
+  };
+
+  const onSelect = (next: string): void => {
+    if (next === currentFolderId) return;
+    void apply(() =>
+      next === NO_FOLDER
+        ? writeOk(FoldersHandlers.clearFolder, { entityType: entityName, entityId })
+        : writeOk(FoldersHandlers.setFolder, { folderId: next, entityType: entityName, entityId }),
+    );
+  };
+
+  const createAndFile = (): void => {
+    const name = newName.trim();
+    if (name === "") return;
+    void apply(async () => {
+      const created = await dispatcher.write<{ id: string }>(FoldersHandlers.createFolder, {
+        name,
+      });
+      if (!created.isSuccess) {
+        setErrorKey(created.error.i18nKey);
+        return false;
+      }
+      if (
+        !(await writeOk(FoldersHandlers.setFolder, {
+          folderId: created.data.id,
+          entityType: entityName,
+          entityId,
+        }))
+      ) {
+        return false;
+      }
+      setNewName("");
+      return true;
+    });
+  };
+
+  return (
+    <div data-testid="folder-section" className="flex flex-col gap-4">
+      <Field id="folder-section-select" label={t("folders.section.label")}>
+        <Input
+          kind="combobox"
+          id="folder-section-select"
+          name="folder"
+          options={options}
+          value={currentFolderId}
+          onChange={onSelect}
+          disabled={busy}
+          placeholder={t("folders.section.placeholder")}
+          emptyText={t("folders.section.empty")}
+        />
+      </Field>
+
+      {/* Inline create-row: das Ordner-Input wächst, der Anlegen-Button sitzt
+          rechts daneben. ponytail: separate Zeile, weil die Combobox keine
+          create-on-type-Affordance hat — fold-in, wenn renderer-web ein
+          onCreate-Prop bekommt. */}
+      <div className="flex items-end gap-2">
+        <div className="flex-1">
+          <Field id="folder-section-new" label={t("folders.section.newLabel")}>
+            <Input
+              kind="text"
+              id="folder-section-new"
+              name="newFolder"
+              value={newName}
+              onChange={setNewName}
+            />
+          </Field>
+        </div>
+        <Button
+          variant="secondary"
+          disabled={busy || newName.trim() === ""}
+          onClick={() => createAndFile()}
+          testId="folder-section-create"
+        >
+          {busy ? t("folders.section.working") : t("folders.section.create")}
+        </Button>
+      </div>
+
+      {errorKey !== null && (
+        <Banner variant="error" testId="folder-section-action-error">
+          <Text>{t(errorKey)}</Text>
+        </Banner>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,34 @@
+// @runtime client
+// Default translation bundle for the folders UI. foldersClient() hangs it into
+// the LocaleProvider as a fallback bundle — apps override individual keys via
+// foldersClient({ translations }). Keys follow `folders.<area>.<slug>`.
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  en: {
+    "folders.section.createMode": "Save the entity first to pick a folder.",
+    "folders.section.loading": "Loading…",
+    "folders.section.label": "Folder",
+    "folders.section.placeholder": "Select a folder…",
+    "folders.section.empty": "No folders found.",
+    "folders.section.none": "— No folder —",
+    "folders.section.newLabel": "New folder",
+    "folders.section.create": "Create & file",
+    "folders.section.working": "Saving…",
+
+    "folders.manager.loading": "Loading…",
+    "folders.manager.newRoot": "New folder",
+    "folders.manager.add": "Create",
+    "folders.manager.addChild": "Subfolder",
+    "folders.manager.rename": "Rename",
+    "folders.manager.delete": "Delete",
+    "folders.manager.save": "Save",
+    "folders.manager.cancel": "Cancel",
+    "folders.manager.working": "Saving…",
+    "folders.manager.deleteBlocked": "Remove subfolders first.",
+    "folders.manager.deleteConfirmTitle": "Delete folder?",
+    "folders.manager.deleteConfirmBody":
+      "The folder will be removed. Filed entries move back to Unfiled.",
+  },
+};

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

@@ -0,0 +1,6 @@
+// @runtime client
+export { FOLDER_SECTION_EXTENSION_NAME, FoldersHandlers, FoldersQueries } from "../constants.js";
+export { foldersClient } from "./client-plugin.js";
+export { type FolderFiling, type FolderLeaf, FolderManager } from "./folder-manager.js";
+export { FolderSection } from "./folder-section.js";
+export { buildFolderTree, type FolderNode, type FolderRow, folderPath } from "./tree.js";

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

@@ -0,0 +1,65 @@
+// @runtime client
+// Pure tree helpers shared by FolderManager (nested render) and FolderSection
+// (path-labelled options). No React, no IO — folder rows in, structure out, so
+// both can be unit-tested without a renderer harness.
+
+export type FolderRow = {
+  readonly id: string;
+  readonly name: string;
+  readonly parentId: string | null;
+  readonly version: number;
+};
+
+export type FolderNode = FolderRow & {
+  readonly children: readonly FolderNode[];
+  readonly depth: number;
+};
+
+function byName(a: FolderRow, b: FolderRow): number {
+  return a.name.localeCompare(b.name);
+}
+
+// Roots (parentId null OR pointing at a row that no longer exists — a dangling
+// parentId from a deleted parent stays visible at the top instead of vanishing)
+// with children attached recursively, each level sorted by name.
+export function buildFolderTree(rows: readonly FolderRow[]): readonly FolderNode[] {
+  const byParent = new Map<string | null, FolderRow[]>();
+  const ids = new Set(rows.map((r) => r.id));
+  for (const row of rows) {
+    const key = row.parentId !== null && ids.has(row.parentId) ? row.parentId : null;
+    const siblings = byParent.get(key);
+    if (siblings) siblings.push(row);
+    else byParent.set(key, [row]);
+  }
+  // visited guards against a parent cycle recursing forever (658/4) —
+  // currently impossible (no reparent feature yet), but cheap insurance for
+  // when one lands; a cyclic node's subtree just stops re-descending.
+  // No cycle guard needed (658/4, verified not just asserted): build() only
+  // descends via byParent[parentId] starting from roots (parentId === null
+  // or dangling) — a row in a cycle has a non-null, existing parentId by
+  // definition, so it can never be a root, and each row contributes exactly
+  // one parentId edge, so nothing outside a cycle points into it either. A
+  // pure a<->b cycle is structurally unreachable from build(null).
+  const build = (parentId: string | null, depth: number): readonly FolderNode[] =>
+    (byParent.get(parentId) ?? [])
+      .slice()
+      .sort(byName)
+      .map((row) => ({ ...row, depth, children: build(row.id, depth + 1) }));
+  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.
+export function folderPath(rows: readonly FolderRow[], id: string, separator = " / "): string {
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  const names: string[] = [];
+  let current = byId.get(id);
+  for (let i = 0; current !== undefined && i < rows.length; i += 1) {
+    names.unshift(current.name);
+    current = current.parentId !== null ? byId.get(current.parentId) : undefined;
+  }
+  return names.join(separator);
+}

package/packages/bundled-features/src/folders-user-data/changes.json

@@ -0,0 +1 @@
+[]

package/packages/bundled-features/src/folders-user-data/hooks.ts

@@ -0,0 +1,76 @@
+// EXT_USER_DATA hooks for the folder + folder-assignment entities (GDPR Art. 20
+// export / Art. 17 erasure). Lives apart from the folders feature so folders
+// consumers without the user-data-rights pipeline don't pull a hard dependency.
+// Mirrors credit-user-data — standard tenant-scoped pattern, no name-stripping
+// (a folder name is tenant data, not per-user PII).
+
+import type { EventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntityExecutor,
+  createSystemUser,
+  type UserDataDeleteHook,
+  type UserDataExportHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { folderAssignmentEntity, folderEntity } from "../folders/index.js";
+
+const { table: folderTable, executor: folderExecutor } = createEntityExecutor(
+  "folder",
+  folderEntity,
+);
+const { table: folderAssignmentTable, executor: folderAssignmentExecutor } = createEntityExecutor(
+  "folder-assignment",
+  folderAssignmentEntity,
+);
+
+// Folders are tenant-scoped (no per-user owner column). Every tenant user reads
+// all tenant folders in-app, so bundling them into the user's export is no new
+// exposure — it gives the data subject the organisation of the loans they work with.
+export const folderExportHook: UserDataExportHook = async (ctx) => {
+  const rows = await ctx.db.selectMany(folderTable, { tenantId: ctx.tenantId });
+  if (rows.length === 0) return null;
+  return { entity: "folder", rows };
+};
+
+export const folderAssignmentExportHook: UserDataExportHook = async (ctx) => {
+  // folderAssignmentEntity is softDelete: true — a cleared assignment
+  // (isDeleted: true) is a removed folder membership, not something the GDPR
+  // export should still surface as current data.
+  const rows = await ctx.db.selectMany(folderAssignmentTable, {
+    tenantId: ctx.tenantId,
+    isDeleted: false,
+  });
+  if (rows.length === 0) return null;
+  return { entity: "folder-assignment", rows };
+};
+
+// Tenant-scoped erasure is only safe when the tenant is effectively single-user
+// (set by the forget orchestrator from the app's tenantModel + a runtime
+// sole-member check). In a multi-user tenant this stays a no-op: deleting by
+// tenant would destroy co-members' folders. anonymize is also a no-op — folder
+// rows carry no person-link to strip (name is tenant data, not PII), so a
+// retention hold simply keeps them.
+function tenantScopedDelete(
+  table: typeof folderTable,
+  executor: EventStoreExecutor,
+): UserDataDeleteHook {
+  return async (ctx, strategy) => {
+    // skip: multi-user tenant — a tenant-wide delete would destroy co-members' folders
+    if (ctx.tenantModel !== "single-user") return;
+    // skip: anonymize is a no-op — folder rows carry no per-user PII to strip
+    if (strategy === "anonymize") return;
+    // Per-row via the executor (event -> rebuild-safe): a bulk deleteMany is
+    // eventless, so a projection rebuild resurrects the rows. Bounded — forget
+    // only fires for single-user tenants.
+    const systemUser = createSystemUser(ctx.tenantId);
+    const rows = await ctx.db.selectMany<{ id: string }>(table, { tenantId: ctx.tenantId });
+    for (const row of rows) {
+      await executor.delete({ id: row.id }, systemUser, ctx.db);
+    }
+  };
+}
+
+export const folderDeleteHook: UserDataDeleteHook = tenantScopedDelete(folderTable, folderExecutor);
+export const folderAssignmentDeleteHook: UserDataDeleteHook = tenantScopedDelete(
+  folderAssignmentTable,
+  folderAssignmentExecutor,
+);

package/packages/bundled-features/src/folders-user-data/index.ts

@@ -0,0 +1,33 @@
+// Provides the EXT_USER_DATA export/delete hooks for the folder + folder-assignment
+// entities as a standalone feature — mount it alongside the folders feature +
+// user-data-rights when an app needs folders in its GDPR export/forget pipeline.
+// Kept separate from the folders feature (which only requires "tenant") so
+// folders stays usable without the user-data-rights stack. Mirrors credit-user-data.
+
+import { defineFeature, EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  folderAssignmentDeleteHook,
+  folderAssignmentExportHook,
+  folderDeleteHook,
+  folderExportHook,
+} from "./hooks.js";
+
+export const foldersUserDataFeature = defineFeature("folders-user-data", (r) => {
+  r.describe(
+    "GDPR (Art. 20 export / Art. 17 erasure) coverage for the `folders` feature's `folder` + `folder-assignment` entities. Mounts the EXT_USER_DATA export + delete hooks so a tenant's folder tree and its entity-to-folder assignments are included in the user-data export bundle and erased on a tenant-scoped forget (single-user tenants only; multi-user + anonymize are no-ops since folder rows carry no per-user PII). Kept separate from `folders` so folder consumers without the user-data-rights pipeline don't pull a hard dependency — requires `user-data-rights`, optionalRequires `folders`.",
+  );
+  // user-data-rights is the hard dependency (EXT_USER_DATA host). `folders` is
+  // OPTIONAL: if it's mounted toggleable(default=false) (e.g. per-tenant via
+  // tier), a hard r.requires would throw an "effectively disabled" boot
+  // warning even though the folder entities exist and the hooks work fine.
+  r.requires("user-data-rights");
+  r.optionalRequires("folders");
+  r.useExtension(EXT_USER_DATA, "folder", {
+    export: folderExportHook,
+    delete: folderDeleteHook,
+  });
+  r.useExtension(EXT_USER_DATA, "folder-assignment", {
+    export: folderAssignmentExportHook,
+    delete: folderAssignmentDeleteHook,
+  });
+});

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

@@ -0,0 +1 @@
+[]

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

@@ -0,0 +1,50 @@
+// @runtime client
+// 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";
+
+export const FORM_DRAFT_FEATURE_NAME = "form-draft";
+
+// Qualified handler/query names (QN format: scope:type:name). Clients
+// reference the object instead of magic strings.
+export const FormDraftHandlers = {
+  save: "form-draft:write:save",
+  discard: "form-draft:write:discard",
+} as const;
+
+export const FormDraftQueries = {
+  get: "form-draft:query:get",
+  list: "form-draft:query:list",
+} as const;
+
+// Any authenticated tenant user may save/discard/read their OWN draft — the
+// per-row ownerId check in the handlers (not roles) is what keeps a draft
+// private to the user who created it. See handlers/*.ts.
+export const FORM_DRAFT_ACCESS: AccessRule = {
+  openToAll: {
+    reason:
+      "any signed-in tenant user may save, discard or read a draft; the per-row " +
+      "ownerId check in the handlers, not roles, keeps a draft private to its owner",
+  },
+};
+
+// Unique index name — shared between entity.ts (index declaration) and
+// handlers/save.write.ts (unique-violation race detection).
+export const FORM_DRAFT_UNIQUE_KEY_CONSTRAINT = "read_form_drafts_tenant_owner_key_uniq";
+
+export const FORM_DRAFT_KEY_MAX_LENGTH = 256;
+
+// `values` is unbounded, caller-controlled JSON (wizard-form fields) — an
+// autosaving frontend or a malicious authenticated caller could otherwise
+// grow a single draft row without limit. Each save appends an event to the
+// append-only event store, so an oversized draft is also a permanent
+// storage cost, not just a transient one.
+export const FORM_DRAFT_VALUES_MAX_BYTES = 64 * 1024;
+
+// Cap on concurrent drafts per (tenant, ownerId) — without it, an
+// autosaving frontend generating a new create-mode draftId per abandoned
+// wizard session grows the event stream without bound (every save is an
+// append-only event).
+export const FORM_DRAFT_MAX_PER_OWNER = 50;

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

@@ -0,0 +1,72 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { Temporal } from "temporal-polyfill";
+import type { FormDraftBlob } from "../../schemas.js";
+
+export type StaleDraftRow = {
+  readonly id: string;
+  readonly tenantId: TenantId;
+  readonly ownerId: string;
+  readonly draftKey: string;
+  readonly draft: FormDraftBlob;
+  readonly insertedAt: Temporal.Instant;
+};
+
+// COALESCE(modified_at, inserted_at) — a draft's "last touched" timestamp is
+// modified_at once the upsert path (save.write.ts) has updated it at least
+// 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
+// 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
+// rebuild must not resurrect a "deleted" draft). Ordered oldest-first so a
+// batch is a stable, deterministic slice across the two queries.
+export async function selectStaleDraftsBatch(
+  db: DbConnection,
+  olderThanDays: number,
+  batchSize: number,
+): Promise<readonly StaleDraftRow[]> {
+  const rows = (await unsafeReadRetrying(
+    db,
+    `SELECT "id", "tenant_id", "owner_id", "draft_key", "draft", "inserted_at" FROM "read_form_drafts"
+     WHERE COALESCE("modified_at", "inserted_at") < now() - ($1::int * interval '1 day')
+     ORDER BY COALESCE("modified_at", "inserted_at") ASC
+     LIMIT $2`,
+    [olderThanDays, batchSize],
+  )) as readonly {
+    id: string;
+    tenant_id: string;
+    owner_id: string;
+    draft_key: string;
+    draft: FormDraftBlob;
+    inserted_at: Date;
+  }[];
+  return rows.map((row) => ({
+    id: row.id,
+    tenantId: row.tenant_id as TenantId, // @cast-boundary db-row
+    ownerId: row.owner_id,
+    draftKey: row.draft_key,
+    draft: row.draft,
+    insertedAt: Temporal.Instant.fromEpochMilliseconds(+row.inserted_at), // @cast-boundary db-row
+  }));
+}
+
+/** Re-check staleness after the select→release window so a freshly saved draft is not deleted. */
+export async function isDraftStillStale(
+  db: DbConnection,
+  id: string,
+  olderThanDays: number,
+): Promise<boolean> {
+  const rows = (await unsafeReadRetrying(
+    db,
+    `SELECT 1 FROM "read_form_drafts"
+     WHERE "id" = $1
+       AND COALESCE("modified_at", "inserted_at") < now() - ($2::int * interval '1 day')
+     LIMIT 1`,
+    [id, olderThanDays],
+  )) as readonly unknown[];
+  return rows.length > 0;
+}

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

@@ -0,0 +1,21 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+// COUNT(*), not selectMany(...).length — save.write.ts checks this on every
+// create, and a draft's `values` blob can be up to FORM_DRAFT_VALUES_MAX_BYTES
+// (64KB); loading up to FORM_DRAFT_MAX_PER_OWNER full rows just to count them
+// would be several MB of wasted transfer per save.
+export async function countDraftsByOwner(
+  db: DbRunner,
+  tenantId: TenantId,
+  ownerId: string,
+): Promise<number> {
+  const rows = (await unsafeReadRetrying(
+    db,
+    `SELECT count(*)::int AS "count" FROM "read_form_drafts"
+     WHERE "tenant_id" = $1 AND "owner_id" = $2`,
+    [tenantId, ownerId],
+  )) as readonly { count: number }[];
+  return rows[0]?.count ?? 0;
+}

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

@@ -0,0 +1,74 @@
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { Temporal } from "temporal-polyfill";
+
+// Narrows a draft blob's raw FileRef-shaped storageKeys (collectDraftFileRefKeys
+// output — extracted from free-form, client-supplied JSON, issue #1889) 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
+// provider's delete() unchecked — the same ownership boundary file-routes.ts
+// enforces (loadFileForTenant + FileAccessGuard) before every read/delete.
+//
+// `draftInsertedAt` additionally excludes FileRefs that existed BEFORE the
+// draft row was created. In edit-mode the draft blob carries the full form
+// values, including FileRef pointers the domain entity pre-filled — those
+// storageKeys are owned by the caller (uploaded by them, on an earlier
+// entity) but must survive a discard/cleanup sweep because the live entity
+// still references them. Only uploads that happened during THIS draft's
+// lifetime (inserted after the draft row) are release-eligible.
+//
+// `isCreateMode` bypasses that timestamp filter entirely: a create-mode
+// draftKey (`${screenId}:new:${draftId}`) mints its draftId lazily on the
+// first step-change, so a file uploaded on step 0 gets a file_refs row
+// timestamped BEFORE the draft row exists. There is no pre-filled entity in
+// create-mode — every FileRef the draft references is draft-owned — so the
+// filter would otherwise permanently exclude that key from every future
+// discard/cleanup, leaking it as an unreleasable storage object.
+export async function filterOwnedStorageKeys(
+  db: DbRunner,
+  tenantId: TenantId,
+  ownerId: string,
+  candidateKeys: readonly string[],
+  draftInsertedAt: Temporal.Instant,
+  isCreateMode: boolean,
+): Promise<readonly string[]> {
+  const rows = await filterOwnedFileRefs(
+    db,
+    tenantId,
+    ownerId,
+    candidateKeys,
+    draftInsertedAt,
+    isCreateMode,
+  );
+  return rows.map((row) => row.storageKey);
+}
+
+// Same ownership boundary as filterOwnedStorageKeys, but also returns the
+// file_refs row id — a hard-erasure call (executor.forget) addresses the
+// row by id, not by storageKey.
+export type OwnedFileRef = {
+  readonly id: string;
+  readonly storageKey: string;
+};
+
+export async function filterOwnedFileRefs(
+  db: DbRunner,
+  tenantId: TenantId,
+  ownerId: string,
+  candidateKeys: readonly string[],
+  draftInsertedAt: Temporal.Instant,
+  isCreateMode: boolean,
+): Promise<readonly OwnedFileRef[]> {
+  if (candidateKeys.length === 0) return [];
+  const rows = (await unsafeReadRetrying(
+    db,
+    `SELECT "id", "storage_key" FROM "file_refs"
+     WHERE "tenant_id" = $1 AND "inserted_by_id" = $2
+       AND "storage_key" = ANY($3::text[]) AND "is_deleted" = false
+       AND ($5::boolean OR "inserted_at" > $4::timestamptz)`,
+    [tenantId, ownerId, candidateKeys, draftInsertedAt.toString(), isCreateMode],
+  )) as readonly { id: string; storage_key: string }[];
+  return rows.map((row) => ({ id: row.id, storageKey: row.storage_key }));
+}