@cosmicdrift/kumiko-bundled-features 0.187.0 → 0.188.0

package/src/form-draft/__tests__/form-draft.integration.test.ts

@@ -0,0 +1,232 @@
+// Full-stack integration for the form-draft bundle. Drives save → get →
+// discard through the real dispatcher + entity-projection + DB:
+//   - save upserts (tenantId, ownerId, draftKey) — a second save for the
+//     same key updates the existing row, it never duplicates
+//   - get resolves { draft: null } for a foreign user / foreign tenant,
+//     never leaking the other owner's row
+//   - discard only ever removes the caller's own row
+//   - stepIndex + savedAt round-trip through the blob shape fixed by #1889
+//   - list resolves a user's open drafts for a screenId (draftKey prefix
+//     match), never another user's/tenant's rows and never the blob values
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { createConfigFeature } from "../../config";
+import { FormDraftHandlers, FormDraftQueries } from "../constants";
+import { formDraftEntity } from "../entity";
+import { formDraftFeature } from "../feature";
+import type { GetDraftResult } from "../handlers/get.query";
+import type { ListDraftsResult } from "../handlers/list.query";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [formDraftFeature, createConfigFeature()] });
+  await unsafeCreateEntityTable(stack.db, formDraftEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+  await asRawClient(stack.db).unsafe("DELETE FROM read_form_drafts");
+});
+
+// Distinct ids (default createTestUser() shares TestUsers.admin.id).
+const owner = createTestUser({ id: 1, roles: ["TenantMember"] });
+const otherUser = createTestUser({ id: 2, roles: ["TenantMember"] });
+const otherTenant = createTestUser({
+  id: 1,
+  roles: ["TenantMember"],
+  tenantId: "00000000-0000-4000-8000-0000000000aa",
+});
+
+async function saveDraft(
+  draftKey: string,
+  values: Record<string, unknown>,
+  stepIndex: number,
+  user = owner,
+): Promise<unknown> {
+  return stack.http.writeOk(FormDraftHandlers.save, { draftKey, values, stepIndex }, user);
+}
+
+async function getDraft(draftKey: string, user = owner): Promise<GetDraftResult> {
+  return stack.http.queryOk<GetDraftResult>(FormDraftQueries.get, { draftKey }, user);
+}
+
+async function discardDraft(draftKey: string, user = owner): Promise<unknown> {
+  return stack.http.writeOk(FormDraftHandlers.discard, { draftKey }, user);
+}
+
+async function listDrafts(screenId: string, user = owner): Promise<ListDraftsResult> {
+  return stack.http.queryOk<ListDraftsResult>(FormDraftQueries.list, { screenId }, user);
+}
+
+describe("form-draft integration — save + get", () => {
+  test("save then get round-trips values, stepIndex, and a stamped savedAt", async () => {
+    await saveDraft("wizard:vehicle-create", { name: "Van" }, 1);
+    const { draft } = await getDraft("wizard:vehicle-create");
+    expect(draft).not.toBeNull();
+    expect(draft?.values).toEqual({ name: "Van" });
+    expect(draft?.stepIndex).toBe(1);
+    expect(draft?.savedAt).toBeTruthy();
+  });
+
+  test("get resolves { draft: null } when nothing was ever saved", async () => {
+    const { draft } = await getDraft("no-such-draft");
+    expect(draft).toBeNull();
+  });
+
+  test("savedAt is always a fresh server-side stamp, not a client-supplied value", async () => {
+    await stack.http.writeOk(
+      FormDraftHandlers.save,
+      {
+        draftKey: "wizard:x",
+        values: {},
+        stepIndex: 0,
+        savedAt: "1999-01-01T00:00:00Z",
+      },
+      owner,
+    );
+    const { draft } = await getDraft("wizard:x");
+    const savedAtMs = draft?.savedAt ? Date.parse(draft.savedAt) : Number.NaN;
+    expect(Number.isNaN(savedAtMs)).toBe(false);
+    expect(Date.now() - savedAtMs).toBeLessThan(10_000);
+  });
+});
+
+describe("form-draft integration — save is an upsert", () => {
+  test("saving the same draftKey twice updates the row, it never duplicates", async () => {
+    await saveDraft("wizard:vehicle-create", { name: "Van" }, 0);
+    await saveDraft("wizard:vehicle-create", { name: "Van", plate: "B-XY-123" }, 2);
+
+    const { draft } = await getDraft("wizard:vehicle-create");
+    expect(draft?.values).toEqual({ name: "Van", plate: "B-XY-123" });
+    expect(draft?.stepIndex).toBe(2);
+
+    const rows = await asRawClient(stack.db).unsafe(
+      "SELECT count(*)::int AS n FROM read_form_drafts WHERE draft_key = $1",
+      ["wizard:vehicle-create"],
+    );
+    expect((rows as Array<{ n: number }>)[0]?.n).toBe(1);
+  });
+
+  test("two different users saving the same draftKey each get their own draft", async () => {
+    await saveDraft("wizard:shared-key", { name: "Owner's" }, 0, owner);
+    await saveDraft("wizard:shared-key", { name: "Other's" }, 3, otherUser);
+
+    expect((await getDraft("wizard:shared-key", owner)).draft?.values).toEqual({
+      name: "Owner's",
+    });
+    expect((await getDraft("wizard:shared-key", otherUser)).draft?.values).toEqual({
+      name: "Other's",
+    });
+  });
+});
+
+describe("form-draft integration — discard", () => {
+  test("discard removes the draft — a subsequent get resolves null", async () => {
+    await saveDraft("wizard:to-discard", { name: "Gone soon" }, 0);
+    await discardDraft("wizard:to-discard");
+    expect((await getDraft("wizard:to-discard")).draft).toBeNull();
+  });
+
+  test("discarding a draftKey that was never saved is a no-op, not an error", async () => {
+    await discardDraft("wizard:never-saved");
+    expect((await getDraft("wizard:never-saved")).draft).toBeNull();
+  });
+});
+
+describe("form-draft integration — ownership isolation", () => {
+  test("a foreign user's get never sees another user's draft", async () => {
+    await saveDraft("wizard:private", { secret: "only mine" }, 0, owner);
+    expect((await getDraft("wizard:private", otherUser)).draft).toBeNull();
+  });
+
+  test("a foreign user's discard never removes another user's draft", async () => {
+    await saveDraft("wizard:private", { secret: "only mine" }, 0, owner);
+    await discardDraft("wizard:private", otherUser);
+    expect((await getDraft("wizard:private", owner)).draft?.values).toEqual({
+      secret: "only mine",
+    });
+  });
+
+  test("a foreign user's save under the same draftKey creates its own row, never overwrites", async () => {
+    await saveDraft("wizard:private", { secret: "only mine" }, 0, owner);
+    await saveDraft("wizard:private", { secret: "not mine" }, 5, otherUser);
+    expect((await getDraft("wizard:private", owner)).draft?.values).toEqual({
+      secret: "only mine",
+    });
+    expect((await getDraft("wizard:private", otherUser)).draft?.values).toEqual({
+      secret: "not mine",
+    });
+  });
+
+  test("a foreign tenant's get never sees another tenant's draft, even with the same user id", async () => {
+    await saveDraft("wizard:tenant-scoped", { secret: "tenant A" }, 0, owner);
+    expect((await getDraft("wizard:tenant-scoped", otherTenant)).draft).toBeNull();
+    expect((await getDraft("wizard:tenant-scoped", owner)).draft?.values).toEqual({
+      secret: "tenant A",
+    });
+  });
+});
+
+describe("form-draft integration — list", () => {
+  test("list returns open drafts for a screenId, newest first, without the blob's values", async () => {
+    await saveDraft("wizard:a", { name: "First" }, 0);
+    await saveDraft("wizard:b", { name: "Second" }, 1);
+
+    const { drafts } = await listDrafts("wizard");
+    expect(drafts.map((d) => d.draftKey)).toEqual(["wizard:b", "wizard:a"]);
+    expect(drafts[0]?.stepIndex).toBe(1);
+    expect(drafts[0]?.savedAt).toBeTruthy();
+    expect(drafts[0]).not.toHaveProperty("values");
+  });
+
+  test("list excludes a draft whose screenId is only a prefix, not a full segment match", async () => {
+    await saveDraft("wizard:a", {}, 0);
+    await saveDraft("wizardry:x", {}, 0);
+
+    const { drafts } = await listDrafts("wizard");
+    expect(drafts.map((d) => d.draftKey)).toEqual(["wizard:a"]);
+  });
+
+  test("a screenId containing LIKE metacharacters is matched literally, not as a wildcard", async () => {
+    await saveDraft("scr%en:a", {}, 0);
+    await saveDraft("wizard:a", {}, 0);
+
+    const { drafts } = await listDrafts("scr%en");
+    expect(drafts.map((d) => d.draftKey)).toEqual(["scr%en:a"]);
+  });
+
+  test("list resolves an empty array when nothing was ever saved for the screenId", async () => {
+    expect((await listDrafts("no-such-screen")).drafts).toEqual([]);
+  });
+
+  test("list excludes another user's drafts for the same screenId", async () => {
+    await saveDraft("wizard:mine", { secret: "only mine" }, 0, owner);
+    await saveDraft("wizard:theirs", { secret: "not mine" }, 0, otherUser);
+
+    expect((await listDrafts("wizard", owner)).drafts.map((d) => d.draftKey)).toEqual([
+      "wizard:mine",
+    ]);
+    expect((await listDrafts("wizard", otherUser)).drafts.map((d) => d.draftKey)).toEqual([
+      "wizard:theirs",
+    ]);
+  });
+
+  test("list excludes another tenant's drafts, even with the same user id", async () => {
+    await saveDraft("wizard:tenant-a", { secret: "tenant A" }, 0, owner);
+    expect((await listDrafts("wizard", otherTenant)).drafts).toEqual([]);
+  });
+});

package/src/form-draft/changes.json

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

package/src/form-draft/constants.ts

@@ -0,0 +1,31 @@
+// @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: true };
+
+// 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;

package/src/form-draft/db/queries/cleanup.ts

@@ -0,0 +1,50 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { FormDraftBlob } from "../../schemas";
+
+export type StaleDraftRow = {
+  readonly id: string;
+  readonly tenantId: TenantId;
+  readonly ownerId: string;
+  readonly draft: FormDraftBlob;
+};
+
+// 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 by
+// id via deleteDraftsByIds below. 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 asRawClient(db).unsafe(
+    `SELECT "id", "tenant_id", "owner_id", "draft" 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: FormDraftBlob }[];
+  return rows.map((row) => ({
+    id: row.id,
+    tenantId: row.tenant_id as TenantId, // @cast-boundary db-row
+    ownerId: row.owner_id,
+    draft: row.draft,
+  }));
+}
+
+export async function deleteDraftsByIds(db: DbConnection, ids: readonly string[]): Promise<number> {
+  if (ids.length === 0) return 0;
+  const rows = (await asRawClient(db).unsafe(
+    `DELETE FROM "read_form_drafts" WHERE "id" = ANY($1::uuid[]) RETURNING "id"`,
+    [ids],
+  )) as readonly { id: string }[];
+  return rows.length;
+}

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

@@ -0,0 +1,26 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+// 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.
+export async function filterOwnedStorageKeys(
+  db: DbRunner,
+  tenantId: TenantId,
+  ownerId: string,
+  candidateKeys: readonly string[],
+): Promise<readonly string[]> {
+  if (candidateKeys.length === 0) return [];
+  const rows = (await asRawClient(db).unsafe(
+    `SELECT "storage_key" FROM "file_refs"
+     WHERE "tenant_id" = $1 AND "inserted_by_id" = $2
+       AND "storage_key" = ANY($3::text[]) AND "is_deleted" = false`,
+    [tenantId, ownerId, candidateKeys],
+  )) as readonly { storage_key: string }[];
+  return rows.map((row) => row.storage_key);
+}

package/src/form-draft/entity.ts

@@ -0,0 +1,51 @@
+import {
+  createEntity,
+  createJsonbField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { FORM_DRAFT_KEY_MAX_LENGTH, FORM_DRAFT_UNIQUE_KEY_CONSTRAINT } from "./constants";
+
+// form-draft — a per-user, pre-submission working copy of an in-progress
+// form (e.g. a wizard-mode EditLayout). `draftKey` is caller-assigned
+// (typically screenId + optional hostEntityId) and scoped to
+// (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
+// 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.
+export const formDraftEntity = createEntity({
+  table: "read_form_drafts",
+  fields: {
+    // Never client-supplied — stamped from event.user.id (see handlers), so
+    // a draft can't be saved/read/discarded as someone else. subjectRef
+    // feeds the GDPR-hook-coverage boot guard (it's a plain FK into `user`,
+    // not content of its own) — see ../form-draft-user-data for the
+    // required export/delete hook coverage.
+    ownerId: createTextField({ subjectRef: true }),
+    draftKey: createTextField({ required: true, maxLength: FORM_DRAFT_KEY_MAX_LENGTH }),
+    // The blob shape is fixed by issue #1889, 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. NOT annotated
+    // `userOwned` — the framework's PII field-encryption engine only
+    // accepts string values (pii-field-encryption.ts throws on a non-string
+    // field), and this is a jsonb object. Erasure instead runs as a real
+    // physical row-delete on forget (see form-draft-user-data/hooks.ts),
+    // not crypto-shredding; `ownerId`'s `subjectRef` annotation alone
+    // already satisfies the GDPR-hook-coverage boot guard.
+    draft: createJsonbField(),
+  },
+  // One draft per (tenant, owner, draftKey) — save() is an upsert keyed on
+  // this index (see handlers/save.write.ts); a resume query must find at
+  // most one row.
+  indexes: [
+    {
+      columns: ["tenantId", "ownerId", "draftKey"],
+      unique: true,
+      name: FORM_DRAFT_UNIQUE_KEY_CONSTRAINT,
+    },
+  ],
+});

package/src/form-draft/executor.ts

@@ -0,0 +1,7 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { formDraftEntity } from "./entity";
+
+export const { executor: formDraftExecutor, table: formDraftTable } = createEntityExecutor(
+  "form-draft",
+  formDraftEntity,
+);

package/src/form-draft/feature.ts

@@ -0,0 +1,42 @@
+// 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.
+
+import { defineFeature, type FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import { FORM_DRAFT_FEATURE_NAME } from "./constants";
+import { formDraftEntity } from "./entity";
+import { cleanupDraftsJob, formDraftRetentionDaysConfig } from "./handlers/cleanup.job";
+import { discardDraftWrite } from "./handlers/discard.write";
+import { getDraftQuery } from "./handlers/get.query";
+import { listDraftsQuery } from "./handlers/list.query";
+import { saveDraftWrite } from "./handlers/save.write";
+import { FORM_DRAFT_FEATURE_I18N } from "./i18n";
+
+function registerFormDraft(r: FeatureRegistrar<typeof FORM_DRAFT_FEATURE_NAME>): void {
+  r.describe(
+    "Per-user, per-tenant working copy of an in-progress form, saved BEFORE the real domain entity exists. Owns one event-sourced entity, `form-draft` (`read_form_drafts`), keyed by a caller-assigned draftKey (typically screenId + optional hostEntityId), unique per (tenant, owner, draftKey). `save` upserts the draft blob ({ values, stepIndex, savedAt } — savedAt stamped server-side), `discard` deletes it (called once the real submit succeeds), `get` resumes it, `list` finds a user's open drafts for a given screenId (draftKey prefix match) — the fallback when a client-generated draftId is lost. Ownership is enforced by a per-row owner filter in every handler, not by roles — a foreign user's save/discard/get/list for someone else's draftKey never sees or touches that row. Never holds anything that already lives in a domain stream; the consuming app is responsible for discarding once the domain write succeeds. A daily cron job hard-deletes drafts past a configurable retention window (`form-draft:config:retention-days`, SystemAdmin-writable, default 30 days).",
+  );
+  r.uiHints({
+    displayLabel: "Form Drafts",
+    category: "data",
+    recommended: false,
+  });
+
+  r.requires("config");
+  r.entity("form-draft", formDraftEntity);
+
+  r.writeHandler(saveDraftWrite);
+  r.writeHandler(discardDraftWrite);
+  r.queryHandler(getDraftQuery);
+  r.queryHandler(listDraftsQuery);
+
+  r.config({ keys: { retentionDays: formDraftRetentionDaysConfig } });
+  r.job("cleanup", { trigger: { cron: "0 3 * * *" }, concurrency: "skip" }, cleanupDraftsJob);
+
+  r.translations({ keys: FORM_DRAFT_FEATURE_I18N });
+}
+
+export const formDraftFeature = defineFeature(FORM_DRAFT_FEATURE_NAME, registerFormDraft);

package/src/form-draft/handlers/cleanup.job.ts

@@ -0,0 +1,120 @@
+// form-draft cleanup — hard-deletes drafts whose last save is older than a
+// configurable retention window (system-wide, one value for the whole
+// deployment — form-draft drafts are ephemeral scratch state, not a
+// per-tenant compliance policy like data-retention). No perTenant fan-out:
+// a single cron run reads the one config value and sweeps the whole table.
+// Chunked DELETE (default 1000/batch) keeps lock durations bounded, mirror
+// of sessions/handlers/cleanup.job.ts.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type AppContext,
+  access,
+  type ConfigKeyDefinition,
+  createSystemConfig,
+  type JobHandlerFn,
+  SYSTEM_TENANT_ID,
+  SYSTEM_USER_ID,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  deleteDraftsByIds,
+  type StaleDraftRow,
+  selectStaleDraftsBatch,
+} from "../db/queries/cleanup";
+import { filterOwnedStorageKeys } from "../db/queries/owned-file-refs";
+import { collectDraftFileRefKeys, releaseDraftFileRefs } from "../release-file-refs";
+
+export const FORM_DRAFT_RETENTION_DAYS_CONFIG_KEY = "form-draft:config:retention-days";
+export const FORM_DRAFT_DEFAULT_RETENTION_DAYS = 30;
+const DEFAULT_BATCH_SIZE = 1000;
+
+export const formDraftRetentionDaysConfig: ConfigKeyDefinition<"number"> = createSystemConfig(
+  "number",
+  {
+    default: FORM_DRAFT_DEFAULT_RETENTION_DAYS,
+    bounds: { min: 1 },
+    write: access.systemAdmin,
+    read: access.admin,
+  },
+);
+
+async function releaseRowFileRefs(
+  row: StaleDraftRow,
+  db: DbConnection,
+  fileProviderResolver: AppContext["_fileProviderResolver"],
+  log: AppContext["log"],
+): Promise<void> {
+  const keys = collectDraftFileRefKeys(row.draft);
+  // skip: no FileRefs in this row's blob — nothing to release.
+  if (keys.length === 0) return;
+  if (!fileProviderResolver) {
+    // skip: no resolver wired (files feature not mounted) — row still
+    // gets deleted below, but its FileRefs leak as storage orphans.
+    log?.warn?.(
+      `[form-draft:cleanup] tenant=${row.tenantId} has ${keys.length} FileRef(s) but no _fileProviderResolver is wired — row will be deleted without releasing storage`,
+    );
+    // skip: warning already logged above — nothing more to do for this row.
+    return;
+  }
+
+  try {
+    // Only storageKeys with a real file_refs row owned by this row's
+    // draft owner are releasable — `draft.values` is free-form JSON the
+    // owning user controls, so an unverified key could target someone
+    // else's file (see db/queries/owned-file-refs.ts).
+    const ownedKeys = await filterOwnedStorageKeys(db, row.tenantId, row.ownerId, keys);
+    const provider = await fileProviderResolver(row.tenantId);
+    await releaseDraftFileRefs(ownedKeys, (key) => provider.delete(key), log);
+  } catch (err) {
+    log?.warn?.(
+      `[form-draft:cleanup] no file provider resolvable for tenant=${row.tenantId} — FileRefs NOT released (row still deleted): ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export const cleanupDraftsJob: JobHandlerFn = async (_payload, ctx) => {
+  if (!ctx.db || !ctx.registry) {
+    throw new InternalError({
+      message: "[form-draft:cleanup] ctx.db + ctx.registry required (JobContext incomplete)",
+    });
+  }
+  const db = ctx.db as DbConnection;
+
+  const resolved = ctx.configResolver
+    ? await ctx.configResolver.get(
+        FORM_DRAFT_RETENTION_DAYS_CONFIG_KEY,
+        formDraftRetentionDaysConfig,
+        SYSTEM_TENANT_ID,
+        SYSTEM_USER_ID,
+        db,
+      )
+    : undefined;
+  const retentionDays =
+    typeof resolved === "number" && resolved >= 1 ? resolved : FORM_DRAFT_DEFAULT_RETENTION_DAYS;
+
+  const fileProviderResolver = ctx._fileProviderResolver;
+
+  let deleted = 0;
+  while (true) {
+    const batch = await selectStaleDraftsBatch(db, retentionDays, DEFAULT_BATCH_SIZE);
+    if (batch.length === 0) break;
+
+    // Rows span arbitrary tenants (this job sweeps the whole table under
+    // SYSTEM_TENANT_ID, not per-tenant) — ctx.files is resolved for a single
+    // tenant per job run and would be wrong here, so each row resolves its
+    // own tenant's provider via _fileProviderResolver instead. Skipped
+    // entirely for rows with no FileRefs in the blob, the common case.
+    for (const row of batch) {
+      await releaseRowFileRefs(row, db, fileProviderResolver, ctx.log);
+    }
+
+    const batchDeleted = await deleteDraftsByIds(
+      db,
+      batch.map((row) => row.id),
+    );
+    deleted += batchDeleted;
+    if (batchDeleted === 0 || batch.length < DEFAULT_BATCH_SIZE) break;
+  }
+  ctx.log?.info?.(`[form-draft:cleanup] deleted=${deleted} retentionDays=${retentionDays}`);
+};

package/src/form-draft/handlers/discard.write.ts

@@ -0,0 +1,55 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { FORM_DRAFT_ACCESS } from "../constants";
+import { filterOwnedStorageKeys } from "../db/queries/owned-file-refs";
+import { formDraftExecutor } from "../executor";
+import { lookupDraft } from "../lookup";
+import { collectDraftFileRefKeys, releaseDraftFileRefs } from "../release-file-refs";
+import { discardDraftPayloadSchema } from "../schemas";
+
+// discard — the caller's own draft only. Ownership is enforced by the
+// lookup predicate (tenantId + ownerId + draftKey), not by a separate
+// permission check: a foreign user's discard call for someone else's
+// draftKey finds no row and no-ops (isSuccess, nothing deleted) rather than
+// erroring — same "own rows only, silently absent otherwise" shape as
+// personal-access-tokens' revoke.
+export const discardDraftWrite = defineWriteHandler({
+  name: "discard",
+  schema: discardDraftPayloadSchema,
+  access: FORM_DRAFT_ACCESS,
+  handler: async (event, ctx) => {
+    const ownerId = event.user.id;
+    const existing = await lookupDraft(
+      ctx.db,
+      event.user.tenantId,
+      ownerId,
+      event.payload.draftKey,
+    );
+    if (!existing) {
+      return { isSuccess: true as const, data: { discarded: false } };
+    }
+    const result = await formDraftExecutor.delete({ id: existing.id }, event.user, ctx.db);
+    if (!result.isSuccess) return result;
+    // Release AFTER the row delete succeeds — a version-conflict/failed
+    // delete leaves the draft (and its FileRefs) intact rather than
+    // orphaning a photo behind a draft that's still there. Gated on
+    // releaseFiles: a successful-submit discard must NOT release — the
+    // domain entity the submit just wrote carries the same storageKeys
+    // forward (see schemas.ts comment on discardDraftPayloadSchema).
+    const files = ctx.files;
+    if (files && event.payload.releaseFiles === true) {
+      const candidateKeys = collectDraftFileRefKeys(existing.draft);
+      // Only storageKeys with a real file_refs row owned by THIS caller are
+      // releasable — `values` is free-form JSON the caller controls, so an
+      // unverified key could target someone else's file (see
+      // db/queries/owned-file-refs.ts).
+      const ownedKeys = await filterOwnedStorageKeys(
+        ctx.db.raw,
+        event.user.tenantId,
+        ownerId,
+        candidateKeys,
+      );
+      await releaseDraftFileRefs(ownedKeys, (key) => files.ref(key).delete(), ctx.log);
+    }
+    return { isSuccess: true as const, data: { discarded: true } };
+  },
+});

package/src/form-draft/handlers/get.query.ts

@@ -0,0 +1,26 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { FORM_DRAFT_ACCESS } from "../constants";
+import { lookupDraft } from "../lookup";
+import type { FormDraftBlob } from "../schemas";
+import { getDraftPayloadSchema } from "../schemas";
+
+export type GetDraftResult = { readonly draft: FormDraftBlob | null };
+
+// get — resolves to `{ draft: null }` for both "no draft saved yet" and "a
+// draft exists but belongs to someone else / another tenant" — the lookup
+// is scoped by (tenantId, ownerId, draftKey), so a foreign caller's query
+// never surfaces another user's row, it just looks like no draft exists.
+export const getDraftQuery = defineQueryHandler({
+  name: "get",
+  schema: getDraftPayloadSchema,
+  access: FORM_DRAFT_ACCESS,
+  handler: async (query, ctx): Promise<GetDraftResult> => {
+    const row = await lookupDraft(
+      ctx.db,
+      query.user.tenantId,
+      query.user.id,
+      query.payload.draftKey,
+    );
+    return { draft: row?.draft ?? null };
+  },
+});