Sanctum `contracts/` 폴더 역할 향상 보고서

보고서 목적

이 보고서는 Sanctum LLM 운영 모델에서 contracts/ 폴더를 어떤 권위로 다뤄야 하는지 결정하기 위한 문서다. 핵심 결론은 contracts/가 canonical contract SSOT이지만 worker 실행 문맥 전체를 담는 장소는 아니라는 것이다. 이 보고서는 그 결론을 서비스별 작업 경계, proposal 절차, diff guard 기준으로 확장한다.

핵심 결론

contracts/는 Sanctum의 서비스 간 계약을 담는 canonical SSOT다. 여기에는 API request/response schema, event/message payload, protocol invariant, error semantics, retry expectation, compatibility rule, generated client/source rule, e2e acceptance condition이 들어갈 수 있다.

하지만 contracts/는 서비스 worker의 작업 방식, build/test/local run 명령, write/read/propose-only boundary, Codex 또는 discord-codex-bot runtime 규칙, Graphify refresh 정책, RAG indexing 정책, LLM 임시 요약, secret, credential, private key, raw token을 담는 장소가 아니다.

권장 모델은 명확하다. contracts/는 계약 사실을 보관하고, service AGENTS.md와 llm-context/는 worker 실행 문맥을 보관한다. Graphify와 RAG는 contracts/를 찾는 데 도움을 줄 수 있지만 contract truth를 대체하지 않는다.

원본 문서의 주요 내용

wallet-api에서 kms-api로 가는 key operation request/response, wallet-api에서 hd-manager로 가는 derivation request, hd-manager에서 mpc-manager-rs로 가는 MPC operation contract, mpc-manager-rs와 party-node-rs 사이의 party coordination message는 canonical contract 후보다.

service llm-context/contracts.md는 복제 문서가 아니라 mapping 문서여야 한다. canonical contract 목록, 코드 사용 위치, worker permission, handoff route, required validation을 담아야 하며 schema field를 장문으로 복사하면 안 된다.

Sanctum 적용 해석

wallet-api worker는 contracts/를 read-only로 보는 것이 기본이다. request validation, response serialization, downstream adapter behavior가 바뀌면 먼저 service contracts.md에서 canonical contract를 찾고 원문을 직접 읽어야 한다. 계약 자체가 문제라면 contract change proposal을 작성해 root/e2e agent 또는 contract owner에게 넘긴다.

kms-api worker는 key operation과 signing boundary 때문에 더 엄격한 절차가 필요하다. error code, retry semantics, permission expectation이 바뀌면 wallet-api consumer impact와 migration 필요성을 proposal에 포함해야 하며 secret 또는 raw key material은 어떤 계약 문서에도 포함하지 않는다.

hd-manager worker는 derivation/MPC 연결 contract를 확인해야 한다. 내부 refactor는 service-local로 처리할 수 있지만 wallet creation, account recovery, signing, MPC session과 연결되는 contract 변경은 root/e2e 검증 대상이다.

mpc-manager-rs와 party-node-rs는 protocol compatibility가 핵심이다. Rust 내부 타입 변경이 external payload 또는 session state transition에 영향을 주면 canonical contract 변경 proposal이 필요하다.

운영 판단

Worker	`contracts/` 기본 접근	기본 write 권한	계약 변경 필요 시
`wallet-api`	read	no	proposal 후 owner 또는 root/e2e handoff
`kms-api`	read	no	key/signing contract proposal, wallet impact 표기
`hd-manager`	read	no	derivation/MPC contract proposal
`mpc-manager-rs`	read	no	MPC session/protocol proposal
`party-node-rs`	read	no	party protocol proposal, manager impact 표기
root/e2e agent	assigned read/write	explicit scope only	cross-service diff와 e2e 검증 담당

service worker가 contracts/를 직접 수정할 수 있는 예외는 작업 scope와 approval record에 명시되어야 한다. diff guard는 변경 파일이 allowlist 안에 있는지, affected service context가 갱신되었는지, 관련 테스트 또는 e2e handoff가 기록되었는지 확인해야 한다.

리스크와 가드레일

contracts/ 비대화: runbook, LLM 요약, 조사 메모가 들어가면 canonical contract와 추론이 섞인다.
service contract 복제: service contracts.md가 schema를 복사하면 drift가 발생한다.
Graphify authority 오해: Graphify는 관련 contract 후보를 찾을 수 있지만 contract fact나 write authorization을 결정하지 않는다.
RAG chunk 오해: RAG 결과는 partial/stale일 수 있으므로 최종 판단 전 원문을 직접 읽는다.
Codex App boundary 오해: workspace separation은 hard boundary가 아니며 runtime write allowlist, diff guard, approval scope가 필요하다.
계약 변경의 테스트 부족: affected service list와 e2e acceptance condition 없이 merge-ready로 보면 안 된다.

실행 체크리스트

contracts/ 문서의 허용 정보 유형을 명시한다.
service llm-context/contracts.md에서 계약 내용 복제를 제거하고 mapping으로 바꾼다.
각 service worker의 contract 접근을 기본 read-only로 둔다.
contract change proposal template을 제공한다.
proposal에는 canonical file, problem, proposed change, impacted services, required validation, migration/backward compatibility를 포함한다.
root/e2e agent가 contract impact와 e2e flow 검증을 담당하게 한다.
Graphify/RAG 결과는 canonical file direct read 전의 후보로만 사용한다.
diff guard에서 contracts/** 변경이 approval scope에 포함되어 있는지 확인한다.

Sanctum contracts/ 폴더 역할 향상 보고서