Merge branch 'main' into claude/unify-agent-tools-p10

Author: kirill-markin

apps/backend/src/chat/cardImages/metadata.ts

@@ -1,16 +1,26 @@
 import { createHash } from "node:crypto";
+import type { CardTextSide } from "../../cards";
 import type { GeneratedCardImageOperationMetadata } from "./types";
 
 const generatedCardImageOperationNamespace = "flashcards-open-source-app:generated-card-image:v1";
+const generatedCardImageRequestBucketMs = 3_600_000;
+
+export type GeneratedCardImageRequestContent = Readonly<{
+  workspaceId: string;
+  cardId: string;
+  targetSide: CardTextSide;
+  imagePrompt: string;
+  altText: string;
+  requestedAtMs: number;
+}>;
 
 function deterministicUuidFromOperationIdentity(
   purpose: "operation" | "media-asset",
-  runId: string,
-  operationKey: string,
+  identity: ReadonlyArray<string | number>,
 ): string {
   const digest = createHash("sha256")
     .update(JSON.stringify(
-      [generatedCardImageOperationNamespace, purpose, runId.toLowerCase(), operationKey],
+      [generatedCardImageOperationNamespace, purpose, ...identity],
     ))
     .digest();
   const uuidBytes = Buffer.from(digest.subarray(0, 16));
@@ -27,15 +37,49 @@ function deterministicUuidFromOperationIdentity(
   ].join("-");
 }
 
-export function deriveGeneratedCardImageOperationMetadata(
-  runId: string,
-  operationKey: string,
+function deriveOperationMetadataFromIdentity(
+  identityKind: GeneratedCardImageOperationMetadata["identityKind"],
+  identity: ReadonlyArray<string | number>,
 ): GeneratedCardImageOperationMetadata {
-  const operationId = deterministicUuidFromOperationIdentity("operation", runId, operationKey);
+  const operationId = deterministicUuidFromOperationIdentity("operation", identity);
   return {
+    identityKind,
     operationId,
-    mediaAssetId: deterministicUuidFromOperationIdentity("media-asset", runId, operationKey),
+    mediaAssetId: deterministicUuidFromOperationIdentity("media-asset", identity),
     mediaLastOperationId: `generated-card-image:${operationId}:media`,
     cardLastOperationId: `generated-card-image:${operationId}:card`,
   };
 }
+
+export function deriveGeneratedCardImageOperationMetadata(
+  runId: string,
+  operationKey: string,
+): GeneratedCardImageOperationMetadata {
+  return deriveOperationMetadataFromIdentity("chat_run", [runId.toLowerCase(), operationKey]);
+}
+
+/**
+ * Identity for surfaces without a chat run. `requestedAtMs` is the backend clock at request
+ * receipt, bucketed into epoch-aligned UTC hours: a literal repeat inside the hour is the same
+ * operation, while a retry that lands in the next hour is a new, separately paid operation.
+ */
+export function deriveRequestContentGeneratedCardImageOperationMetadata(
+  request: GeneratedCardImageRequestContent,
+): GeneratedCardImageOperationMetadata {
+  if (!Number.isSafeInteger(request.requestedAtMs) || request.requestedAtMs < 0) {
+    throw new RangeError(
+      "Generated card image requestedAtMs must be a non-negative epoch-millisecond safe integer.",
+    );
+  }
+  const contentSha256 = createHash("sha256")
+    .update(JSON.stringify([request.imagePrompt, request.altText]))
+    .digest("hex");
+  return deriveOperationMetadataFromIdentity("request_content", [
+    "request-content",
+    request.workspaceId.toLowerCase(),
+    request.cardId.toLowerCase(),
+    request.targetSide,
+    contentSha256,
+    Math.floor(request.requestedAtMs / generatedCardImageRequestBucketMs),
+  ]);
+}

apps/backend/src/chat/cardImages/operation.postgres.integration.ts

@@ -246,6 +246,9 @@ test("generated image operation reconciles ambiguous enqueue without early card
       let stagedObject: GeneratedMediaStagingObject | null = null;
       const dependencies = createGeneratedCardImageOperationDependencies({
         markProviderStartedFn: markGeneratedCardImageProviderStarted,
+        markGeneratedMediaProviderStartedObjectFn: async () => {
+          throw new Error("Chat operations must not write the storage provider-started marker.");
+        },
         generateProviderImageFn: async () => {
           providerCalls += 1;
           providerStarted.resolve();
@@ -443,6 +446,9 @@ test("persisted provider start blocks replay without staging and permits staged
           providerStartCalls += 1;
           return markGeneratedCardImageProviderStarted(params);
         },
+        markGeneratedMediaProviderStartedObjectFn: async () => {
+          throw new Error("Chat operations must not write the storage provider-started marker.");
+        },
         generateProviderImageFn: async () => {
           providerCalls += 1;
           throw new Error("Provider must not run after a durable provider start.");

apps/backend/src/chat/cardImages/operation.test.ts

@@ -167,6 +167,9 @@ test("provider-start commit-unknown never crosses the provider boundary", async
     markProviderStartedFn: async () => {
       throw commitUnknownError;
     },
+    markGeneratedMediaProviderStartedObjectFn: async () => {
+      throw new Error("Chat operations must not write the storage provider-started marker.");
+    },
     generateProviderImageFn: async () => {
       providerCallCount += 1;
       throw new Error("Provider must not run after an ambiguous start fence.");
@@ -202,6 +205,9 @@ test("previously-started provider state without staging is authoritative", async
   let providerCallCount = 0;
   const createdDependencies = createGeneratedCardImageOperationDependencies({
     markProviderStartedFn: async () => ({ status: "previously_started" }),
+    markGeneratedMediaProviderStartedObjectFn: async () => {
+      throw new Error("Chat operations must not write the storage provider-started marker.");
+    },
     generateProviderImageFn: async () => {
       providerCallCount += 1;
       throw new Error("Provider must not replay a previously-started operation.");
@@ -244,6 +250,9 @@ test("pre-provider staging lookup failure remains safely retryable", async () =>
       providerStartCallCount += 1;
       return { status: "first_started" };
     },
+    markGeneratedMediaProviderStartedObjectFn: async () => {
+      throw new Error("Chat operations must not write the storage provider-started marker.");
+    },
     generateProviderImageFn: async () => {
       providerCallCount += 1;
       return {
@@ -295,6 +304,9 @@ test("post-provider staging failure is authoritative and preserves its cause", a
       providerStartCallCount += 1;
       return { status: "first_started" };
     },
+    markGeneratedMediaProviderStartedObjectFn: async () => {
+      throw new Error("Chat operations must not write the storage provider-started marker.");
+    },
     generateProviderImageFn: async () => {
       providerCallCount += 1;
       return {

apps/backend/src/chat/cardImages/operation.ts

@@ -7,6 +7,7 @@ import { DatabaseCommitOutcomeUnknownError } from "../../database/transient";
 import { normalizeImageBytesForCard } from "../../mediaAssets/ingestion/imageNormalization";
 import {
   loadGeneratedMediaStagingObject,
+  markGeneratedMediaProviderStartedObject,
   storeGeneratedMediaStagingObject,
   type GeneratedMediaStagingObject,
 } from "../../mediaAssets/storage";
@@ -76,6 +77,7 @@ export type GeneratedCardImageExternalDependencies = Readonly<{
   markProviderStartedFn: (
     params: MarkGeneratedCardImageProviderStartedParams,
   ) => Promise<MarkGeneratedCardImageProviderStartedResult>;
+  markGeneratedMediaProviderStartedObjectFn: typeof markGeneratedMediaProviderStartedObject;
   generateProviderImageFn: (input: OpenAIImageGenerationInput) => Promise<GeneratedProviderImage>;
   normalizeImageBytesForCardFn: typeof normalizeImageBytesForCard;
   loadGeneratedMediaStagingObjectFn: typeof loadGeneratedMediaStagingObject;
@@ -213,15 +215,19 @@ async function prepareStagedGeneratedCardImage(
   };
   const existing = await dependencies.loadGeneratedMediaStagingObjectFn(stagingInput);
   if (existing !== null) return { ...existing, reused: true };
-  const providerStart = await dependencies.markProviderStartedFn({
-    userId: input.userId,
-    workspaceId: input.workspaceId,
-    runId: input.runId,
-    sessionId: input.sessionId,
-    claimToken: input.claimToken,
-    operationKey: input.operationKey,
-    databaseDeadlineAtMs: input.operationDeadlineMs,
-  });
+  // The chat flag is set in the same transaction that asserts the run claim; a request-content
+  // operation has no run, so its create-if-absent storage marker fences the paid call instead.
+  const providerStart = operationMetadata.identityKind === "chat_run"
+    ? await dependencies.markProviderStartedFn({
+      userId: input.userId,
+      workspaceId: input.workspaceId,
+      runId: input.runId,
+      sessionId: input.sessionId,
+      claimToken: input.claimToken,
+      operationKey: input.operationKey,
+      databaseDeadlineAtMs: input.operationDeadlineMs,
+    })
+    : await dependencies.markGeneratedMediaProviderStartedObjectFn(stagingInput);
   if (providerStart.status === "previously_started") {
     throw new GeneratedCardImageProviderOutcomeUnknownError(
       input.runId,
@@ -396,6 +402,7 @@ export async function generateCardImageWithDependencies(
 
 const defaultExternalDependencies: GeneratedCardImageExternalDependencies = {
   markProviderStartedFn: markGeneratedCardImageProviderStarted,
+  markGeneratedMediaProviderStartedObjectFn: markGeneratedMediaProviderStartedObject,
   generateProviderImageFn: async (input) => createOpenAIGeneratedCardImageProvider().generate(input),
   normalizeImageBytesForCardFn: normalizeImageBytesForCard,
   loadGeneratedMediaStagingObjectFn: loadGeneratedMediaStagingObject,

apps/backend/src/chat/cardImages/types.ts

@@ -32,6 +32,7 @@ export type GeneratedCardImageResult = Readonly<{
 }>;
 
 export type GeneratedCardImageOperationMetadata = Readonly<{
+  identityKind: "chat_run" | "request_content";
   operationId: string;
   mediaAssetId: string;
   mediaLastOperationId: string;

apps/backend/src/mediaAssets/storage/index.ts

@@ -52,13 +52,16 @@ export {
   GeneratedMediaPromotionStorageTransientError,
   loadGeneratedMediaStagingObject,
   loadGeneratedMediaStagingObjectWithDependencies,
+  markGeneratedMediaProviderStartedObject,
+  markGeneratedMediaProviderStartedObjectWithDependencies,
   promoteGeneratedMediaObject,
   promoteGeneratedMediaObjectWithDependencies,
   storeGeneratedMediaStagingObject,
   storeGeneratedMediaStagingObjectWithDependencies,
 } from "./promotion/generatedPromotion";
 export type {
   GeneratedMediaObjectPromotionInput,
+  GeneratedMediaProviderStartedMarkerResult,
   GeneratedMediaStagingObject,
   GeneratedMediaStagingObjectInput,
   StoreGeneratedMediaStagingObjectInput,

apps/backend/src/mediaAssets/storage/promotion/generatedPromotion.ts

@@ -30,6 +30,9 @@ export type GeneratedMediaStagingObjectInput = GeneratedMediaStorageRequestInput
 export type GeneratedMediaStagingObject = Readonly<{
   stagingStorageKey: string; mimeType: typeof imageJpegCardMediaBlobMimeType; sizeBytes: number; sha256: string;
 }>;
+export type GeneratedMediaProviderStartedMarkerResult =
+  | Readonly<{ status: "first_started" }>
+  | Readonly<{ status: "previously_started" }>;
 export type StoreGeneratedMediaStagingObjectInput = GeneratedMediaStagingObjectInput & Readonly<{
   bytes: Buffer; mimeType: typeof imageJpegCardMediaBlobMimeType; sizeBytes: number; sha256: string;
 }>;
@@ -350,6 +353,39 @@ export async function loadGeneratedMediaStagingObjectWithDependencies(
   );
   return metadata === null ? null : readStagingObject(input, metadata);
 }
+/**
+ * Create-if-absent zero-byte sibling of the staging key, written once before a paid provider call.
+ * The suffix keeps it off every staging key, whose leaf is a bare SHA-256 hex digest. A lost PUT
+ * response retried here answers 412 and reads as previously_started, which refuses a second payment.
+ */
+export async function markGeneratedMediaProviderStartedObjectWithDependencies(
+  input: GeneratedMediaStagingObjectInput,
+  dependencies: MediaAssetStorageDependencies,
+): Promise<GeneratedMediaProviderStartedMarkerResult> {
+  validateStagingIdentity(input);
+  const markerStorageKey = `${buildMediaUploadStagingStorageKey(
+    input.workspaceId, input.mediaAssetId, input.operationId,
+  )}.provider-started`;
+  try {
+    await runS3(input, "put_object", async () => dependencies.s3Client.send(
+      new PutObjectCommand({
+        Bucket: dependencies.getMediaAssetsStorageConfigFn().bucketName,
+        Key: markerStorageKey,
+        Body: Buffer.alloc(0),
+        IfNoneMatch: "*",
+      }),
+      { abortSignal: input.signal },
+    ));
+    return { status: "first_started" };
+  } catch (error) {
+    input.signal.throwIfAborted();
+    const statusCode = getS3ErrorStatusCode(error);
+    if (statusCode === 412) return { status: "previously_started" };
+    if (error instanceof GeneratedMediaPromotionStorageTransientError) throw error;
+    if (statusCode === null) throw error;
+    terminal("S3_REQUEST_REJECTED", "Object storage rejected the provider-started marker request.", statusCode);
+  }
+}
 export async function storeGeneratedMediaStagingObjectWithDependencies(
   input: StoreGeneratedMediaStagingObjectInput,
   dependencies: MediaAssetStorageDependencies,
@@ -439,6 +475,14 @@ export async function loadGeneratedMediaStagingObject(
     getMediaAssetsStorageConfigFn: getMediaAssetsStorageConfig,
   });
 }
+export async function markGeneratedMediaProviderStartedObject(
+  input: GeneratedMediaStagingObjectInput,
+): Promise<GeneratedMediaProviderStartedMarkerResult> {
+  return markGeneratedMediaProviderStartedObjectWithDependencies(input, {
+    s3Client: getMediaAssetsS3Client(),
+    getMediaAssetsStorageConfigFn: getMediaAssetsStorageConfig,
+  });
+}
 export async function storeGeneratedMediaStagingObject(
   input: StoreGeneratedMediaStagingObjectInput,
 ): Promise<GeneratedMediaStagingObject> {