Skip to main content

Execution Contract

The Execution Contract is the immutable 9-step sequence that every Tool invocation follows. No steps are skipped. No steps are reordered. Every execution is deterministic, transactional, and auditable.

There is no AI involved at runtime. The executor is a pure, deterministic engine that processes Flow graphs according to this contract.

The 9 Steps​

Step 1: Validate Input​

The incoming payload is validated against the Tool's declared JSON Schema. If the input does not match the schema -- missing required fields, wrong types, values out of range -- the request is rejected immediately with a validation error.

No business logic runs until the input is confirmed to be structurally valid.

Step 2: Authorize​

Three layers of authorization are checked in sequence:

  1. JWT verification -- The request must carry a valid, unexpired JSON Web Token (unless the Tool is configured as public).
  2. RBAC check -- The user's role must be in the Tool's allowedRoles list. For example, a deleteUser Tool might only allow admin.
  3. Row-level policy -- If the target Entity has rowLevelAccess enabled, the user can only access records they own (determined by the ownerField).

If any authorization check fails, the request is rejected before any data is read or written.

Step 3: Policy Check​

The Policies attached to the Tool are evaluated. These are runtime policy checks (distinct from the design-time risk analysis). Examples include rate limiting, row count limits, and budget thresholds.

If a policy with a block action is violated, the request is rejected. Policies with warn or escalate actions log the violation but allow execution to continue.

Step 4: Start Transaction​

A database transaction is opened. All subsequent read and write operations occur within this transaction, ensuring atomicity. If anything fails in the following steps, all changes are rolled back.

Step 5: Execute Flow Graph​

The Tool's Flow graph is executed. The executor traverses the DAG from the start node, following edges and executing each node in topological order:

  • Read nodes query Entities within the transaction
  • Write nodes create, update, transition, or soft-delete Entity records
  • Transform nodes compute derived values using the Value DSL
  • If/Switch nodes evaluate conditions and branch the execution path
  • Assert nodes enforce preconditions and abort if they fail
  • External nodes (Payment, Email, HTTP) call outside services -- these are placed outside the transaction boundary

The flow graph has already been validated as a DAG at design time, so the executor can process it without cycle detection at runtime.

Step 6: Enforce Invariants​

After the flow graph completes, all invariants defined on the affected Entities are evaluated. Invariants are Value DSL boolean expressions that represent business rules which must always hold true.

If any invariant evaluates to false, the transaction is rolled back and the request fails with an invariant violation error. This ensures that no matter what the flow does, the data always remains in a valid state.

Step 7: Commit or Rollback​

If all invariants pass, the transaction is committed and all changes become permanent. If any step from 4 through 6 failed, the transaction is rolled back and no changes are persisted.

This is an all-or-nothing operation. Partial writes are never possible.

Step 8: Write Audit Log​

An audit log entry is written for every execution, regardless of whether it succeeded or failed. The audit log includes:

  • Timestamp
  • User ID
  • Tool name
  • Operation performed
  • Entity IDs affected
  • Before and after state (for writes)
  • Success or failure status
  • Error details (if applicable)

Audit logs are append-only. They can never be modified or deleted.

Step 9: Return Normalized Output​

The result is returned to the caller in a normalized format matching the Tool's output JSON Schema. Success responses include the requested data. Failure responses include a structured error with a code, message, and details.

The caller always receives a predictable response shape, regardless of which flow path was taken or how many nodes were executed.

Guarantees​

The Execution Contract provides the following guarantees for every Tool invocation:

  • Deterministic -- The same input with the same data state always produces the same result.
  • Transactional -- All writes either fully commit or fully roll back. No partial state.
  • Auditable -- Every execution is logged with full context, including before/after state for writes.
  • Validated -- Input is schema-validated, authorization is checked, and invariants are enforced on every call.
  • No AI at runtime -- The executor is a pure graph-processing engine. No LLM calls, no probabilistic behavior, no non-determinism.