Files
lolympus-agent/docs/resolution-hash-sunset-procedure.md
T

3.5 KiB

Supervisor Resolution Hash Sunset Procedure

Last verified: Iter8 implementation branch, 2026-05-18.

Supervisor resolution은 현재 두 곳에 기록된다.

  • Audit stream: lolympus-agent:review-resolutions
  • Compatibility hash: lolympus-agent:review-resolved:{reviewId}

Hash는 기존 read path와 rollback을 위한 compatibility layer다. 실제 sunset은 최소 1-2개월 운영 후 아래 조건을 만족할 때만 진행한다.

선결 조건

  • Dual-write 운영 기간이 2개월 이상이다.
  • Stream과 hash의 resolution 데이터 일치율이 100%다.
  • review:list, review:show, review:resolve, review:stats가 stream 기반 확인으로 대체 가능한 상태다.
  • 최근 2주간 supervisor resolution 관련 incident가 없다.
  • Sunset 실행 전 main branch의 전체 회귀가 통과한다.

권장 점검:

npm run review:stats
npm run review:list -- --include-resolved --limit=20
npm run typecheck
npm test

필요하면 별도 consistency script를 만든다.

scripts/verify-dual-write-consistency.ts

이 script는 lolympus-agent:review-resolutions의 최신 resolution과 lolympus-agent:review-resolved:{reviewId} hash를 비교해 divergence를 출력해야 한다.

Sunset 단계

Step 1. Hash write 중단

src/skills/supervisor/review-queue.ts의 resolveSupervisorReview()에서 setHash()와 expireKey() 호출을 제거한다. Stream append는 유지한다.

검증:

npm run typecheck
npm test -- src/skills/supervisor/review-queue.test.ts src/operations/cli.test.ts

Rollback: 해당 commit revert. 기존 hash TTL 동안 read fallback은 유지된다.

Step 2. Stream-only write로 1개월 운영

새 resolution은 stream에만 쌓이고, 기존 hash는 TTL까지 남는다. 이 기간 동안 review:list/show/stats가 정상 동작하는지 확인한다.

관찰 항목:

  • unresolved item이 비정상적으로 늘지 않는가
  • resolution history가 누락되지 않는가
  • 운영자가 review:show에서 이전 resolution을 확인할 수 있는가

Rollback: setHash()와 expireKey()를 복구한다.

Step 3. Hash read fallback 제거

getSupervisorReview()와 listSupervisorReview()에서 hash lookup을 제거하고, resolution stream join으로만 상태를 계산한다.

검증:

npm run review:list -- --include-resolved --limit=5
npm run review:stats
npm test -- src/skills/supervisor/review-queue.test.ts src/operations/cli.test.ts

Rollback: hash lookup 코드를 복구한다. Step 1 이후 새 데이터는 hash에 없으므로 rollback 전에 stream 기반 backfill이 필요한지 판단한다.

Step 4. 기존 hash 정리

TTL이 짧으면 자연 만료를 기다린다. 운영상 즉시 정리가 필요하면 cleanup script를 별도 PR로 만든다.

주의: cleanup script는 반드시 dry-run을 기본값으로 둔다.

Step 5. 상수와 문서 정리

SUPERVISOR_RESOLVED_HASH_PREFIX 상수와 관련 env/문서 언급을 제거한다. docs/service-evaluation-operations.md의 Redis key schema도 갱신한다.

검증:

rg "review-resolved|SUPERVISOR_RESOLVED_HASH_PREFIX" src docs
npm run lint
npm test

Rollback 원칙

  • Step 1-2는 단순 revert로 rollback 가능하다.
  • Step 3 이후 rollback은 stream-to-hash backfill 필요 여부를 먼저 판단한다.
  • Step 4 cleanup 이후에는 hash 데이터 복구를 기대하지 않는다.
  • 모든 단계는 작은 PR로 나누고, 각 PR은 독립 revert 가능해야 한다.