Claim Check Pattern

The previous two lessons kept the workflow’s steps correct: duplication was suppressed, half-finished steps were balanced. The data the workflow carries was never in question. When the carrier reports a delivery, it attaches proof of delivery alongside it — the recipient’s signature or a photo of the delivery point. This addition moves K01’s 220-byte state event record to a different order of magnitude, and that byte count passes through the queue, gets copied to every consumer, and is carried again on every redelivery.

The claim check is a layout that writes the large payload to a separate store and lets the message carry only a reference to that payload. This lesson’s measures are four: the message’s size, the bytes crossing the queue, how long the payload lives in a separate store, and the check dangling — the payload deleted, the check still in hand.

Two Writes, No Shared Transaction Boundary

DD8 — proof of delivery is 40,000 bytes. Rationale: the proof is a compressed signature image, two orders of magnitude above K01’s 900-byte shipment record. Its sensitivity is already visible in the message byte ratio. DD9 — a claim check record is 64 bytes: the store name, the object key, and a digest.

The pattern’s hidden cost starts here. The attached layout has a single write: the message goes to the queue and the proof is inside it. The claim-check layout has two writes — the proof to the store first, then the message to the queue — and the two share no transaction boundary. This is exactly The Data Access Layer and Business Logic course’s distributed transaction problem. Two new failure modes are born: the orphaned payload (the proof was written, the message was not) and the dangling claim check (the message is in hand, the proof is deleted).

// claim-check/queue.mjs — the in-process model of the event stream carrying proof of delivery.
// There is no real queue, store, or network: the queue is an array, the payload store a set, bytes are counted.

export const EVENT = 220, PROOF = 40_000, CHECK = 64;   // K01 V6; DD8 proof; DD9 check record

export function generator(seed) {              // 32-bit linear congruential generator, seed exposed
  let s = seed >>> 0;
  return () => { s = (Math.imul(s, 1103515245) + 12345) >>> 0; return s / 4294967296; };
}

// layout:   "attached" = the proof travels inside the message; "check" = the proof sits in a store, the message carries a check
// deletion: "immediate" = the consumer deletes on processing; "lifetime" = deletion waits out a lifetime
export function run({ n, layout, deletion, producerCrash, unackedCrash, seed }) {
  const rnd = generator(seed);
  const usesCheck = layout === "check";
  const message = usesCheck ? EVENT + CHECK : EVENT + PROOF;
  const store = new Set(), queue = [];
  const s = { message, bytesMoved: 0, deliveries: 0, lostEvents: 0, orphanedPayload: 0,
    danglingCheck: 0, processed: 0, remainingInStore: 0 };

  for (let i = 0; i < n; i += 1) {
    if (usesCheck) store.add(i);                        // the payload is written first
    const crashed = rnd() < producerCrash;              // then the message is written; a crash can land in between
    if (crashed) { if (usesCheck) s.orphanedPayload += 1; else s.lostEvents += 1; continue; }
    queue.push({ no: i, attempt: 0 });
  }
  while (queue.length > 0) {
    const m = queue.shift();
    s.bytesMoved += message; s.deliveries += 1;          // every delivery carries the message from scratch
    if (usesCheck && !store.has(m.no)) { s.danglingCheck += 1; continue; }
    s.processed += 1;
    if (usesCheck && deletion === "immediate") store.delete(m.no);
    if (rnd() < unackedCrash && m.attempt === 0) queue.push({ no: m.no, attempt: 1 });
  }
  s.remainingInStore = usesCheck ? store.size : 0;
  return s;
}

The failure scenario is named directly. DD10 — in the failure window, the probability that the producer crashes between its two writes is 0.005, the probability that the consumer crashes before acknowledgment is 0.01. Rationale: the first window is the short gap between two remote writes, the second is the gap between processing and acknowledgment, and the second is longer. Both are assumptions, not added to K01’s table.

// claim-check/measure.mjs — four layouts, without and with failure; message bytes and dangling counted
import { run, EVENT, PROOF, CHECK } from "./queue.mjs";

const N = 100_000;
const CONDITION = [["failure-free day", 0, 0], ["failure window (DD10)", 0.005, 0.01]];
const LAYOUT = [["attached", "-"], ["check", "immediate"], ["check", "lifetime"]];

console.log(`message bytes: attached ${EVENT + PROOF}, check ${EVENT + CHECK} ` +
  `(K01 V6 = ${EVENT} bytes event, DD8 = ${PROOF} bytes proof, DD9 = ${CHECK} bytes check)`);
for (const [name, producerCrash, unackedCrash] of CONDITION) {
  console.log(`\n${name}: ${N} delivery events, producer crash ${producerCrash}, unacked crash ${unackedCrash}`);
  console.log(`${"layout".padEnd(18)}${"deliveries".padStart(11)}${"MB moved".padStart(11)}` +
    `${"lost events".padStart(13)}${"orphaned".padStart(11)}${"dangling".padStart(11)}` +
    `${"processed".padStart(11)}${"in store".padStart(10)}`);
  for (const [layout, deletion] of LAYOUT) {
    const r = run({ n: N, layout, deletion, producerCrash, unackedCrash, seed: 20260730 });
    console.log(`${`${layout} ${deletion}`.padEnd(18)}${String(r.deliveries).padStart(11)}` +
      `${(r.bytesMoved / 1e6).toFixed(2).padStart(11)}${String(r.lostEvents).padStart(13)}` +
      `${String(r.orphanedPayload).padStart(11)}${String(r.danglingCheck).padStart(11)}` +
      `${String(r.processed).padStart(11)}${String(r.remainingInStore).padStart(10)}`);
  }
}

message bytes: attached 40220, check 284 (K01 V6 = 220 bytes event, DD8 = 40000 bytes proof, DD9 = 64 bytes check)

failure-free day: 100000 delivery events, producer crash 0, unacked crash 0
layout             deliveries   MB moved  lost events   orphaned   dangling  processed  in store
attached -             100000    4022.00            0          0          0     100000         0
check immediate        100000      28.40            0          0          0     100000         0
check lifetime         100000      28.40            0          0          0     100000    100000

failure window (DD10): 100000 delivery events, producer crash 0.005, unacked crash 0.01
layout             deliveries   MB moved  lost events   orphaned   dangling  processed  in store
attached -             100495    4041.91          492          0          0     100495         0
check immediate        100495      28.54            0        492        987      99508       492
check lifetime         100495      28.54            0        492          0     100495    100000

These numbers are in the measurement class: they come from a process-internal model and a generator seeded at 20260730.

The Deletion Policy Is a Correctness Decision

The top table gives the message bytes: the attached layout moves 4022.00 MB for a hundred thousand events, the claim-check layout 28.40 MB. The ratio is the message byte ratio, and with no failure there is no other difference.

The bottom table makes the real distinction, and the column that deserves attention is processed. In the attached layout, the producer’s crash drops 492 events entirely — the proof and the event were in a single write, and both were gone together. In the claim-check layout, the same crash still loses the events, but it leaves 492 orphaned payloads in the store; the loss is equal, and there is now garbage on top of it.

The two deletion policies behave differently under the same failure. Under immediate deletion, 987 redeliveries cannot find the proof and turn into dangling checks; the processed count sits at 99,508, meaning every event is processed exactly once. Under lifetime-based deletion, dangling checks are zero, but processed is 100,495: all 987 redeliveries find the proof and redo the work.

This is the pattern’s least-noticed consequence. The moment the payload is deleted turns, without anyone intending it, into an idempotency check: immediate deletion blocks duplicate processing but turns redelivery into an error; lifetime-based deletion runs the redelivery and hands the duplicated side effect off to the first lesson’s ledger. The correct setup keeps the two separate — the idempotency decision is made in the ledger, the deletion decision in the store; the payload’s lifetime is not used as a correctness mechanism.

Back to the Numbers

DD11 — proof lifetime is 7 days. Rationale: a delivery dispute arrives within the business day following the delivery day, and the proof is requested inside that window; proof is not kept without a dispute. Its sensitivity is given at 1 and 30 days.

// claim-check/cost.mjs — converting the measured message bytes into queue, storage, and dangling numbers at K01 scale
const V3 = 400_000, V8 = 3, DAY_SEC = 86_400;                     // K01: daily shipments, peak factor
const WRITE_MBIT = 0.17, GROWTH_MB = 976, STORAGE_GB = 712.48;    // K01 computed values
const BACKLOG = 525_000, EVENT_SHARE = 7;                         // M19/K03 message queues lesson: highest backlog
const ATTACHED = 40_220, CHECKED = 284, PROOF = 40_000;           // measure.mjs measurement; DD8
const peakDeliveries = (V3 / DAY_SEC) * V8;                       // every shipment produces one delivery event

console.log(`peak delivery events ${peakDeliveries.toFixed(4)} events/s (K01: ${V3} shipments/day, peak factor ${V8})`);
console.log(`\n${"layout".padEnd(12)}${"message bytes".padStart(14)}${"queue Mbit/s".padStart(15)}` +
  `${"of K01 write entry".padStart(21)}${"backlog MB".padStart(13)}`);
for (const [name, b] of [["attached", ATTACHED], ["check", CHECKED]]) {
  const mbit = (peakDeliveries * b * 8) / 1e6, backlog = ((BACKLOG / EVENT_SHARE) * b) / 1e6;
  console.log(`${name.padEnd(12)}${String(b).padStart(14)}${mbit.toFixed(4).padStart(15)}` +
    `${`${(mbit / WRITE_MBIT).toFixed(2)}x`.padStart(21)}${backlog.toFixed(1).padStart(13)}`);
}
console.log(`queue byte ratio ${(ATTACHED / CHECKED).toFixed(1)}x; ` +
  `backlog ${(BACKLOG / EVENT_SHARE).toLocaleString("en-US")} messages with proof (M19/K03: ${BACKLOG.toLocaleString("en-US")} events / ${EVENT_SHARE})`);

console.log(`\n${"DD11 lifetime".padStart(15)}${"proof in store".padStart(16)}${"store GB".padStart(11)}` +
  `${"of K01 storage".padStart(16)}${"of daily growth".padStart(17)}`);
for (const days of [1, 7, 30]) {
  const count = V3 * days, gb = (count * PROOF) / 1e9;
  console.log(`${`${days} d`.padStart(15)}${count.toLocaleString("en-US").padStart(16)}` +
    `${gb.toFixed(2).padStart(11)}${`${((100 * gb) / STORAGE_GB).toFixed(2)}%`.padStart(16)}` +
    `${`${((gb * 1000) / GROWTH_MB).toFixed(2)}x`.padStart(17)}`);
}

const DANGLING = 987 / 100_000, ORPHANED = 492 / 100_000;         // measure.mjs measurement
console.log(`\nfailure window at K01 scale (${V3.toLocaleString("en-US")} delivery events/day):`);
console.log(`dangling checks ${(V3 * DANGLING).toFixed(0)}/day, orphaned payloads ${(V3 * ORPHANED).toFixed(0)}/day`);
console.log(`orphaned payload bytes ${((V3 * ORPHANED * PROOF) / 1e6).toFixed(1)} MB/day, ` +
  `without a lifetime, a year gives ${((V3 * ORPHANED * PROOF * 365) / 1e9).toFixed(2)} GB`);
console.log(`in the attached layout, the same crash drops ${(V3 * ORPHANED).toFixed(0)} events entirely`);

peak delivery events 13.8889 events/s (K01: 400000 shipments/day, peak factor 3)

layout       message bytes   queue Mbit/s   of K01 write entry   backlog MB
attached             40220         4.4689               26.29x       3016.5
check                  284         0.0316                0.19x         21.3
queue byte ratio 141.6x; backlog 75,000 messages with proof (M19/K03: 525,000 events / 7)

  DD11 lifetime  proof in store   store GB  of K01 storage  of daily growth
            1 d         400,000      16.00           2.25%           16.39x
            7 d       2,800,000     112.00          15.72%          114.75x
           30 d      12,000,000     480.00          67.37%          491.80x

failure window at K01 scale (400,000 delivery events/day):
dangling checks 3948/day, orphaned payloads 1968/day
orphaned payload bytes 78.7 MB/day, without a lifetime, a year gives 28.73 GB
in the attached layout, the same crash drops 1968 events entirely

The Numbers for Two Days

The failure-free day’s cost has three line items. Every delivery event now carries two writes and one extra read on the consumer side; the single write’s atomicity is gone. At DD11 = 7 days, the proof sits in the store at 112.00 GB, 15.72 percent of K01’s 712.48 GB storage line. And on the storage side, the pattern has no gain at all: the proof occupies the same 40,000 bytes whether it is attached or checked. The claim check is a transport decision, not a storage decision.

The failure day’s gain sits in the queue. In the attached layout, the peak delivery flow puts 4.4689 Mbit/s on the queue — 26.29 times K01’s 0.17 Mbit/s write entry. In the claim-check layout, it is 0.0316 Mbit/s, 0.19 times the write entry. The real difference shows up in the backlog: given that one in seven of the 525,000 events The Application Layer and Service Interaction course measured is a message carrying proof, the queue has to hold 3016.5 MB in the attached layout and 21.3 MB in the claim-check layout. In a design where the queue is a bounded buffer, this 141.6-fold difference is the difference in how many events the same bound can hold.

The gain’s counterpart is new failure modes. At K01 scale, the failure window produces 1968 orphaned payloads a day (78.7 MB) and, under the immediate deletion policy, 3948 dangling checks. Without a lifetime, orphaned payloads climb to 28.73 GB a year; DD11 is not a storage parameter, it is a garbage collection mechanism. Dangling checks, on the other hand, are not data loss — all 3948 are redeliveries of work already processed — but they show up as errors on the consumer side, and if they are not routed off the dead-letter path, they hide real errors.

Summary

• Proof of delivery raises the message from 220 bytes to 40,220 bytes; the claim check brings it down to 284 bytes, a ratio of 141.6x.
• Queue load: the peak delivery flow is 4.4689 Mbit/s in the attached layout (26.29 times K01’s write entry), 0.0316 Mbit/s in the claim-check layout (0.19 times).
• The difference grows in the backlog: a backlog of 75,000 messages with proof holds 21.3 MB instead of 3016.5 MB.
• The pattern has no gain on the storage side: at DD11 = 7 days the proof sits at 112.00 GB, 15.72 percent of K01’s storage; the claim check is a transport decision, not a storage decision.
• The pattern splits a single write into two and introduces two new failure modes: 1968 orphaned payloads a day (78.7 MB, 28.73 GB a year without a lifetime) and 3948 dangling checks.
• The deletion policy is silently a correctness decision: under immediate deletion, processed is 99,508 (exactly once); under lifetime-based deletion, it is 100,495 (987 duplicate processing runs); the latter depends on the idempotency ledger.

Next Step

The proof left the queue, but the whole path still runs through the service. The carrier uploads the proof to the service, the service writes it to the store; when a recipient wants to see the proof, the service reads it from the store and passes it to the client. The 40,000 bytes removed from the queue still pass through the service’s request path twice, and when the store slows down, they tie up the service’s own workers. The next lesson takes on removing this byte count from the service as well: the limited-time authorization granted for direct client access to the resource, the byte count that never passes through the service, the authorization window it opens, and what narrowing that scope costs.