<a id="embedding"></a>
# 통합과 운영 경계

상위 경로: [Norma 시스템 지도](README.md#system-map) → 통합과 운영

Norma는 daemon이나 배포 서비스가 아니라 Go library다. host binary가 provider credentials, prompt, tools, permission UI, process/filesystem/network 경계, persistence와 shutdown을 소유한다. `cmd/agentcore`와 examples는 wiring 예시이며 production policy가 아니다. [README 근거](evidence:source-readme) [Session 구성](evidence:agentcore-newsession)

`go.mod`는 `go 1.26.3`을 선언해 README의 “Go 1.23+”와 다르다. 이 snapshot을 build/test할 때는 module directive를 기준으로 한다. module graph의 외부 entry 9개(직접 4, graph-only transitive 5), package 선택 여부와 examples 5개는 [dependency와 examples](reference/dependencies-and-examples.md#dependencies)에 있다. [module graph 근거](evidence:go-module-graph)

최소 embedding은 terminal을 보존하는 event loop까지 포함한다.

```go
sess := agentcore.NewSession(agentcore.Options{
    Provider:       provider,
    SystemPrompt:   []string{systemPrompt},
    Tools:          approvedTools,
    PermissionMode: permission.ModeDefault,
    CanUseTool:     approve,
    Transcript:     transcriptStore,
    SessionID:      safeRunID,
    MaxTurns:       40,
    MaxDuration:    30 * time.Minute,
})
defer sess.Close()

for ev, err := range sess.Prompt(runCtx, task) {
    if err != nil { return err }
    if ev.Kind == harness.KindResult {
        persistTerminal(ev.Terminal)
    }
}
```

<a id="configuration"></a>
## 구성 책임

| 영역 | Norma primitive | host가 준비·강제할 것 |
|---|---|---|
| model | adapters, retry/rate primitive | endpoint/model allowlist, secrets, total budget |
| prompt | ordered segments, dynamic boundary | policy version/digest, untrusted-data delimiting |
| action | registry, schema, permission/hook | target/resource scope, sandbox, idempotency, provenance |
| concurrency | safe/exclusive scheduler | global target rate, fairness, shared-state locking |
| context | built-in/custom/Noa | context quality eval, raw evidence, authoritative run state |
| persistence | transcript/memory/Noa files | integrity, encryption, migration, backup/reconciliation |
| delegation | subagent/coordinator | isolation, inheritance contract, per-child limits/accounting |
| completion | terminal reason/event | task success, retry/resume/stop policy |

trusted absolute paths에서 WorkingDir, SessionID, output/archive roots를 만들고 model/user text로 path를 직접 구성하지 않는다. credentials는 Bash/MCP child가 물려받는 전체 environment 대신 tool별 최소 환경으로 전달한다.

<a id="supported-environment"></a>
## 준비와 첫 실행

1. 고정 source root와 `go.mod`가 같은 snapshot인지 확인한다.
2. Go toolchain이 module directive를 지원하는지 `go version`으로 확인한다.
3. 사용하는 provider format의 endpoint/model/credential을 secret channel로 준비한다.
4. 최소 tool 목록과 permission mode/callback을 명시한다. nil Tools가 defaults를 넣는 점을 의도적으로 선택한다.
5. WorkingDir와 transcript/output/memory/Noa root를 trusted path로 만들고 권한·보존 정책을 적용한다.
6. caller context deadline, MaxTurns/Duration, model request rate와 target action rate를 각각 설정한다.
7. synthetic prompt와 read-only custom tool로 event/terminal/recording을 확인한 뒤 mutating capability를 연다.

첫 `Grep` 전에 `rg`를 image/PATH에 설치하거나 `NORMA_DISABLE_RIPGREP=1` 또는 `NORMA_RIPGREP_NO_INSTALL=1`을 설정한다. 아무 조치도 없고 `rg`가 없으면 읽기 전용·self-allow로 등록된 `Grep`이 permission callback 밖에서 `npm install -g @vscode/ripgrep`을 실행할 수 있으며, 이 bootstrap에는 context timeout/cancel이 없다. trigger와 silent fallback은 [Grep bootstrap operation](reference/external-operations.md#grep-bootstrap)에 있다. [구현 근거](evidence:ripgrep-bootstrap)

demo CLI를 로컬에서 build하는 정의 명령은 다음과 같다.

[CLI 근거](evidence:cli-main)

```bash
cd reference/src/Norma
go build -o agentcore ./cmd/agentcore
```

실제 provider 호출은 credential과 비용·외부 effect를 발생시키므로 문서 생성 과정에서는 실행하지 않았다. flags, stdout/stderr, signal/EOF와 exit semantics는 [CLI 동작 계약](reference/cli.md#overview)에 있다.

<a id="shutdown"></a>
## 종료, 중단과 복구

`Session.Close`는 background task manager를 cleanup하지만 MCP stdio client는 별도 close가 필요하다. context를 무시하는 custom tool은 SDK가 timeout result를 만든 뒤에도 계속 실행할 수 있으므로 OS-level supervisor가 필요하다.

정상/비정상 종료에서 확인할 순서는 다음과 같다.

1. Prompt iterator의 terminal 수신 여부와 reason/error를 기록한다.
2. action broker에서 running/unknown actions를 표시하고 외부 effect를 조회한다.
3. background tasks, PTY sessions와 process groups를 중단한다.
4. MCP clients와 다른 host-owned resources를 닫는다.
5. transcript writer error, output spill, Noa state/archive warning을 확인한다.
6. 재개할 run에는 last durable state와 reconciliation 결과를 남긴다.

<a id="verification"></a>
## 이 snapshot의 재검증

2026-10-07 KST에 고정 local source에서 다음을 실행했다.

```bash
go test ./... -count=1
```

실행 환경은 `go1.26.3 linux/amd64`, 결과는 exit 1이다. package별 결과와 8개 top-level failure/panic은 [홈의 테스트 상태](README.md#test-status)에 기록했다. 동적 LLM/MCP/network/long-session 실행은 하지 않았다.

문서 설명의 정적 risk 중 별도 reproduction이 필요한 항목은 다음과 같다.

- stream error/consumer 중단과 이미 시작한 orphan tool effect
- hook rewrite 뒤 schema/permission bypass
- untrusted SessionID/path traversal과 cleanup 범위
- WebFetch proxy failure 뒤 direct-intended fallback과 environment proxy 재상속 분기
- hidden/deferred inner tool의 direct/wrapper authorization 차이
- context를 무시하는 tool의 timeout 이후 실행

<a id="adoption-boundary"></a>
## 현재 SDK 채택 경계

Norma가 현재 제공하는 재사용 가능한 primitive는 provider-neutral event loop, tool contract/scheduler, permission modes, replaceable context interface, transcript primitive와 extension adapters다. 다음 책임은 구현에 없으므로 host가 별도 소유해야 한다.

- 승인된 target scope, redirect/DNS와 rate를 실행 직전에 강제하는 broker
- action idempotency, before/after provenance와 immutable evidence
- asset/hypothesis/finding state와 duplicate suppression
- persistent frontier, lease, retry policy와 hard deadlines
- finding reproducibility와 human-review workflow
- agent별 filesystem/process/network isolation
- model/tool/child 전체 cost와 policy-version accounting

이 경계는 미래 아키텍처 제안이 아니라 현재 public types와 실행 경로에서 확인되는 책임 분리다. Norma permission/hook만으로 위 control-plane 보장을 주장할 수 없다.

<a id="source-use-boundary"></a>
## 소스 사용 경계

고정 Norma tree에는 `LICENSE`, `LICENSE.*`, `COPYING` 파일이 없다. 공개 저장소이고 ARTEX가 Go module로 참조한다는 사실은 복제·수정·재배포 권리를 자동 부여하지 않는다. 이 snapshot은 분석 근거이며, implementation dependency나 파생 코드로 사용할 때 upstream 권리 조건을 별도로 확인해야 한다.