5. Give privileged users a richer output shape

When a manager reroutes an applicant, the response should include previous_stage and an audit_trail. Operators should never receive those fields — not even i...

Problem. When a manager reroutes an applicant, the response should include previous_stage and an audit_trail. Operators should never receive those fields — not even if a handler bug tries to emit them.

Solution. Define two output variants and tag the privileged one with @requires.

# @rbs type success = {
#   success: true,
#   applicant_id: String,
#   current_stage: String
# }

# @rbs type rerouted_success = {
#   success: true,
#   applicant_id: String,
#   previous_stage: String,
#   current_stage: String,
#   audit_trail: Array[String]
# }

# @rbs type output = success
#                   | rerouted_success  @requires(:backward_routing)
#                   | error

Result. An operator's output schema is success | error. A manager's is success | rerouted_success | error. The enforcement bite: the gem projects the handler's return value onto the caller's compiled output schema. If your call returns audit_trail to an operator by mistake, the field is stripped before it crosses the wire. A refactor accident can't leak privileged fields.

Collected from COOKBOOK.md in the repository. Edit it there, not here.