toki/iop

toki 6c52e7b56f docs(agent-ops): 검증 게이트를 최소화한다

누적된 잠금·승인·증거 체인이 구현과 완료를 반복 차단해 작업 비용을 키웠다. 보안·데이터 손상·명시적 외부 의존성만 차단 조건으로 남기고 로드맵과 스킬의 기본 흐름을 단순화한다.

2026-08-15 16:54:00 +09:00

SDD Decision Notes

검토 대상

결정 필요: 요청별 request ledger의 canonical 저장 책임을 Edge-local store, Control Plane store, 또는 Edge 원본 + Control Plane replica 중 어디에 둘지 결정해야 한다.
추천안: Edge를 원본으로 두고 Control Plane은 조회/export용 replica 또는 relay view로 시작한다.
대안: Control Plane을 원본으로 두거나, MVP에서는 Edge-local CLI 조회만 제공한다.
영향: source of truth, 장애 복구, 다중 Control Plane 전환, export API, 저장소 schema 경계에 영향을 준다.
적용 위치:
- SDD: Source of Truth, Interface Contract, Acceptance Scenarios
- Milestone: storage-query, 결정 사항

결정 필요: provider-reported, estimated, mixed, unavailable usage source를 운영 UI와 export에서 어떤 기본 표현으로 보여줄지 결정해야 한다.
추천안: 모든 token 필드에 source를 함께 저장하고, rollup에서는 provider-reported와 estimated를 기본적으로 분리해 표시한다.
대안: total token만 source를 표시하거나, estimated 값을 기본 rollup에 포함하지 않는다.
영향: provider 효율 비교, 사용자별 사용량 통계, 비용/성능 판단 정확도에 영향을 준다.
적용 위치:
- SDD: Interface Contract, Acceptance Scenarios
- Milestone: token-usage

결정 필요: provider가 hidden think/reasoning token을 보고하지 않는 경우 표시된 reasoning text 기반 추정치를 별도 필드로 허용할지 결정해야 한다.
추천안: provider-reported reasoning token만 canonical reasoning_tokens로 두고, 표시 reasoning text 기반 값은 reasoning_tokens_estimated처럼 별도 추정 필드로만 둔다.
대안: 추정치를 MVP에서 아예 제외하거나, output token에 합산한다.
영향: 모델/provider 비교, hidden reasoning 비용 추정, 사용자 로그 신뢰도에 영향을 준다.
적용 위치:
- SDD: Interface Contract
- Milestone: token-usage

결정 필요: prompt/response/reasoning 원문, preview, IOP request/route metadata, error detail의 기본 보관 범위와 redaction 정책을 결정해야 한다.
추천안: MVP 기본값은 원문 미보관, redacted preview와 IOP request/route metadata summary만 저장하고, raw payload export는 별도 opt-in으로 둔다.
대안: Edge-local에 raw payload를 짧게 보관하거나, 운영자 권한이 있으면 Control Plane에서 raw 조회를 허용한다.
영향: 보안, 개인 정보, 저장 비용, 디버깅 깊이, 사용자 신뢰에 영향을 준다.
적용 위치:
- SDD: Interface Contract, Acceptance Scenarios
- Milestone: log-redaction

결정 필요: 기존 RunEvent/runtime event schema를 확장할지, 별도 request ledger/audit event schema를 둘지 결정해야 한다.
추천안: runtime stream의 RunEvent는 실행 중 이벤트로 유지하고, 완료/관측용 request ledger record를 별도 schema로 둔다. 필요한 correlation 필드만 runtime event에 보강한다.
대안: RunEvent를 확장해 ledger까지 흡수하거나, audit event만 확장한다.
영향: proto 변경 범위, Edge/Node/Control Plane 책임 경계, 과거 로그 migration, client UI parsing에 영향을 준다.
적용 위치:
- SDD: Interface Contract, State Machine
- Milestone: migration-plan

결정 필요: tool-call argument, provider raw chunk, parser error detail을 preview/hash/raw capture 중 어떤 수준으로 보관하고 어떻게 redaction할지 결정해야 한다.
추천안: 기본값은 raw 원문 미보관, run_id 기준 판정 필드와 길이/hash/redacted preview만 저장하고, bounded raw capture는 명시적으로 켠 진단 모드에서만 허용한다.
대안: Edge-local에 짧은 raw chunk ring buffer를 두거나, tool-call arguments는 schema 기반 redaction 후 저장한다.
영향: tool-call 장애 분석 깊이, 민감 정보 노출, 저장 비용, 운영자 export 권한에 영향을 준다.
적용 위치:
- SDD: Interface Contract, Acceptance Scenarios
- Milestone: tool-call-trace, log-redaction