7장 조사 작업 API와 상태 기계

에이전트 작업은 요청 한 번으로 끝나지 않는다. queued → running → completed가 정상 경로이고 blocked, failed, cancelled가 옆에 있다. blocked는 입력이나 승인을 기다리는 상태, failed는 같은 입력으로 실행을 끝내지 못한 상태다. 둘을 섞으면 자동 재시도가 사람의 결정을 우회한다.

현재 실습 서버는 Node 표준 http만 사용한다. GET /api/snapshot, GET /api/evidence, POST /api/decisions가 있다. 작은 코어부터 검증한 뒤 실제 배포에서 Fastify나 프레임워크 어댑터로 옮긴다. 핵심 규칙은 프레임워크가 아니라 도메인 함수에 둔다.

const record = store.decide({
  evidenceId: 'EV-001',
  decision: 'accepted',
  reason: '정부 원문과 적용 범위를 대조함'
});

결정 API는 멱등 키를 확장 과제로 둔다. 네트워크 재시도로 같은 판정이 두 번 저장되지 않게 decisionRequestId에 고유 제약을 둔다. 늦게 도착한 에이전트 결과는 현재 작업 버전과 비교하고, 버전이 다르면 자동 채택하지 않는다.