ormuzPARTNER
Home/Design standards

Design standards

Nodes, Agent tools, and events are different public contracts. Reusing internal services is healthy; automatically copying their surface from one contract to another is not.

Each interface has its own intent

InterfaceOptimized forCommon mistake
NodeExplicit composition in a graph, typed bindings, routes, and static guarantees.Creating a complete CRUD family without a process use case.
ToolSelection by an Agent, easy-to-supply arguments, useful observation, and bounded effect.Copying a node 1:1 or exposing a generic API to the model.
EventDescribe a fact that occurred and its typed context.Exposing the webhook mechanism rather than the business fact.

Shared guarantees

The shape of the interfaces may differ; their business invariants remain shared.

  • canonical types and identities;
  • creation, field, and transition authority;
  • permissions and merchant isolation;
  • data classification and provenance;
  • true operation idempotency;
  • observability and the economic contract when they apply.

Before publishing a contract

  1. Prove the use case

    Describe the business task or outcome that justifies a new public surface.

  2. Prove the authority

    Verify that the operation does not fabricate a decision or fact that belongs to another role.

  3. Bound the surface

    Define cardinality, limits, errors, effects, repetition, and required context.

  4. Document and test

    The contract must not depend on implicit knowledge of the code or provider.