Execution Contract

Execution Contract(실행 계약)는 모든 Tool 호출이 따르는 불변의 9단계 시퀀스입니다. 단계를 건너뛰지 않습니다. 순서를 변경하지 않습니다. 모든 실행은 결정론적이고, 트랜잭션으로 보호되며, 감사 추적이 가능합니다.

런타임에 AI는 개입하지 않습니다. 실행기(executor)는 이 계약에 따라 Flow 그래프를 처리하는 순수한 결정론적 엔진입니다.

9단계

1단계: 입력 검증

수신된 페이로드는 Tool에 선언된 JSON Schema에 대해 검증됩니다. 입력이 스키마와 일치하지 않으면 -- 필수 필드 누락, 타입 불일치, 범위 초과 값 -- 요청은 검증 오류와 함께 즉시 거부됩니다.

입력이 구조적으로 유효한 것이 확인될 때까지 어떤 비즈니스 로직도 실행되지 않습니다.

2단계: 인가

세 계층의 인가 검사가 순서대로 수행됩니다:

1. JWT 검증 -- 요청에는 유효하고 만료되지 않은 JSON Web Token이 포함되어야 합니다 (Tool이 공개로 설정된 경우 제외).
2. RBAC 검사 -- 사용자의 역할이 Tool의 allowedRoles 목록에 포함되어야 합니다. 예를 들어, deleteUser Tool은 admin만 허용할 수 있습니다.
3. 행 수준 정책 -- 대상 Entity에 rowLevelAccess가 활성화되어 있으면, 사용자는 자신이 소유한 레코드(ownerField로 결정)만 접근할 수 있습니다.

인가 검사가 하나라도 실패하면 데이터 읽기나 쓰기 전에 요청이 거부됩니다.

3단계: 정책 검사

Tool에 연결된 Policy가 평가됩니다. 이것은 런타임 정책 검사로, 설계 시점의 리스크 분석과는 별개입니다. 속도 제한, 행 수 제한, 예산 임계값 등이 포함됩니다.

block 행동이 지정된 정책이 위반되면 요청이 거부됩니다. warn 또는 escalate 행동이 지정된 정책은 위반을 기록하되 실행은 계속 진행됩니다.

4단계: 트랜잭션 시작

데이터베이스 트랜잭션이 열립니다. 이후의 모든 읽기 및 쓰기 작업은 이 트랜잭션 내에서 수행되어 원자성을 보장합니다. 이후 단계에서 무엇이든 실패하면 모든 변경 사항이 롤백됩니다.

5단계: Flow 그래프 실행

Tool의 Flow 그래프가 실행됩니다. 실행기는 시작 노드부터 DAG를 순회하며, 엣지를 따라 각 노드를 위상 순서(topological order)로 실행합니다:

• Read 노드는 트랜잭션 내에서 Entity를 조회합니다
• Write 노드는 Entity 레코드를 생성, 수정, 상태 전이 또는 소프트 삭제합니다
• Transform 노드는 Value DSL을 사용하여 파생된 값을 계산합니다
• If/Switch 노드는 조건을 평가하고 실행 경로를 분기합니다
• Assert 노드는 사전 조건을 강제하며 실패 시 Flow를 중단합니다
• External 노드(Payment, Email, HTTP)는 외부 서비스를 호출합니다 -- 이들은 트랜잭션 경계 밖에 배치됩니다

Flow 그래프는 설계 시점에 이미 DAG로 검증되었으므로, 실행기는 런타임에 순환 감지를 수행하지 않고 처리할 수 있습니다.

6단계: 불변식 강제

Flow 그래프가 완료된 후, 영향을 받은 Entity에 정의된 모든 불변식(invariant)이 평가됩니다. 불변식은 항상 참이어야 하는 비즈니스 규칙을 나타내는 Value DSL 불리언 표현식입니다.

불변식이 하나라도 false로 평가되면 트랜잭션이 롤백되고, 불변식 위반 오류와 함께 요청이 실패합니다. 이를 통해 Flow가 무엇을 하든 데이터가 항상 유효한 상태를 유지하도록 보장합니다.

7단계: 커밋 또는 롤백

모든 불변식을 통과하면 트랜잭션이 커밋되고 모든 변경 사항이 영구적으로 반영됩니다. 4단계부터 6단계 사이에서 어떤 단계라도 실패하면 트랜잭션이 롤백되고 어떤 변경도 저장되지 않습니다.

이것은 전부 아니면 전무(all-or-nothing) 연산입니다. 부분적인 쓰기는 절대 발생하지 않습니다.

8단계: 감사 로그 기록

성공 여부와 관계없이 모든 실행에 대해 감사 로그 항목이 기록됩니다. 감사 로그에는 다음이 포함됩니다:

• 타임스탬프
• 사용자 ID
• Tool 이름
• 수행된 작업
• 영향을 받은 Entity ID
• 변경 전후 상태 (쓰기 작업의 경우)
• 성공 또는 실패 상태
• 오류 세부 정보 (해당하는 경우)

감사 로그는 추가 전용(append-only)입니다. 수정하거나 삭제할 수 없습니다.

9단계: 정규화된 출력 반환

결과는 Tool의 출력 JSON Schema에 맞는 정규화된 형식으로 호출자에게 반환됩니다. 성공 응답에는 요청된 데이터가 포함됩니다. 실패 응답에는 코드, 메시지, 세부 정보를 포함하는 구조화된 오류가 포함됩니다.

어떤 Flow 경로를 거쳤든, 얼마나 많은 노드가 실행되었든, 호출자는 항상 예측 가능한 응답 형태를 받습니다.

보장 사항

Execution Contract는 모든 Tool 호출에 대해 다음을 보장합니다:

• 결정론적(Deterministic) -- 동일한 입력과 동일한 데이터 상태에서 항상 동일한 결과를 생성합니다.
• 트랜잭션(Transactional) -- 모든 쓰기는 완전히 커밋되거나 완전히 롤백됩니다. 부분 상태는 없습니다.
• 감사 가능(Auditable) -- 모든 실행이 전체 컨텍스트와 함께 기록되며, 쓰기 작업의 경우 변경 전후 상태가 포함됩니다.
• 검증됨(Validated) -- 입력은 스키마로 검증되고, 인가가 확인되며, 모든 호출에서 불변식이 강제됩니다.
• 런타임 AI 없음(No AI at runtime) -- 실행기는 순수한 그래프 처리 엔진입니다. LLM 호출, 확률적 동작, 비결정성이 없습니다.