@opengeni/api-router 0.5.3 → 0.5.4

package/src/routes/environments.ts

@@ -1,175 +1,244 @@
 import {
-  CreateWorkspaceEnvironmentRequest,
-  SetWorkspaceEnvironmentVariableRequest,
-  UpdateWorkspaceEnvironmentRequest,
-  WorkspaceEnvironmentVariableName,
+  CreateVariableSetRequest,
+  SetVariableSetVariableRequest,
+  UpdateVariableSetRequest,
+  VariableSetVariableName,
 } from "@opengeni/contracts";
 import {
-  countActiveSessionsUsingEnvironment,
-  countScheduledTasksUsingEnvironment,
-  countWorkspaceEnvironments,
-  createWorkspaceEnvironment,
-  deleteWorkspaceEnvironment,
-  deleteWorkspaceEnvironmentVariable,
-  encryptEnvironmentValue,
-  getWorkspaceEnvironmentByName,
-  listWorkspaceEnvironments,
-  setWorkspaceEnvironmentVariable,
-  updateWorkspaceEnvironment,
+  countActiveSessionsUsingVariableSet,
+  countScheduledTasksUsingVariableSet,
+  countVariableSets,
+  createVariableSet,
+  deleteVariableSet,
+  deleteVariableSetVariable,
+  encryptVariableSetValue,
+  getVariableSetByName,
+  listVariableSets,
+  setVariableSetVariable,
+  updateVariableSet,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { requireAccessGrant } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
-  assertAllowedEnvironmentVariableName,
+  assertAllowedVariableSetVariableName,
   MAX_ENVIRONMENTS_PER_WORKSPACE,
   MAX_VARIABLES_PER_ENVIRONMENT,
-  recordEnvironmentAuditEvent,
-  requireEnvironmentEncryption,
-  requireEnvironmentForApi,
+  recordVariableSetAuditEvent,
+  requireVariableSetEncryption,
+  requireVariableSetForApi,
 } from "@opengeni/core";
 
-export function registerEnvironmentRoutes(app: Hono, deps: ApiRouteDeps): void {
+export function registerVariableSetRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { settings, db } = deps;
+  const prefixes = [
+    "/v1/workspaces/:workspaceId/variable-sets",
+    "/v1/workspaces/:workspaceId/environments",
+  ];
 
-  app.get("/v1/workspaces/:workspaceId/environments", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "environments:use");
-    return c.json(await listWorkspaceEnvironments(db, workspaceId));
-  });
+  for (const prefix of prefixes) {
+    app.get(`${prefix}`, async (c) => {
+      const workspaceId = c.req.param("workspaceId")!;
+      await requireAccessGrant(c, deps, workspaceId, "variable-sets:use");
+      return c.json(await listVariableSets(db, workspaceId));
+    });
 
-  app.post("/v1/workspaces/:workspaceId/environments", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
-    const key = requireEnvironmentEncryption(settings);
-    const payload = CreateWorkspaceEnvironmentRequest.parse(await c.req.json());
-    const name = trimmedEnvironmentName(payload.name);
-    if (payload.variables.length > MAX_VARIABLES_PER_ENVIRONMENT) {
-      throw new HTTPException(422, { message: `an environment supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables` });
-    }
-    const variableNames = new Set<string>();
-    for (const variable of payload.variables) {
-      assertAllowedEnvironmentVariableName(variable.name);
-      if (variableNames.has(variable.name)) {
-        throw new HTTPException(422, { message: `duplicate environment variable name: ${variable.name}` });
+    app.post(`${prefix}`, async (c) => {
+      const workspaceId = c.req.param("workspaceId")!;
+      const grant = await requireAccessGrant(c, deps, workspaceId, "variable-sets:manage");
+      const key = requireVariableSetEncryption(settings);
+      const payload = CreateVariableSetRequest.parse(await c.req.json());
+      const name = trimmedVariableSetName(payload.name);
+      if (payload.variables.length > MAX_VARIABLES_PER_ENVIRONMENT) {
+        throw new HTTPException(422, {
+          message: `a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables`,
+        });
+      }
+      const variableNames = new Set<string>();
+      for (const variable of payload.variables) {
+        assertAllowedVariableSetVariableName(variable.name);
+        if (variableNames.has(variable.name)) {
+          throw new HTTPException(422, {
+            message: `duplicate variable set variable name: ${variable.name}`,
+          });
+        }
+        variableNames.add(variable.name);
+      }
+      if ((await countVariableSets(db, workspaceId)) >= MAX_ENVIRONMENTS_PER_WORKSPACE) {
+        throw new HTTPException(422, {
+          message: `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE} variable sets`,
+        });
+      }
+      if (await getVariableSetByName(db, workspaceId, name)) {
+        throw new HTTPException(409, { message: `variable set name is already in use: ${name}` });
       }
-      variableNames.add(variable.name);
-    }
-    if (await countWorkspaceEnvironments(db, workspaceId) >= MAX_ENVIRONMENTS_PER_WORKSPACE) {
-      throw new HTTPException(422, { message: `a workspace supports at most ${MAX_ENVIRONMENTS_PER_WORKSPACE} environments` });
-    }
-    if (await getWorkspaceEnvironmentByName(db, workspaceId, name)) {
-      throw new HTTPException(409, { message: `environment name is already in use: ${name}` });
-    }
-    // Values are encrypted up front and the environment plus all initial
-    // variables are written in one transaction: a failure leaves nothing.
-    const created = await createWorkspaceEnvironment(db, {
-      accountId: grant.accountId,
-      workspaceId,
-      name,
-      description: payload.description ?? null,
-      variables: payload.variables.map((variable) => ({
-        name: variable.name,
-        valueEncrypted: encryptEnvironmentValue(key, variable.value),
-      })),
+      // Values are encrypted up front and the variableSet plus all initial
+      // variables are written in one transaction: a failure leaves nothing.
+      const created = await createVariableSet(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        name,
+        description: payload.description ?? null,
+        variables: payload.variables.map((variable) => ({
+          name: variable.name,
+          valueEncrypted: encryptVariableSetValue(key, variable.value),
+        })),
+      });
+      await recordVariableSetAuditEvent(db, {
+        grant,
+        action: "variable_set.created",
+        variableSetId: created.id,
+      });
+      return c.json(created, 201);
     });
-    await recordEnvironmentAuditEvent(db, { grant, action: "environment.created", environmentId: created.id });
-    return c.json(created, 201);
-  });
 
-  app.get("/v1/workspaces/:workspaceId/environments/:environmentId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "environments:use");
-    return c.json(await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId")));
-  });
+    app.get(`${prefix}/:variableSetId`, async (c) => {
+      const workspaceId = c.req.param("workspaceId")!;
+      await requireAccessGrant(c, deps, workspaceId, "variable-sets:use");
+      return c.json(await requireVariableSetForApi(db, workspaceId, c.req.param("variableSetId")!));
+    });
 
-  app.patch("/v1/workspaces/:workspaceId/environments/:environmentId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
-    const environment = await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId"));
-    const payload = UpdateWorkspaceEnvironmentRequest.parse(await c.req.json());
-    const name = payload.name !== undefined ? trimmedEnvironmentName(payload.name) : undefined;
-    if (name !== undefined && name !== environment.name) {
-      const existing = await getWorkspaceEnvironmentByName(db, workspaceId, name);
-      if (existing && existing.id !== environment.id) {
-        throw new HTTPException(409, { message: `environment name is already in use: ${name}` });
+    app.patch(`${prefix}/:variableSetId`, async (c) => {
+      const workspaceId = c.req.param("workspaceId")!;
+      const grant = await requireAccessGrant(c, deps, workspaceId, "variable-sets:manage");
+      const variableSet = await requireVariableSetForApi(
+        db,
+        workspaceId,
+        c.req.param("variableSetId")!,
+      );
+      const payload = UpdateVariableSetRequest.parse(await c.req.json());
+      const name = payload.name !== undefined ? trimmedVariableSetName(payload.name) : undefined;
+      if (name !== undefined && name !== variableSet.name) {
+        const existing = await getVariableSetByName(db, workspaceId, name);
+        if (existing && existing.id !== variableSet.id) {
+          throw new HTTPException(409, { message: `variable set name is already in use: ${name}` });
+        }
       }
-    }
-    const updated = await updateWorkspaceEnvironment(db, workspaceId, environment.id, {
-      ...(name !== undefined ? { name } : {}),
-      ...(payload.description !== undefined ? { description: payload.description } : {}),
+      const updated = await updateVariableSet(db, workspaceId, variableSet.id, {
+        ...(name !== undefined ? { name } : {}),
+        ...(payload.description !== undefined ? { description: payload.description } : {}),
+      });
+      await recordVariableSetAuditEvent(db, {
+        grant,
+        action: "variable_set.updated",
+        variableSetId: variableSet.id,
+      });
+      return c.json(updated);
     });
-    await recordEnvironmentAuditEvent(db, { grant, action: "environment.updated", environmentId: environment.id });
-    return c.json(updated);
-  });
 
-  app.delete("/v1/workspaces/:workspaceId/environments/:environmentId", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
-    const environment = await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId"));
-    const attachedTasks = await countScheduledTasksUsingEnvironment(db, workspaceId, environment.id);
-    if (attachedTasks > 0) {
-      throw new HTTPException(409, { message: `environment is attached to ${attachedTasks} scheduled task(s); detach first` });
-    }
-    const activeSessions = await countActiveSessionsUsingEnvironment(db, workspaceId, environment.id);
-    if (activeSessions > 0) {
-      throw new HTTPException(409, { message: `environment is attached to ${activeSessions} active session(s); wait for them to finish or cancel them first` });
-    }
-    await deleteWorkspaceEnvironment(db, workspaceId, environment.id);
-    await recordEnvironmentAuditEvent(db, { grant, action: "environment.deleted", environmentId: environment.id });
-    return c.json({ ok: true });
-  });
+    app.delete(`${prefix}/:variableSetId`, async (c) => {
+      const workspaceId = c.req.param("workspaceId")!;
+      const grant = await requireAccessGrant(c, deps, workspaceId, "variable-sets:manage");
+      const variableSet = await requireVariableSetForApi(
+        db,
+        workspaceId,
+        c.req.param("variableSetId")!,
+      );
+      const attachedTasks = await countScheduledTasksUsingVariableSet(
+        db,
+        workspaceId,
+        variableSet.id,
+      );
+      if (attachedTasks > 0) {
+        throw new HTTPException(409, {
+          message: `variable set is attached to ${attachedTasks} scheduled task(s); detach first`,
+        });
+      }
+      const activeSessions = await countActiveSessionsUsingVariableSet(
+        db,
+        workspaceId,
+        variableSet.id,
+      );
+      if (activeSessions > 0) {
+        throw new HTTPException(409, {
+          message: `variable set is attached to ${activeSessions} active session(s); wait for them to finish or cancel them first`,
+        });
+      }
+      await deleteVariableSet(db, workspaceId, variableSet.id);
+      await recordVariableSetAuditEvent(db, {
+        grant,
+        action: "variable_set.deleted",
+        variableSetId: variableSet.id,
+      });
+      return c.json({ ok: true });
+    });
 
-  app.put("/v1/workspaces/:workspaceId/environments/:environmentId/variables/:name", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
-    const key = requireEnvironmentEncryption(settings);
-    const name = parseVariableName(c.req.param("name"));
-    const environment = await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId"));
-    const payload = SetWorkspaceEnvironmentVariableRequest.parse(await c.req.json());
-    const exists = environment.variables.some((variable) => variable.name === name);
-    if (!exists && environment.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT) {
-      throw new HTTPException(422, { message: `an environment supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables` });
-    }
-    const metadata = await setWorkspaceEnvironmentVariable(db, {
-      accountId: grant.accountId,
-      workspaceId,
-      environmentId: environment.id,
-      name,
-      valueEncrypted: encryptEnvironmentValue(key, payload.value),
+    app.put(`${prefix}/:variableSetId/variables/:name`, async (c) => {
+      const workspaceId = c.req.param("workspaceId")!;
+      const grant = await requireAccessGrant(c, deps, workspaceId, "variable-sets:manage");
+      const key = requireVariableSetEncryption(settings);
+      const name = parseVariableName(c.req.param("name")!);
+      const variableSet = await requireVariableSetForApi(
+        db,
+        workspaceId,
+        c.req.param("variableSetId")!,
+      );
+      const payload = SetVariableSetVariableRequest.parse(await c.req.json());
+      const exists = variableSet.variables.some((variable) => variable.name === name);
+      if (!exists && variableSet.variables.length >= MAX_VARIABLES_PER_ENVIRONMENT) {
+        throw new HTTPException(422, {
+          message: `a variable set supports at most ${MAX_VARIABLES_PER_ENVIRONMENT} variables`,
+        });
+      }
+      const metadata = await setVariableSetVariable(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        variableSetId: variableSet.id,
+        name,
+        valueEncrypted: encryptVariableSetValue(key, payload.value),
+      });
+      await recordVariableSetAuditEvent(db, {
+        grant,
+        action: "variable_set.variable.set",
+        variableSetId: variableSet.id,
+        variableName: name,
+      });
+      return c.json(metadata);
     });
-    await recordEnvironmentAuditEvent(db, { grant, action: "environment.variable.set", environmentId: environment.id, variableName: name });
-    return c.json(metadata);
-  });
 
-  app.delete("/v1/workspaces/:workspaceId/environments/:environmentId/variables/:name", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "environments:manage");
-    const name = parseVariableName(c.req.param("name"));
-    const environment = await requireEnvironmentForApi(db, workspaceId, c.req.param("environmentId"));
-    const deleted = await deleteWorkspaceEnvironmentVariable(db, workspaceId, environment.id, name);
-    if (!deleted) {
-      throw new HTTPException(404, { message: "environment variable not found" });
-    }
-    await recordEnvironmentAuditEvent(db, { grant, action: "environment.variable.deleted", environmentId: environment.id, variableName: name });
-    return c.json({ ok: true });
-  });
+    app.delete(`${prefix}/:variableSetId/variables/:name`, async (c) => {
+      const workspaceId = c.req.param("workspaceId")!;
+      const grant = await requireAccessGrant(c, deps, workspaceId, "variable-sets:manage");
+      const name = parseVariableName(c.req.param("name")!);
+      const variableSet = await requireVariableSetForApi(
+        db,
+        workspaceId,
+        c.req.param("variableSetId")!,
+      );
+      const deleted = await deleteVariableSetVariable(db, workspaceId, variableSet.id, name);
+      if (!deleted) {
+        throw new HTTPException(404, { message: "variable set variable not found" });
+      }
+      await recordVariableSetAuditEvent(db, {
+        grant,
+        action: "variable_set.variable.deleted",
+        variableSetId: variableSet.id,
+        variableName: name,
+      });
+      return c.json({ ok: true });
+    });
+  }
 }
 
+/** @deprecated use registerVariableSetRoutes */
+export const registerEnvironmentRoutes = registerVariableSetRoutes;
+
 function parseVariableName(raw: string): string {
-  const parsed = WorkspaceEnvironmentVariableName.safeParse(raw);
+  const parsed = VariableSetVariableName.safeParse(raw);
   if (!parsed.success) {
-    throw new HTTPException(422, { message: "environment variable names must match ^[A-Z][A-Z0-9_]*$" });
+    throw new HTTPException(422, {
+      message: "variable set variable names must match ^[A-Z][A-Z0-9_]*$",
+    });
   }
-  assertAllowedEnvironmentVariableName(parsed.data);
+  assertAllowedVariableSetVariableName(parsed.data);
   return parsed.data;
 }
 
-function trimmedEnvironmentName(name: string): string {
+function trimmedVariableSetName(name: string): string {
   const trimmed = name.trim();
   if (!trimmed) {
-    throw new HTTPException(422, { message: "environment name is required" });
+    throw new HTTPException(422, { message: "variable set name is required" });
   }
   return trimmed;
 }

package/src/routes/files.ts

@@ -6,10 +6,11 @@ import {
   FileDownloadUrlResponse,
 } from "@opengeni/contracts";
 import {
+  claimFileUploadCleanup,
+  completeFileUploadCleanup,
   completeFileUpload,
   createFileUpload,
   getFileUpload,
-  markFileUploadFailed,
   requireFile,
 } from "@opengeni/db";
 import type { Hono } from "hono";
@@ -28,9 +29,16 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(503, { message: "object storage is not configured" });
     }
     const payload = CreateFileUploadRequest.parse(await c.req.json());
-    await requireLimit(deps, { accountId: grant.accountId, workspaceId, action: "file:upload", quantity: payload.sizeBytes });
+    await requireLimit(deps, {
+      accountId: grant.accountId,
+      workspaceId,
+      action: "file:upload",
+      quantity: payload.sizeBytes,
+    });
     if (payload.sizeBytes > objectStorage.maxSinglePutSizeBytes) {
-      throw new HTTPException(413, { message: `file exceeds single PUT limit of ${objectStorage.maxSinglePutSizeBytes} bytes` });
+      throw new HTTPException(413, {
+        message: `file exceeds single PUT limit of ${objectStorage.maxSinglePutSizeBytes} bytes`,
+      });
     }
     const fileId = crypto.randomUUID();
     const safeFilename = sanitizeFilename(payload.filename);
@@ -53,14 +61,17 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       objectKey,
       expiresAt: signed.expiresAt,
     });
-    return c.json(CreateFileUploadResponse.parse({
-      fileId: upload.file.id,
-      uploadId: upload.uploadId,
-      putUrl: signed.url,
-      requiredHeaders: signed.requiredHeaders,
-      expiresAt: upload.expiresAt,
-      maxSizeBytes: objectStorage.maxSinglePutSizeBytes,
-    }), 201);
+    return c.json(
+      CreateFileUploadResponse.parse({
+        fileId: upload.file.id,
+        uploadId: upload.uploadId,
+        putUrl: signed.url,
+        requiredHeaders: signed.requiredHeaders,
+        expiresAt: upload.expiresAt,
+        maxSizeBytes: objectStorage.maxSinglePutSizeBytes,
+      }),
+      201,
+    );
   });
 
   app.post("/v1/workspaces/:workspaceId/files/uploads/:uploadId/complete", async (c) => {
@@ -73,40 +84,144 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!upload) {
       throw new HTTPException(404, { message: "file upload not found" });
     }
+    const recordUploadedFileUsage = async (file: typeof upload.file): Promise<void> => {
+      await recordWorkspaceUsage(deps, {
+        accountId: grant.accountId,
+        workspaceId,
+        subjectId: grant.subjectId,
+        eventType: "file.uploaded",
+        quantity: file.sizeBytes,
+        unit: "byte",
+        sourceResourceType: "file",
+        sourceResourceId: file.id,
+        idempotencyKey: `file.uploaded:${workspaceId}:${file.id}`,
+      });
+    };
+    const completeAndRecordUsage = async (): Promise<typeof upload.file> => {
+      let file: typeof upload.file;
+      try {
+        file = await completeFileUpload(db, workspaceId, upload.id);
+      } catch (error) {
+        // HEAD runs outside the DB transaction. If the expiry reaper claims the
+        // row in that window, report the durable state instead of leaking an
+        // internal 500. A concurrent successful finalize remains a normal
+        // idempotent completion and still repairs usage below.
+        const current = await getFileUpload(db, workspaceId, upload.id);
+        if (current?.status === "completed" && current.file.status === "ready") {
+          file = current.file;
+        } else if (current && current.status !== "pending") {
+          throw new HTTPException(409, {
+            message: `file upload is ${publicFileUploadStatus(current.status)}`,
+          });
+        } else {
+          throw error;
+        }
+      }
+      await recordUploadedFileUsage(file);
+      return file;
+    };
+    const rejectAndCleanObject = async (
+      status: 409 | 422,
+      message: string,
+      terminalStatus: "failed" | "expired",
+    ): Promise<typeof upload.file> => {
+      const claim = await claimFileUploadCleanup(db, {
+        workspaceId,
+        uploadId: upload.id,
+        fileId: upload.file.id,
+      });
+      // A concurrent valid finalize may have committed while this request was
+      // checking expiry/provider metadata. Never delete that ready object's
+      // key; preserve normal idempotent finalize and repair usage instead.
+      if (claim.outcome === "completed") {
+        await recordUploadedFileUsage(claim.file);
+        return claim.file;
+      }
+      if (claim.outcome === "unavailable") {
+        throw new HTTPException(409, {
+          message: `file upload is ${publicFileUploadStatus(claim.status)}`,
+        });
+      }
+      try {
+        await objectStorage.deleteObject(upload.file.objectKey);
+      } catch (error) {
+        // The row remains cleanup_pending and the file non-ready. The global
+        // reaper can reclaim the idempotent delete after its claim timeout.
+        deps.observability?.warn(
+          "file upload rejection cleanup failed; claim remains reclaimable",
+          {
+            workspaceId,
+            fileId: upload.file.id,
+            uploadId: upload.id,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        );
+        throw new HTTPException(status, { message });
+      }
+      const settled = await completeFileUploadCleanup(db, {
+        accountId: grant.accountId,
+        workspaceId,
+        uploadId: upload.id,
+        fileId: upload.file.id,
+        terminalStatus,
+      });
+      if (!settled) {
+        throw new HTTPException(409, { message: "file upload cleanup claim was superseded" });
+      }
+      throw new HTTPException(status, { message });
+    };
+    // A client can lose the response after the server commits completion, or two
+    // tabs can race the same completion request. A ready object is durable and
+    // safe to return again. Re-enter the row-locked DB finalize and retry the
+    // idempotent usage write before returning: the previous request may have
+    // died after completion committed but before `file.uploaded` was recorded.
+    if (upload.status === "completed" && upload.file.status === "ready") {
+      const file = await completeAndRecordUsage();
+      return c.json(CompleteFileUploadResponse.parse({ file }));
+    }
     if (upload.status !== "pending") {
-      throw new HTTPException(409, { message: `file upload is ${upload.status}` });
+      throw new HTTPException(409, {
+        message: `file upload is ${publicFileUploadStatus(upload.status)}`,
+      });
     }
     if (upload.expiresAt.getTime() < Date.now()) {
-      await markFileUploadFailed(db, workspaceId, upload.id, upload.file.id);
-      throw new HTTPException(409, { message: "file upload has expired" });
+      const file = await rejectAndCleanObject(409, "file upload has expired", "expired");
+      return c.json(CompleteFileUploadResponse.parse({ file }));
     }
     const head = await objectStorage.headFile(upload.file).catch((error) => {
-      throw new HTTPException(409, { message: `uploaded object is not available: ${error instanceof Error ? error.message : String(error)}` });
+      throw new HTTPException(409, {
+        message: `uploaded object is not available: ${error instanceof Error ? error.message : String(error)}`,
+      });
     });
     if (Number(head.ContentLength ?? -1) !== upload.file.sizeBytes) {
-      await markFileUploadFailed(db, workspaceId, upload.id, upload.file.id);
-      throw new HTTPException(422, { message: "uploaded object size does not match file metadata" });
+      const file = await rejectAndCleanObject(
+        422,
+        "uploaded object size does not match file metadata",
+        "failed",
+      );
+      return c.json(CompleteFileUploadResponse.parse({ file }));
     }
-    if (upload.file.contentType && head.ContentType && head.ContentType !== upload.file.contentType) {
-      await markFileUploadFailed(db, workspaceId, upload.id, upload.file.id);
-      throw new HTTPException(422, { message: "uploaded object content type does not match file metadata" });
+    if (
+      upload.file.contentType &&
+      head.ContentType &&
+      head.ContentType !== upload.file.contentType
+    ) {
+      const file = await rejectAndCleanObject(
+        422,
+        "uploaded object content type does not match file metadata",
+        "failed",
+      );
+      return c.json(CompleteFileUploadResponse.parse({ file }));
     }
     if (upload.file.sha256 && head.Metadata?.sha256 !== upload.file.sha256) {
-      await markFileUploadFailed(db, workspaceId, upload.id, upload.file.id);
-      throw new HTTPException(422, { message: "uploaded object checksum metadata does not match file metadata" });
+      const file = await rejectAndCleanObject(
+        422,
+        "uploaded object checksum metadata does not match file metadata",
+        "failed",
+      );
+      return c.json(CompleteFileUploadResponse.parse({ file }));
     }
-    const file = await completeFileUpload(db, workspaceId, upload.id);
-    await recordWorkspaceUsage(deps, {
-      accountId: grant.accountId,
-      workspaceId,
-      subjectId: grant.subjectId,
-      eventType: "file.uploaded",
-      quantity: file.sizeBytes,
-      unit: "byte",
-      sourceResourceType: "file",
-      sourceResourceId: file.id,
-      idempotencyKey: `file.uploaded:${workspaceId}:${file.id}`,
-    });
+    const file = await completeAndRecordUsage();
     return c.json(CompleteFileUploadResponse.parse({ file }));
   });
 
@@ -134,15 +249,25 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(409, { message: `file is ${file.status}` });
     }
     const signed = await objectStorage.createGetUrl({ key: file.objectKey });
-    return c.json(FileDownloadUrlResponse.parse({
-      url: signed.url,
-      expiresAt: signed.expiresAt.toISOString(),
-    }));
+    return c.json(
+      FileDownloadUrlResponse.parse({
+        url: signed.url,
+        expiresAt: signed.expiresAt.toISOString(),
+      }),
+    );
   });
 }
 
 function sanitizeFilename(filename: string): string {
   const trimmed = filename.trim().replace(/[/\\]/g, "_");
-  const safe = trimmed.replace(/[^A-Za-z0-9._ -]+/g, "_").replace(/\s+/g, " ").trim();
+  const safe = trimmed
+    .replace(/[^A-Za-z0-9._ -]+/g, "_")
+    .replace(/\s+/g, " ")
+    .trim();
   return safe || "file";
 }
+
+/** Keep the cleanup lease internal; clients only consume terminal upload states. */
+function publicFileUploadStatus(status: string): string {
+  return status === "cleanup_pending" ? "failed" : status;
+}