Reservation / Inventory Patterns, Conditional Writes, Expiration, Compensation, and Oversell Prevention

Learning outcomes

1. The AtlasMart problem: “held for 15 minutes” is two different requirements

When AtlasMart says an item is “held for 15 minutes,” it really means two things: the checkout must not oversell while the reservation is active, and an abandoned hold should eventually release inventory. The first requirement is a strict invariant and belongs inside a transaction. The second is a workflow/time policy and may be processed later. Treating Firestore TTL as the exact release timer confuses data retention with business scheduling.

2. Create one reservation atomically

process.env.FIRESTORE_EMULATOR_HOST = "127.0.0.1:8080";process.env.GCLOUD_PROJECT = "demo-atlasmart-firestore";import { initializeApp } from "firebase-admin/app";import { getFirestore, FieldValue, Timestamp } from "firebase-admin/firestore";initializeApp({ projectId: "demo-atlasmart-firestore" });const db = getFirestore();

async function createReservation({orderId,sku,qty,correlationId}) {  const itemRef=db.doc(`catalogItems/${sku}`);  const reservationRef=db.doc(`reservations/${orderId}`);  const orderRef=db.doc(`orders/${orderId}`);  return db.runTransaction(async tx=>{    const [item,reservation]=await Promise.all([tx.get(itemRef),tx.get(reservationRef)]);    if (reservation.exists) return reservation.data(); // idempotent duplicate command    if (!item.exists || item.get("stock") < qty) throw new Error("INSUFFICIENT_STOCK");    const expiresAt=Timestamp.fromMillis(Date.now()+15*60_000);    tx.update(itemRef,{stock:FieldValue.increment(-qty),updatedAt:FieldValue.serverTimestamp()});    tx.create(reservationRef,{orderId,sku,qty,state:"HELD",expiresAt,correlationId,schemaVersion:3,createdAt:FieldValue.serverTimestamp()});    tx.set(orderRef,{state:"RESERVED",sku,qty,correlationId,schemaVersion:3,updatedAt:FieldValue.serverTimestamp()},{merge:true});    return {orderId,sku,qty,state:"HELD",expiresAt,correlationId};  });}

The reservation document is durable authority. The product’s visible stock has already been decremented, so a second buyer cannot reserve the same unit if all writes obey this transaction path. Security Rules deny clients from directly changing server-owned inventory/reservation state.

3. Expire with an explicit sweeper, not TTL timing

async function releaseIfExpired(reservationId, nowMs=Date.now()) {  const reservationRef=db.doc(`reservations/${reservationId}`);  return db.runTransaction(async tx=>{    const r=await tx.get(reservationRef);    if (!r.exists) return {action:"missing"};    const data=r.data();    if (data.state!=="HELD") return {action:"noop",state:data.state};    if (data.expiresAt.toMillis()>nowMs) return {action:"not-expired"};    const itemRef=db.doc(`catalogItems/${data.sku}`);    const orderRef=db.doc(`orders/${data.orderId}`);    tx.update(itemRef,{stock:FieldValue.increment(data.qty),updatedAt:FieldValue.serverTimestamp()});    tx.update(reservationRef,{state:"RELEASED",releasedAt:FieldValue.serverTimestamp(),releaseReason:"EXPIRED"});    tx.set(orderRef,{state:"CANCELLED",cancelReason:"RESERVATION_EXPIRED",updatedAt:FieldValue.serverTimestamp()},{merge:true});    return {action:"released",qty:data.qty};  });}

Run the sweeper again and it must return noop; stock must not increase twice. That is idempotent compensation. In production, a scheduler, task queue or event system can drive the sweeper, but the state transition itself still needs duplicate-safe logic.

4. TTL is cleanup, not the clock that releases inventory

Firestore TTL makes a document eligible for asynchronous deletion based on a timestamp. Current documentation states that expired documents can remain visible until deletion and that deletion is typically within 24 hours. TTL deletions are not transactional with neighboring documents and do not necessarily occur in expiration order. Therefore, AtlasMart must release stock before (or independently of) TTL cleanup. An optional TTL policy may later remove RELEASED/COMPLETED workflow evidence according to retention policy, but only after the business/audit requirements allow it.

5. Conditional writes and stale workers

Imagine two sweepers both inspect the same expired reservation. A transaction prevents both from applying the release because only one can transition HELD → RELEASED; the retrying worker sees the new state and performs no increment. On trusted server code, update-time preconditions can also be useful for compare-and-set patterns, but when several documents must change together, a transaction keeps the state check and compensation in one atomic boundary.

const snap=await db.doc("orders/ord-ch10-001").get();await snap.ref.update(  {note:"operator-reviewed"},  {lastUpdateTime:snap.updateTime});// A stale writer using an older updateTime fails instead of silently overwriting newer state.

6. Payment failure compensation

async function compensateOrder(orderId, reason) {  const orderRef=db.doc(`orders/${orderId}`);  const reservationRef=db.doc(`reservations/${orderId}`);  return db.runTransaction(async tx=>{    const [o,r]=await Promise.all([tx.get(orderRef),tx.get(reservationRef)]);    if (!o.exists || !r.exists) return {action:"missing"};    if (["CANCELLED","COMPLETED"].includes(o.get("state"))) return {action:"noop",state:o.get("state")};    if (r.get("state")==="HELD") {      tx.update(db.doc(`catalogItems/${r.get("sku")}`),{stock:FieldValue.increment(r.get("qty"))});      tx.update(reservationRef,{state:"RELEASED",releaseReason:reason,releasedAt:FieldValue.serverTimestamp()});    }    tx.update(orderRef,{state:"CANCELLED",cancelReason:reason,updatedAt:FieldValue.serverTimestamp()});    return {action:"cancelled"};  });}

Compensation has its own invariants: never release the same hold twice, never cancel a completed order without an explicit administrative workflow, and preserve why the compensation occurred.

7. Reproducible AtlasMart lab

{  "name": "atlasmart-firestore-ch10",  "private": true,  "type": "module",  "engines": { "node": ">=22" },  "dependencies": {    "firebase-admin": "14.4.0"  },  "devDependencies": {    "firebase-tools": "15.30.0"  }}

{  "firestore": {    "rules": "firestore.rules",    "indexes": "firestore.indexes.json"  },  "emulators": {    "firestore": { "port": 8080 },    "auth": { "port": 9099 },    "ui": { "enabled": true, "port": 4000 }  }}

rules_version = '2';service cloud.firestore {  match /databases/{database}/documents {    match /catalogItems/{productId} { allow read: if true; allow write: if false; }    match /profiles/{uid} { allow read, write: if request.auth != null && request.auth.uid == uid; }    match /orders/{orderId} {      allow read: if request.auth != null && resource.data.customerId == request.auth.uid;      allow write: if false;    }    // Workflow state, reservations, outbox/inbox, dedupe and repair evidence are server-owned.    match /workflowCommands/{id} { allow read, write: if false; }    match /reservations/{id} { allow read, write: if false; }    match /workflowEvents/{id} { allow read, write: if false; }    match /workflowOutbox/{id} { allow read, write: if false; }    match /workflowDeadLetters/{id} { allow read, write: if false; }    match /counters/{counterId}/{document=**} { allow read, write: if false; }    match /{document=**} { allow read, write: if false; }  }}

mkdir atlasmart-firestore-ch10 && cd atlasmart-firestore-ch10npm init -ynpm install firebase-admin@14.4.0npm install --save-dev firebase-tools@15.30.0# Save firebase.json, firestore.rules and firestore.indexes.json from this lesson.printf '{"indexes":[],"fieldOverrides":[]}' > firestore.indexes.jsonnpx firebase-tools@15.30.0 emulators:start --project demo-atlasmart-firestore --only firestore,auth

Seed stock 1. Create one reservation with an expiresAt five seconds in the future for the lab, then call releaseIfExpired before and after a supplied deterministic nowMs. Call it twice after expiration. Assert the item returns to stock 1 exactly once, the reservation becomes RELEASED, and the order becomes CANCELLED. Do not wait for or claim managed TTL behavior locally.

const base=Date.now();await db.doc("catalogItems/P-EXP").set({sku:"P-EXP",stock:1,schemaVersion:3});const r=await createReservation({orderId:"ord-exp-001",sku:"P-EXP",qty:1,correlationId:"corr-exp-001"});const before=await releaseIfExpired("ord-exp-001", r.expiresAt.toMillis()-1);const after=await releaseIfExpired("ord-exp-001", r.expiresAt.toMillis()+1);const again=await releaseIfExpired("ord-exp-001", r.expiresAt.toMillis()+60_000);const stock=(await db.doc("catalogItems/P-EXP").get()).get("stock");console.log({before,after,again,stock});if (stock!==1 || after.action!=="released" || again.action!=="noop") process.exitCode=1;

Production judgment

Reservation correctness depends on the transaction, not on TTL, background timing or client cache. Expiration should be represented as durable state and processed by a retry-safe worker. TTL can later enforce storage retention, with its own cost and lag. If the business requires near-exact expiry timing, select an appropriate scheduler/task mechanism and still keep the release operation idempotent. Lesson 4 now introduces the delivery reality that makes this mandatory: duplicate events and retries.

Knowledge check

1. Why can TTL not be the exact reservation timer?
2. What prevents double stock release?
3. Why retain a released reservation record?
4. What does expiresAt represent?
5. When is a precondition useful?

Summary and next step

Oversell prevention is transactional; expiration and compensation are workflow concerns. Durable state and idempotent release logic let AtlasMart tolerate late or duplicate scheduling. Next we make the event-delivery assumptions explicit.

Authoritative references

• Transactions and batched writes — atomic transaction/batch boundaries and retry behavior.
• Distributed counters — shard-based write distribution and read aggregation tradeoffs.
• Manage data retention with TTL policies — asynchronous deletion behavior, limits, pricing and monitoring.
• Cloud Firestore triggers — at-least-once delivery, non-guaranteed ordering, trigger scope and idempotency requirement.
• Eventarc Standard retry events — at-least-once delivery, duplicate handling, idempotency and dead-letter guidance.
• Firestore best practices — hotspot and scaling guidance.
• Firestore Enterprise overview — edition/mode boundaries to re-check before porting workflow assumptions.
• Firebase release notes — current SDK/tool versions.
• Admin Node.js release notes — 14.4.0 and Firestore client dependency baseline.
• Firebase CLI release notes — 15.30.0 baseline.