Human-in-the-loop as a product primitive, not a config flag

The first version of the workflow engine treated approval as a step in the workflow graph. The graph had nodes for parsing, classification, enrichment, validation, approval, and emit. Each node was the same kind of thing: a function the runtime invoked, with a configurable predicate for when it ran.

On paper this looked clean. In production it had the wrong shape. The problem was structural: if approval is a step, then skipping it is a configuration decision. Someone with edit permission on a workflow graph could remove an approval node, or set its predicate to false, and the runtime would happily emit external writes to a production ERP without a signed human approval in the audit trail.

We caught two instances in pre-production of an approval node being skipped because the workflow author copy-pasted a template that did not include the node. Both were caught by review. Neither would have been caught by the runtime.

Before we get to the right shape, it is worth naming the two failure modes the wrong shape produces. They look different on the surface. They are the same structural error from opposite directions.

The cautious shape: route every effectful action through a full review queue. Every write to the ERP, every email to a vendor, every status flip on a WO record. Within a week, the queue has hundreds of items and operators are bulk-clicking through them at the rate of a few seconds per item. The signature is technically present on every action. The signature carries no information about whether anyone read the row.

This is the failure mode that looks safe and is not. An audit report shows 100% of writes were approved. An operations review shows the operator approved 312 rows in 14 minutes on a Friday. The system is structurally compliant and operationally hollow.

The optimistic shape: trust the model, let writes flow, treat approvals as exception handling. This shape works for read-only enrichment and proposals. It is catastrophic for effectful writes. The first time an autonomous write hits the wrong vendor, or sends a PO at the wrong price tier, or flips a WO status that the floor was actually relying on, the operations VP will demand every autonomous write be unwound, and the unwind itself is the kind of operation nobody has tooling for.

The two failure modes converge on the same underlying error: treating approval as a runtime policy rather than a property of the action itself. Policy you can tune. Properties you cannot strip.

The second version of the runtime made a single change with large consequences: every effectful operation. every write to a vendor portal, every PO emit, every supplier email. became an instance of a single Action object. The runtime is structurally incapable of producing side effects any other way.

The Action type has one mandatory field that the runtime checks at emit time: approval. The field holds a signed approval record, with a user id, a timestamp, and a content hash over the exact payload that is about to be emitted. An Action instance without a valid approval is not a runtime error. It is a type error. The code that constructs the Action will not compile if approval is omitted, and the runtime will not accept an Action whose approval hash does not match the payload.

Skipping approvals is no longer a config flag. It is no longer a property of the workflow graph. It is a property of every effectful operation the runtime can perform.

Once approval is a primitive, the design question becomes: which operations are Action and which are not. We have a simple taxonomy. Anything that produces an effect on a system the operator does not own. vendor inboxes, ERP writes, portal posts, EDI emits. is an Action and must be approved. Anything internal. proposals, enrichments, log writes, lookups. is not an Action and does not gate.

Approval as a primitive answers "can this action emit at all?" A second question is harder: who is allowed to sign for what? The buyer who can approve a $50k coil PO should not be able to approve a $500k capital purchase. The intake engineer who can approve a BOM revision should not be approving vendor onboarding.

The runtime models this as a role-scoped console. Each operator is associated with one or more roles. Each role carries a scope. a set of Action types, value bands, vendor subsets, plant subsets. The approval surface for a given operator only shows the Actions inside their scope. Out-of-scope Actions exist on someone else's queue.^[1]

The console is intentionally opinionated. It does not allow an operator to grant themselves additional scope. Scope changes are themselves Actions, and they require a two-sig gate from the role-admin role.

Making approval a primitive only matters if the approval surface is usable. A queue that floods with every routine write is functionally the same as a config flag. operators will start bulk-clicking through it and the signature stops carrying meaning.

The gate evaluates three kinds of conditions to decide what shows up:

• Bands. Most routine actions sit inside pre-agreed bands. supplier within historical price range, quantity within rolling forecast, vendor on the approved list. Within band, the action shows up in a one-click approve lane. Out of band, it escalates to a full review.
• Vendor / item history. A new supplier, a new item, or a revision that has not appeared on a PO in the last twelve months always escalates. The gate treats absence of history as a signal.
• Bulk-vs-unit scope. Bulk approve is available, but it operates on an explicit scope (e.g. "all in-band POs to V-218 this morning") with a single signed approval that covers the scope. The individual Action objects each carry the scope reference, so the audit trail can reconstruct which scope authorized each write.

Treating approval as a primitive gives you something almost as valuable as the safety guarantee: a complete, source-linked audit trail. Every external write the runtime ever performed can be traced backward through the Action it was emitted as, the approval that authorized it, the proposal it was drafted from, and the source artifacts the proposal was reconciled from.

This is the line that auditors and IT security teams care about most. "Show me every PO Polymr has emitted in the last quarter, who approved each, against what input evidence" is a single query against the audit index. We designed the index that way because once approval is a primitive, the audit shape comes nearly for free.

The cost of the first version was not abstract. We watched the team start to write defensive code around the runtime - wrapping emits in their own check layers, building per-call assertion harnesses, gating CI on snapshot tests of serialized workflow graphs. Every one of those was a workaround for a missing primitive.

The second version made all of that defensive code obsolete in a single change. The wrapper checks were deleted. The assertion harnesses are now type-level. The snapshot tests got replaced with a much smaller set of tests against the Action constructor.

The general lesson is one we keep relearning: when the right shape is a type, do not implement it as a graph node. The type catches the case at construction time, in every code path, forever. The graph catches it on the paths you remembered to add a node to.

The primitive is one piece. The surface around it is the other. A primitive that is structurally safe but operationally painful gets routed around within a quarter. operators will find ways to batch-approve everything, or to push work to a colleague with a different permission scope, or to do the write manually outside the system. The surface has to be good enough that the safe path is also the fast path.

Three principles drove the approvals UI. First, every Action in the queue shows its provenance inline. the source PDF, the parsed proposal, the band the action sits inside or outside. The operator does not click through to a second screen to understand what they are approving. Second, the one-click lane and the full-review lane are visually distinct. The one-click lane is for in-band actions where the operator's role is to confirm the runtime did not err; the full-review lane is for escalations where the operator's role is to apply judgment. Mixing the two breaks the operator's intuition for how much attention a row needs. Third, bulk approve is scoped, not unbounded - a scope query, an explicit count, a signed approval that carries the scope reference forward.

We have iterated this surface twice. The first iteration had a generic queue with row-level approve buttons; in practice it produced approval fatigue within a week. The current iteration separates the lanes, surfaces provenance inline, and constrains bulk approve to explicit scopes. The per-operator approval throughput went up while the rate of retrospective "I approved that without looking properly" flags went down.

If you are evaluating an operations layer that writes to your ERP, the question to ask is not "does it support approvals?" The honest answer from every vendor will be yes. The right question is "is the approval gate a property of every external write, or is it a step in the workflow that someone can remove?" The two have radically different safety properties and the difference will show up the first time someone bulk-edits a workflow on a Friday afternoon.

A second question worth asking: "Show me the audit record for a single PO emit, end to end." If the answer is a log file with the emit timestamp and the user that ran the workflow, the approval is bolted on. If the answer is a structured record that shows the Action, the signed approval, the proposal it was drafted from, and the source artifacts - all linked, all queryable. the approval is structural. Only one of those answers survives the first time a vendor disputes a PO line.