보고서 목적
이 보고서는 Sanctum에서 Graphify artifact를 CI에서 생성, 검증, 보관, 소비하는 방식을 결정한다. 핵심은 Graphify artifact를 canonical truth로 승격하지 않으면서도 worker와 root/e2e agent가 stale graph에 속지 않도록 SHA 기반 freshness와 clean build 정책을 세우는 것이다.
핵심 결론
Sanctum의 Graphify CI 목표는 graph.json이 진실임을 보장하는 것이 아니다. 어떤 source Git SHA, scan root, generator version, ignore policy 기준으로 만들어졌는지 명확히 하고 stale graph를 기준으로 worker가 잘못 판단하지 않게 하는 것이다.
- PR: non-blocking Graphify validation으로 시작한다.
- main: merge 후 clean full build를 실행하고 SHA-tagged artifact로 보관한다.
- nightly: clean rebuild, quality report, drift audit을 실행한다.
- incremental: local/PR 빠른 피드백용 disposable cache로만 사용한다.
- canonical derived artifact 승격 기준은 clean full build다.
- write authorization, contract truth, test authority, canonical documentation authority는 Graphify CI가 소유하지 않는다.
원본 문서의 주요 내용
PR check는 merge gate가 아니라 review aid다. PR head SHA에서 graph build를 실행하고 base/main artifact와 비교해 drift summary를 만들며 contracts/ 변경 시 affected service 후보를 보여준다. Main check는 clean full build와 artifact promotion을 담당하고 metadata에는 source_git_sha, scan_root, build_mode, generator_version, generated_at, dirty_tree_allowed=false, source_truth_policy=derived_index_not_ssot가 있어야 한다. Nightly check는 orphan node, deleted file reference, missing service map, contracts mapping 누락 후보, semantic extraction failure, skipped file list를 수집한다. Incremental build는 canonical artifact가 될 수 없다.
Sanctum 적용 해석
Root/e2e agent는 main clean graph로 e2e impact 후보를 만들 수 있고, wallet-api worker는 PR graph로 kms-api와 contracts read 후보를 좁힐 수 있다. 그러나 artifact가 stale하면 wrong handoff, missing test, boundary confusion이 발생한다. wallet-api, kms-api, hd-manager, Rust MPC, contracts, root/e2e agent는 각각 affected 후보와 drift report를 소비하되 contract truth는 canonical content와 review process에서 결정한다.
운영 판단
Phase 0 manual baseline, Phase 1 PR non-blocking check, Phase 2 main clean artifact, Phase 3 nightly audit, Phase 4 service graph experiment, Phase 5 guarded context pack update proposals 순서로 강화한다. PR은 non-blocking으로 시작하고 blocker 전환은 clean full build 안정성, failure taxonomy, owner triage 절차 이후에만 검토한다.
리스크와 가드레일
- Graphify artifact가 SSOT로 오해될 수 있다.
- branch switch/rebase 후 stale graph가 남을 수 있다.
- rename/delete/move drift가 incremental cache에 남을 수 있다.
- shared
contracts/변경이 service graph에 반영되지 않을 수 있다. - Graphify check가 noisy blocker가 될 수 있다.
- Graphify relation이 write boundary로 오해될 수 있다.
가드레일은 artifact metadata에 derived index 성격을 명시하고, freshness를 commit SHA 기준으로 판정하며, main/nightly artifact는 clean full build만 승격하고, incremental artifact는 canonical 근거로 제공하지 않는 것이다. Write scope 결정은 runtime allowlist와 diff guard에 맡긴다.
실행 체크리스트
- PR check는 non-blocking으로 실행하고 PR head SHA artifact와 drift summary를 남긴다.
- Main merge 후 clean full build를 실행하고 SHA-tagged storage에 저장한다.
- Nightly clean rebuild와 node/edge drift, deleted file reference, shared contracts 영향 후보, merged graph consistency를 확인한다.