78% of My AI Bill Was Waste: Where Prompt Discipline Ends and Runtime Guards Begin

// Claim the key in a short Firestore transaction, then bill the model call once per claim
import { getApps, initializeApp } from "firebase-admin/app";
import { getFirestore, Timestamp } from "firebase-admin/firestore";
import { createHash, randomUUID } from "node:crypto";

const LEASE_MS = 120_000; // longer than the model call's own timeout, or a retry after it bills twice
const sha256 = (s: string) => createHash("sha256").update(s).digest("hex");

export class GuardRejection extends Error {}

export async function executeIdempotentInference(
  uid: string, // from the verified ID token, never from the request body
  idempotencyKey: string,
  requestBody: string,
  inferenceFn: () => Promise<string>
): Promise<string> {
  if (!getApps().length) initializeApp(); // here, not at import, so the entry file can initialize first
  const db = getFirestore();
  const claim = randomUUID(); // fences this call's late writes
  const ref = db.collection("inference_idempotency").doc(sha256(`${uid}:${idempotencyKey}`));
  const requestHash = sha256(requestBody);

  // Firestore may re-run this callback, so it only reads and writes documents
  const cached = await db.runTransaction(async (tx) => {
    const prior = (await tx.get(ref)).data();
    if (prior) {
      if (prior.requestHash !== requestHash) throw new GuardRejection("Key reused with a different body"); // 422
      if (prior.status === "done") return prior.result as string;
      if (prior.status === "failed") throw new GuardRejection("Failed key repeated: breaker open");
      if (prior.leaseUntil.toMillis() > Date.now()) throw new GuardRejection("Request in flight"); // 409
    }
    tx.set(ref, {
      requestHash,
      claim,
      status: "pending",
      leaseUntil: Timestamp.fromMillis(Date.now() + LEASE_MS),
      expireAt: Timestamp.fromMillis(Date.now() + 86_400_000), // TTL policy field
    });
    return null;
  });
  if (cached !== null) return cached;

  // Fenced write: a call that outlived its lease must not overwrite a newer claim
  const settle = (fields: { status: string; result?: string }) =>
    db.runTransaction(async (tx) => {
      if ((await tx.get(ref)).get("claim") === claim) tx.update(ref, fields);
    });
  let result: string;
  try {
    result = await inferenceFn(); // outside the transaction: one bill per claim
  } catch (err) {
    await settle({ status: "failed" }); // the next call with this key opens the breaker
    throw err;
  }
  await settle({ status: "done", result }); // outside the try: a billed result is never marked failed
  return result;
}