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 근거 모듈 근거

이 문서가 답하는 질문

질문	독립 진입
Prompt가 model과 tool을 어떤 상태 전이로 반복하는가?	Session 실행
tool의 입력·권한·hook·실행 순서와 실제 보안 경계는 무엇인가?	도구와 권한
provider, context, extension과 coordination 기능은 어떻게 결합하는가?	기능 지도
package별 책임과 제공·소비 관계는 무엇인가?	모듈 지도
종료·scheduler·retry·compression 판정 규칙은 무엇인가?	규칙과 알고리즘
embedding API와 파일·환경·CLI 계약은 무엇인가?	계약과 설정
공개 identifier/signature와 정확한 설정 field는 무엇인가?	공개 API 색인 · 설정 색인
정적 tool 30개와 outbound operation, on-disk schema는 무엇인가?	Tool 색인 · 외부 operation · 파일 schema
host가 준비·관측·종료해야 할 것은 무엇인가?	통합과 운영

책임과 외부 경계

그림 크게 보기

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 근거 loop 근거

완료의 실제 의미

완료의 실제 의미 · 관계

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

구현 담당 · agentcore와 harness · terminal event가 Prompt completion을 뜻하는 경계 구현 · harness-event

전체 관계 1개 · 종류 선택·관계도

최종 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 계약 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 자체가 생략될 수 있다.

문서 지도

탐색 축	시작점	포함 내용
기능	기능 지도	trigger→입력→판정→상태·효과→완료·실패
모듈	모듈 지도	package 책임·진입점·제공/소비 계약
규칙	규칙 색인	permission, scheduler, 종료, retry, context
계약	계약과 설정	public Go 타입, event, file, CLI, 환경변수
세부 참조	Public API · 설정 · Tool	전수 identifier/signature, field default, 설치/효과
운영	통합과 운영	준비·실행·관측·중단·재검증

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 검증, 실행 절차는 재검증에 있다.

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가 자동 해결한다고 가정하면 안 된다.

먼저 확인할 한계

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 파일이 없다. 소스 재사용·재배포 권리는 별도 확인 대상이다.

각 조건의 단계와 근거는 도구 실행, context와 resume, 운영 경계에 연결돼 있다.

이동한 문서 주소

등록된 주소만 자동 이동합니다. 아래에서 새 위치를 선택할 수 있습니다.

전체로 돌아가기 · Markdown 원본