ARTEX 현재 시스템 지도

ARTEX 현재 시스템 지도 · 관계

이 대상이 사용하는 구현·계약·의존 · 4개

계약 사용 · 강제 지점 지도 · 기능/모듈이 적용하는 보안·신뢰 규칙 · rule-edge-6
의존 / 실행 · Planner session · system bootstrap가 agent manager 구성 · core-edge-6
의존 / 실행 · Router와 middleware · system bootstrap가 HTTP server 구성 · core-edge-7
의존 / 실행 · Manager 구성과 종료 · manager가 storage/background service 소유 · core-edge-8

ARTEX는 승인된 보안 작업을 하나의 장기 태스크로 저장하고, LLM planner가 탐색 의도를 만들며, 여러 worker가 도구를 실행한 결과를 자산·사실·finding·증거로 되돌려 다음 계획을 촉발하는 Go/Next.js 애플리케이션이다. 이 문서는 reference/src/ARTEX의 현재 구현을 운영자와 구현 검토자가 코드까지 추적할 수 있게 설명한다.

설명 기준 · upstream Autumn-27/ARTEX b55ceb1fdd84a813d77de09a06af83d323a81f85 · 이 저장소에 고정한 revision 408bf6b16c425fb615fba80a110a7bc4bf38b0fe · 2026-10-07 확인 시 upstream main과 같은 HEAD · ARTEX source 경로의 staged/unstaged 변경 없음.

확인 수준 · Go backend, PostgreSQL/SQLite 선언, Next.js client, scripts와 tests를 정적으로 대조했다. 서버·DB·proxy·실제 LLM/MCP/ScopeSentry는 실행하지 않았다. Norma 내부 loop는 ARTEX가 options를 구성하고 event를 수집하는 경계까지만 이 문서가 소유한다. 소스 기준

이 문서가 답하는 질문

질문	독립 진입
태스크가 어떻게 목표·의도로 분해되고 끝나는가?	태스크 탐색 루프
자산을 어떻게 가져오고 scope·coverage와 연결하는가?	자산·scope·coverage
finding과 HTTP 증거는 어떻게 함께 확정되는가?	Finding과 증거
사람이 실행 중 무엇을 관찰·수정·질문할 수 있는가?	사람 개입과 보조 실행
Planner/Worker/Main/Reporter가 어떤 runtime을 쓰는가?	에이전트 런타임
tool·skill·MCP·승인은 어디서 조립되고 강제되는가?	도구와 정책
어떤 저장소와 background loop가 상태를 소유하는가?	저장·서비스 모듈
모든 DB 객체와 정확한 SQL 소비·복합 제약을 직접 찾으려면?	데이터 모델 · production access · table-level 제약
모든 HTTP operation을 직접 찾으려면?	HTTP·UI 계약
설정·환경변수·파일의 우선순위는?	설정·파일 계약
언어·프레임워크·외부 의존은 어디에 쓰이는가?	기술과 의존성
인증·scope·egress·finding 신뢰의 실제 경계는?	보안·승인 경계
설치·업데이트·archive·복구의 완료 조건은?	운영

한 화면 시스템 지도

그림 크게 보기

Mermaid 원문

flowchart LR
  Human[운영자 / Browser] -->|HTTP·SSE| API[Go API + embedded UI]
  API --> Manager[Manager / Task registry]
  Manager --> PG[(PostgreSQL\n업무 상태 51 tables)]
  Manager --> Engine[Task Engine]
  Engine --> Planner[Planner]
  Planner -->|intent| Frontier[(Persistent frontier)]
  Frontier --> Worker[Worker pool]
  Human --> Main[Task Main Agent / Chat]
  Worker --> Norma[Norma sessions]
  Planner --> Norma
  Main --> Norma
  Norma --> Tools[Built-in · custom · Skill · MCP]
  Tools --> Proxy[Recording proxy]
  Proxy --> Target[허용 대상]
  Proxy --> Traffic[(Traffic SQLite + blobs)]
  Tools --> External[LLM · MCP · Search · ScopeSentry]
  Worker -->|asset · fact · finding| PG
  Traffic --> Evidence[Evidence CAS + PG bindings]
  Evidence --> PG
  PG --> Reporter[Reporter · Retest · Notify]
  Reporter --> Human

  click Engine "features/task-exploration.md#feedback-loop" "태스크 실행 루프"
  click Planner "modules/agent-runtime.md#planner-session" "Planner 세션"
  click Worker "modules/agent-runtime.md#worker-session" "Worker 세션"
  click Tools "modules/tool-policy.md#assembly" "도구 조립"
  click Proxy "features/findings-evidence.md#traffic-evidence" "트래픽 기록"
  click PG "contracts/data-model.md#postgres-map" "PostgreSQL 지도"
  click API "contracts/http-ui.md#route-families" "API 지도"
  click Reporter "features/findings-evidence.md#downstream" "후속 처리"

텍스트 경로: 운영자는 API로 태스크를 만들고, Manager가 PostgreSQL 상태와 Engine을 결합한다. Planner는 graph를 읽어 intent를 추가하고 worker는 DB frontier를 claim한다. 각 agent는 Norma session에서 허용된 tool을 호출한다. 결과는 PostgreSQL과 traffic/evidence 저장소에 남아 planner·reporter·retest·notification의 입력이 된다. Manager 근거 Engine 근거 조립 근거

완료와 확인의 경계

상태	코드가 보장하는 범위	남는 판단
goal `met`	planner가 같은 exploration의 fact/finding을 `prove_goal`로 연결	독립 검증자가 목표를 승인했는가
intent `done`	worker session이 정상 terminal reason으로 끝나고 writeback을 마침	그 공격 방향을 충분히 소진했는가
intent `blocked`	실행 오류나 provider/tool 문제로 계속하지 못함	대상에 취약점이 없는가
intent `exhausted`	turn/runtime 예산을 소진	추가 탐색 가치가 없는가
finding node `confirmed`	finding row·graph node·선택 evidence binding transaction이 commit	exploit 재현·scope·severity·중복이 검증됐는가
task `done`	goal proof가 모두 충족되거나 goal 없는 frontier가 종료 조건에 도달	scope 전체 coverage가 완전한가
archive `archived`	package와 DB archive 상태가 background worker 기준 완료	전체 인스턴스 backup과 복구가 가능한가

deadline에 도달하면 새 claim과 일반 planning을 막고 inflight writeback을 기다린 뒤 final planning round를 수행한다. HTTP 202나 queue row 생성은 background 작업 완료가 아니다. Engine timeout Archive worker

영역별 문서

축	설명 진입	코드/계약 진입
태스크 탐색	부트스트랩→재계획→종료	`server/engine.go`, `agent/planner.go`, `agent/worker.go`
자산·scope	수집→정규화→gate→coverage	`db/assets.go`, `db/task_scope.go`, `server/sync_scopesentry.go`
결과·증거	fact/finding→snapshot→report/retest	`db/finding_traffic.go`, `evidence/store.go`, `traffic/traffic.go`
사람 개입	main chat·steer·side question·trigger	`agent/mainagent.go`, `server/side_questions.go`
Agent runtime	역할·provider·context	ARTEX↔Norma boundary
Tool policy	catalog·visibility·deferred·intercept	built-in/custom/MCP/Skill/Guard
저장·service loop	store ownership·scheduler·notifier	PostgreSQL/SQLite/files/background loops
HTTP·Web	router·auth·SSE·UI consumer	261 registered operations + Next.js routes
HTTP provider	source file×path family 구현 지도	58 provider group → 261 handlers
DB	독립 객체 지도	PostgreSQL 551개 field 의미 + 정확한 production SQL 소비 + 24개 table-level 제약 + Traffic SQLite 21개 field
API	독립 operation 지도	등록 261 operations + 요청·응답 semantic
Web 화면	27개 화면→API·SSE 소비	27 page entries + 4 SSE endpoints
설정	JSON/env/DB settings/files	우선순위와 소비자
기술	runtime·dependency 지도	`go.mod`, `package-lock.json`, manifests
경계	인증·scope·egress·audit	강제점과 fail-open 조건
운영	시작·업데이트·archive·복구	실제 실행은 미검증

먼저 알아야 할 미확인 사항

모든 outbound destination을 task scope와 대조하는 단일 egress gateway는 확인되지 않았다. asset/intent gate와 tool intercept가 적용되지 않는 직접 네트워크 경로는 별도로 통제해야 한다.
report_finding의 confirmed는 writeback 상태다. 증거 bytes의 provenance와 취약점 결론의 타당성은 서로 다른 검증 대상이다.
handler registry는 261개 operation을 제공하지만 versioned OpenAPI/schema는 없다. 이 문서는 inline decoder·직접 응답/error를 field 수준으로 전수 추적하며 helper·derived response·비동기 효과가 남은 operation은 P/U로 표시한다. code-first handler/DTO가 최종 권위다.
schema.sql 외에 startup이 best-effort로 만드는 llm_records와 llm_usage가 있다. core server가 떠도 두 ledger가 없을 수 있으므로 실제 DB 적용 상태를 별도로 확인한다.
Next.js frontend는 static export와 embedded build를 전제로 하지만 browser 권한·reverse proxy·SSE buffer·cookie 보안은 배포 설정에 따라 달라진다.
upstream README의 사용 제한과 AGPL-3.0의 법적 관계는 이 기술 문서가 판단하지 않는다. 사용 경계

전체로 돌아가기 · Markdown 원본