ormuzPARTNER
Platform governance/Reliability

Reliability, idempotency, and provenance

An extension must remain safe when calls are replayed, events arrive late, or an attempt fails after an external effect. Reliability is a property of the contract, not an assumption about transport.

Idempotence

Do not declare an operation idempotent simply because it is usually called once. Identify the stable key that represents the business intent and how a retry finds the effect already produced.

  • reuse the Ormuz identifier when it already represents the operation;
  • use a durable mapping to find an external resource created from a platform object;
  • after a post-submission timeout, look for the existing effect before retrying a mutation;
  • do not create a second idempotency primitive when a canonical identity is sufficient.
Timeout after mutation

A timeout does not prove that the external effect failed. Treat the state as uncertain and reconcile the operation before any new commit.

Replay and inbound events

Normalization of an inbound event may be replayed. It must therefore produce no non-idempotent side effect merely because a webhook was received again.

Arrival order of external events must not replace canonical lifecycle rules. An invalid transition remains invalid even if its timestamp is newer; a non-terminal state must not regress a terminal state.

Warnings

A warning describes a successful but degraded or notable execution. It must never be used to disguise a blocking error.

  • use a stable machine code in snake_case ;
  • write a safe message for the operator, with no secret or raw payload;
  • keep warnings out of the business output contract;
  • do not turn a success into a failure solely because a warning is present.

Actionable errors

A public error must let the process, Agent, or operator understand the nature of the problem without exposing internal details or credentials.

Where possible, distinguish validation, authority, permission, resource-not-found, lifecycle-conflict, and partner-unavailability errors. A vague technical error must not replace a business result expected by the contract.

Provenance and correlation

Keep the identity that links an Ormuz operation to its external effect, but do not turn that correlation into a new mastership system.

Provenance references, mappings, and event identities must make it possible to explain and deduplicate effects without duplicating the business object or losing its history.