<a id="overview"></a>
# ARTEX 현재 시스템 지도

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를 수집하는 경계까지만 이 문서가 소유한다. [소스 기준](evidence:source-readme)

<a id="questions"></a>
## 이 문서가 답하는 질문

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

<a id="system-map"></a>
## 한 화면 시스템 지도

```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 근거](evidence:manager) [Engine 근거](evidence:engine) [조립 근거](evidence:assembly-server)

<a id="completion-boundary"></a>
## 완료와 확인의 경계

| 상태 | 코드가 보장하는 범위 | 남는 판단 |
|---|---|---|
| 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](evidence:engine-timeout) [Archive worker](evidence:task-archive-server)

<a id="area-map"></a>
## 영역별 문서

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

<a id="important-unknowns"></a>
## 먼저 알아야 할 미확인 사항

- 모든 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의 법적 관계는 이 기술 문서가 판단하지 않는다. [사용 경계](operations.md#source-use-boundary)