Why we made holding an order a feature

The ZeroClickShip source models a stopped synthetic order as explicit work rather than silent progress. This note explains that design choice; it is not a report from live customer or carrier operation.

The clear-the-queue instinct

An exception counter can reward making the number smaller without proving that the next state is justified. But an empty queue is not the goal of a shipping operation. The intended goal is that each local decision has enough evidence, authority, and state to be reviewed later.

A generic warning makes the required action and accountability unclear. The product direction is therefore to stop the synthetic order, name the reason, preserve the current version, and require the next bounded step instead of optimising only for queue clearance.

A system that quietly proceeds when it is unsure is not automated. It is unaccountable.

Naming every reason

The source-backed correction model treats a hold as named state with a reason and version, not merely a transient error message. Ownership and complete reason catalogues remain product work unless their status says otherwise.

// before
{ "error": "Order failed validation (3 errors)" }

// after
{
  "status": "held",
  "hold_reason": "item_weight_mismatch",
  "detail": "line 2 declares 2.000 kg; carton scan reports 2.400 kg",
  "rule": "wt-tolerance-uk", "rule_version": 7,
  "resolvable_by": ["orders:correct"]
}

When a reason becomes structured data, future interfaces can filter, count, route, and explain it consistently. Those downstream capabilities must still be implemented and evidenced separately.

What changed at the bench

The design hypothesis is that an earlier, more specific hold is more useful than a late generic failure. That hypothesis still needs agreed design-partner evidence; this note does not claim a packing-bench study.

In the current synthetic correction model, a user records a bounded field value and reason, then validation is rerun against the new version. The original synthetic capture and version history remain distinct from the correction.

The cost of a silent decision

A system could appear faster by guessing a missing value or treating an ambiguous provider response as success. ZeroClickShip’s design rejects that optimisation because the evidence for the next action would be incomplete.

The intended behaviour is to stop, state why, and require an authorised decision. Live operational value, cost, and throughput remain unproven until a separately approved pilot measures them.