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

Norma는 Go 호스트가 모델, prompt, tool, 권한 정책과 저장 위치를 주입하면 model 호출과 tool-use 반복을 실행하는 **agent harness SDK**다. 자체 버그바운티 제품이나 독립 daemon이 아니며, scope·rate·finding·evidence의 업무 의미는 제공하지 않는다.

> **고정 로컬 소스 기준** · 이 저장소 commit `be49d2d8ee39c98310b6771c4ca8e64f87b11a87`의 `reference/src/Norma`
>
> **upstream 출처** · `Autumn-27/Norma` tag `v0.4.3`, commit `320ae32989da97dd91469bb89164cbfe87d83d5d`를 2026-10-06 KST에 가져온 210-file snapshot. 두 기준의 연결은 저장소의 `reference/SOURCE.md`에 있다.
>
> **현재 source 상태** · `reference/src/Norma`의 등록 파일은 고정 root commit의 bytes와 같고 source-tree dirty 변경이 없다.
>
> **확인 수준** · 코드와 테스트를 대조했다. 2026-10-07 KST의 `go test ./... -count=1`은 일부 `llm`, `noa`, `noaadapter` 테스트 때문에 실패했다. 실제 LLM API, MCP process, network target, 장시간 session은 실행하지 않았다. [README 근거](evidence:source-readme) [모듈 근거](evidence:go-module)

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

| 질문 | 독립 진입 |
|---|---|
| Prompt가 model과 tool을 어떤 상태 전이로 반복하는가? | [Session 실행](runtime/session-loop.md#prompt-lifecycle) |
| tool의 입력·권한·hook·실행 순서와 실제 보안 경계는 무엇인가? | [도구와 권한](runtime/tools-and-permissions.md#permission-pipeline) |
| provider, context, extension과 coordination 기능은 어떻게 결합하는가? | [기능 지도](features/README.md#feature-map) |
| package별 책임과 제공·소비 관계는 무엇인가? | [모듈 지도](modules/README.md#module-map) |
| 종료·scheduler·retry·compression 판정 규칙은 무엇인가? | [규칙과 알고리즘](rules-and-algorithms.md#rule-index) |
| embedding API와 파일·환경·CLI 계약은 무엇인가? | [계약과 설정](contracts/README.md#contracts-overview) |
| 공개 identifier/signature와 정확한 설정 field는 무엇인가? | [공개 API 색인](reference/public-api-runtime.md#overview) · [설정 색인](reference/configuration.md#overview) |
| 정적 tool 30개와 outbound operation, on-disk schema는 무엇인가? | [Tool 색인](reference/tools.md#overview) · [외부 operation](reference/external-operations.md#overview) · [파일 schema](reference/persistence-schemas.md#overview) |
| host가 준비·관측·종료해야 할 것은 무엇인가? | [통합과 운영](operations-and-integration.md#embedding) |

<a id="system-map"></a>
## 책임과 외부 경계

```mermaid
flowchart LR
  H[Host application] -->|Options + Prompt| S[agentcore Session]
  S -->|QueryInput| Q[harness loop]
  Q <-->|normalized completion| L[LLM provider]
  Q -->|validated and allowed call| T[tool registry]
  T -->|filesystem / process / network| E[External effects]
  Q -->|project or compact| C[Context manager]
  S -->|append / resume| P[(Transcript and optional files)]
  Q -->|events + terminal| H

  click S "runtime/session-loop.md#session-construction" "Session 조립"
  click Q "runtime/session-loop.md#prompt-lifecycle" "Prompt 반복"
  click L "runtime/extensions-and-coordination.md#providers" "Provider 경계"
  click T "runtime/tools-and-permissions.md#tool-contract" "Tool 계약"
  click C "runtime/context-and-resume.md#state-ownership" "Context 상태"
  click P "contracts/README.md#persisted-files" "파일 계약"
```

| Norma가 소유하는 책임 | 외부 경계와 host 책임 |
|---|---|
| provider-neutral message/tool loop, event stream, terminal reason | model endpoint·credential·모델 정책·실제 비용 |
| schema 검사, permission decision, hook 호출, tool scheduling | filesystem/process/network sandbox·target scope·global rate |
| built-in compaction 또는 교체 가능한 `Compactor`/`ContextView` | 원본 evidence·품질 평가·장기 run state의 권위 원본 |
| JSONL transcript, memory/Noa 파일 primitive | 무결성·암호화·backup·미결 side effect reconciliation |
| subagent와 coordinator primitive | 격리·lease·dedup·child budget·합산 성공 기준 |

Norma의 최소 실행 단위는 `Session.Prompt`다. Session은 conversation과 누적 usage를 보유하고, Prompt마다 생성되는 `harness.loop`가 요청 view, provider 호출, tool 실행과 종료를 맡는다. [Prompt 근거](evidence:agentcore-prompt) [loop 근거](evidence:harness-query)

<a id="completion-boundary"></a>
## 완료의 실제 의미

최종 `KindResult`의 `TerminalReason`이 loop 종료 이유다. `completed`는 tool call 없는 model 응답으로 loop가 끝났다는 뜻이며 목표 달성이나 side effect 검증을 뜻하지 않는다. `agentcore.Run`, `subagent.Run`, `coordinator.RunParallel`은 terminal reason을 구조적으로 반환하지 않고 `Terminal.Err`만 상위 error로 사용하므로 `max_turns`와 `timeout`이 nil-error 결과처럼 보일 수 있다. 장기 작업 host는 `Session.Prompt`를 끝까지 소비하고 terminal 전체를 저장해야 한다. [event 계약](evidence:harness-event) [Run 근거](evidence:agentcore-run)

| reason | 현재 생성 경로의 의미 |
|---|---|
| `completed` | 일반 종료 또는 recovery 이후 최종 응답 |
| `model_error` | provider 실패 또는 reactive recovery 뒤 재실패 |
| `aborted_streaming` / `aborted_tools` | parent context 취소를 stream/tool 단계에서 관찰 |
| `prompt_too_long` | overflow recovery가 retry view를 만들지 못함 |
| `stop_hook_prevented` | Stop hook이 continuation을 금지 |
| `max_turns` / `timeout` | main tool-turn 수 또는 경계에서 관찰한 시간 budget 소진 |

`blocking_limit`, `image_error`, `hook_stopped`는 선언돼 있지만 이 snapshot의 main harness 경로에서 생성되는 지점은 확인되지 않았다. consumer가 event iterator를 일찍 끊으면 terminal event와 Session commit 자체가 생략될 수 있다.

## 문서 지도

| 탐색 축 | 시작점 | 포함 내용 |
|---|---|---|
| 기능 | [기능 지도](features/README.md#feature-map) | trigger→입력→판정→상태·효과→완료·실패 |
| 모듈 | [모듈 지도](modules/README.md#module-map) | package 책임·진입점·제공/소비 계약 |
| 규칙 | [규칙 색인](rules-and-algorithms.md#rule-index) | permission, scheduler, 종료, retry, context |
| 계약 | [계약과 설정](contracts/README.md#contracts-overview) | public Go 타입, event, file, CLI, 환경변수 |
| 세부 참조 | [Public API](reference/public-api-runtime.md#overview) · [설정](reference/configuration.md#overview) · [Tool](reference/tools.md#overview) | 전수 identifier/signature, field default, 설치/효과 |
| 운영 | [통합과 운영](operations-and-integration.md#embedding) | 준비·실행·관측·중단·재검증 |

<a id="test-status"></a>
## 2026-10-07 재검증 상태

`go test ./... -count=1`은 `go1.26.3 linux/amd64`에서 종료 코드 1을 반환했다. `agentcore`, `compaction`, `coordinator`, `harness`, `hook`, `mcp`, `memory`, `permission`, `plan`, `skill`, `subagent`, `tool`, `transcript` package는 통과했다.

| 실패 package | 관찰한 실패 |
|---|---|
| `llm` | `TestDoStreamHonorsConfiguredRetries`가 nil `HTTPClient` dereference로 panic |
| `noa` | adaptive growth, suppression release 기대 2건 |
| `noaadapter` | mostly-competent/partial model boundedness, overflow learning, tiering을 포함한 5개 top-level test |

`TestTierTwoIsUnreachableOnSmallWindows`는 현재 tier 2가 실제 만들어져 과거 limitation 기대가 깨지는 형태다. 나머지 실패와 함께 전체 suite가 green이라는 주장은 할 수 없다. 상세 한계는 [Noa 검증](modules/noa.md#limits), 실행 절차는 [재검증](operations-and-integration.md#verification)에 있다.

<a id="art-ex-boundary"></a>
## ARTEX와의 정확한 경계

ARTEX snapshot의 `go.mod`가 요구하는 `github.com/Autumn-27/norma v0.4.3`은 이 문서의 upstream commit과 일치한다. ARTEX는 task/frontier, asset, finding, evidence와 proxy를 소유하고 Norma `Options`와 `Prompt`를 호출한다. Norma는 해당 worker 안의 model/tool session runtime이다.

```mermaid
flowchart LR
  A[ARTEX control plane] -->|provider, tools, prompt, policy| N[Norma Session]
  N -->|events, terminal, tool results| A
  A --> D[(ARTEX DB and traffic evidence)]
  N --> F[(Norma transcript and optional state)]
```

ARTEX의 scope·finding writeback을 Norma 기능으로 읽거나, Norma의 permission·context·resume 한계를 ARTEX가 자동 해결한다고 가정하면 안 된다.

<a id="known-gaps"></a>
## 먼저 확인할 한계

- `WorkingDir`는 path sandbox가 아니며 absolute path, `..`, symlink를 격리하지 않는다.
- `MaxDuration`은 model stream을 중간에 끊는 hard deadline이 아니다. caller context deadline이 별도로 필요하다.
- model에게 schema를 숨기는 것과 registry 실행을 금지하는 것은 다르다. deferred/settlement 도구에는 우회 경계가 있다.
- transcript는 복구용 JSONL이며 tamper-evident ledger가 아니다. writer error는 Session terminal로 자동 전달되지 않는다.
- resume은 conversation을 복원하며 tool effect, background process, permission/plan/unlock 상태를 reconcile하지 않는다.
- hook rewrite 입력은 schema·permission을 다시 통과하지 않고, skill 본문은 system policy가 아니라 user message로 들어간다.
- 이 snapshot에는 `LICENSE` 파일이 없다. 소스 재사용·재배포 권리는 별도 확인 대상이다.

각 조건의 단계와 근거는 [도구 실행](runtime/tools-and-permissions.md), [context와 resume](runtime/context-and-resume.md), [운영 경계](operations-and-integration.md)에 연결돼 있다.