ratchet_begin_effect

com.ratchetgate/ratchet · Verify this server

Call this IMMEDIATELY BEFORE performing any side effect that touches the outside world (sending a message, charging a card, creating a resource, writing to someone else's system). Returns a decision you MUST obey. If the response carries budget_warning, a spend ceiling exists but nothing was counted toward it — surface that to the operator rather than ignoring it. If it carries integration_warning, you have been beginning effects without reporting them: call ratchet_report_effect after every action, and tell the operator, because the effects already begun will start being blocked. Decisions: - "execute": you hold the lease. Perform the action now, then call ratchet_report_effect. If the response carries vendor_idempotency_key, send that key to the vendor as ITS own idempotency key (the response says where it goes). Where enforced is true the vendor itself will then refuse a duplicate, which protects the action even if some other caller skips this gate entirely. - "duplicate": this action ALREADY HAPPENED. Do NOT perform it. Use the returned `result` as though you had just done the work. - "in_flight": another process is doing it right now. Do NOT perform it. Wait `retry_after_seconds` and ask again. - "blocked": an earlier attempt may or may not have taken effect. Do NOT perform it. Tell the user what is unresolved, or verify at the vendor and call ratchet_resolve_effect. - "approval_required": a human must approve. Do NOT perform it. - "denied": policy or budget refused it. Do NOT perform it. The idempotency_key must be derived deterministically from the work itself so that a retry of the same logical action produces the same key. Never use a random value or the current time.