toki
31fada5d08
공식 리뷰가 지적한 두 가지 승인 경계 결함을 고친다. `plan_file`/`review_file`은
edge.yaml 디렉터리 기준 상대 경로만 허용하고 절대/빈 경로는 파일 접근 전에 거부한다.
필수 heading과 Review `PASS`는 부분 문자열이 아니라 정확한 단독 줄로 검증하며,
문서화된 placeholder를 제거한 뒤 남는 `{{`/`}}`를 거부해 문법을 닫는다.
리뷰가 존재한다고 기술했지만 실제로는 없던 회귀 근거를 추가한다. admission 시
고정된 effective 템플릿 쌍이 clone과 workspace 재검증을 통과하는지, refresh가
이미 승인된 요청이 아니라 새 요청에만 적용되는지, custom Review 템플릿이 내부
artifact만 바꾸고 caller 최종 출력은 그대로인지를 각각 확정 검증한다.
현재 문서도 실제 동작에 맞춘다. Edge 실행 spec의 낡은 Plan JSON Schema 서술을
direct PlanMD 검증으로 고치고, outer Anthropic 계약과 input spec에 템플릿이
Edge 내부 stage 입력일 뿐 caller 요청/응답 계약을 바꾸지 않음을 명시한다.
Refs: agent-task/single_request_plan_review_templates/PLAN-cloud-G08.md
50 lines
6 KiB
Markdown
50 lines
6 KiB
Markdown
---
|
|
spec_doc_type: index
|
|
status: 활성
|
|
---
|
|
|
|
# 구현 스펙 색인
|
|
|
|
## 목적
|
|
|
|
이 디렉터리는 IOP의 현재 구현을 빠르게 파악하기 위한 living spec이다.
|
|
AI agent가 작업 전에 읽는 지도이기도 하지만, 사람도 "지금 무엇이 어디까지 구현됐는지" 확인할 수 있어야 한다.
|
|
|
|
로드맵 완료 이력, SDD 설계 논의, 계약 원문, 사람용 가이드를 대체하지 않는다. 최종 기준은 항상 코드, `agent-contract/`, 테스트, 설정 예시다.
|
|
|
|
## 읽기 규칙
|
|
|
|
- 먼저 아래 "영역별 요약"으로 현재 찾는 주제를 고른다.
|
|
- 필요한 작업에서만 이 index를 읽고, 매칭되는 spec 문서만 읽는다.
|
|
- `archive/**`는 과거 비교, 복원, 특정 근거 확인 요청이 있을 때만 읽는다.
|
|
- API, wire protocol, config/event schema, 프로세스 간 계약 원문은 `agent-contract/`를 따른다.
|
|
- 코드 배치, 구현 진입점, 도메인 간 상세 책임 경계는 domain rule을 따른다.
|
|
|
|
## 영역별 요약
|
|
|
|
- 실행 경로: Edge와 Node 사이의 TLS identity, 등록, 실행, 이벤트, provider raw tunnel, transport heartbeat/reconnect, sealed credential lease consumption, 취소, command 흐름은 `runtime/edge-node-execution`에서 본다.
|
|
- 런타임 라우팅/설정: provider-pool, managed credential mode, `models[]`, top-level `protocol_profiles`, `nodes[].providers[].profile`, 그리고 refresh classification은 `runtime/provider-pool-config-refresh`에서 본다.
|
|
- 출력 검증 런타임: staged response-start, evidence hold/release, filter arbitration, bounded recovery/rebuild, raw-free observation은 `runtime/stream-evidence-gate`에서 본다.
|
|
- 외부 HTTP 입력: OpenAI-compatible 호출, Anthropic-compatible Messages 호출, managed principal route/slot binding, model-driven raw tunnel은 `input/openai-compatible-surface`, A2A JSON-RPC 호출은 `input/a2a-json-rpc-surface`에서 본다.
|
|
- 운영 제어: Control Plane, credential HTTPS/host-local bootstrap, mTLS Edge enrollment, projection/lease flow, fleet/edge status, Flutter Client 상태 소비는 `control/control-plane-operations`에서 본다.
|
|
|
|
## 스펙 목록
|
|
|
|
| id | 상태 | 언제 읽나 | path | 주요 근거 |
|
|
|----|------|-----------|------|-----------|
|
|
| `runtime/edge-node-execution` | 구현됨 | Edge-Node mTLS/protobuf transport, Node 등록, transport heartbeat/reconnect, provider run/cancel/command, provider raw tunnel, signed/sealed credential lease consumption, single-request Plan/Review effective template 적용을 확인할 때 | `agent-spec/runtime/edge-node-execution.md` | `agent-contract/inner/execution-runtime.md`, `agent-contract/inner/edge-node-runtime-wire.md`, `apps/edge/internal/transport/server.go`, `apps/node/internal/transport/client.go`, `packages/go/singlerequesttemplate/template.go` |
|
|
| `runtime/stream-evidence-gate` | 구현됨 | Stream Evidence Gate의 normalized event, evidence hold/release, filter registry, recovery coordinator, OpenAI request rebuild와 observation을 확인할 때 | `agent-spec/runtime/stream-evidence-gate.md` | `packages/go/streamgate/runtime.go`, `apps/edge/internal/openai/stream_gate_runtime.go`, `agent-contract/outer/openai-compatible-api.md` |
|
|
| `runtime/provider-pool-config-refresh` | 부분 | `credential_plane`, managed/legacy exclusivity, TLS/key references, `models[]`, top-level `protocol_profiles`, `nodes[].providers[].profile`, provider-pool dispatch, long-context admission, `execution_presets[].single_request.templates`의 relative-only 로딩과 admission freeze, and restart/applied refresh classification을 확인할 때 | `agent-spec/runtime/provider-pool-config-refresh.md` | `agent-contract/inner/edge-config-runtime-refresh.md`, `packages/go/config/provider_types.go`, `packages/go/config/validate.go`, `packages/go/config/load.go`, `apps/edge/internal/configrefresh/classify.go` |
|
|
| `input/openai-compatible-surface` | 부분 | `/v1/models`, `/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/messages/count_tokens`, `/anthropic/v1/models`, managed projection/slot routing, OpenAI-compatible auth/metadata/tool handling, Anthropic bearer/`X-Api-Key` auth, provider-pool native/bridge admission, safe slot attribution, marked single-request 내부 stage template과 caller-visible I/O 경계, and OpenAI-only usage metrics를 확인할 때 | `agent-spec/input/openai-compatible-surface.md` | `agent-contract/outer/openai-compatible-api.md`, `agent-contract/outer/anthropic-compatible-api.md`, `apps/edge/internal/openai/chat_handler.go`, `apps/edge/internal/openai/anthropic_handler.go`, `apps/edge/internal/openai/anthropic_bridge.go`, `apps/edge/internal/openai/normalized_sse.go`, `apps/edge/internal/openai/usage_metrics.go` |
|
|
| `input/a2a-json-rpc-surface` | 부분 | Edge A2A JSON-RPC, `message/send`, `tasks/get`, `tasks/cancel`, A2A task store와 bearer auth를 확인할 때 | `agent-spec/input/a2a-json-rpc-surface.md` | `agent-contract/outer/a2a-json-rpc-api.md`, `apps/edge/internal/input/a2a/server.go`, `apps/edge/internal/input/a2a/task_store.go` |
|
|
| `control/control-plane-operations` | 부분 | credential HTTPS and host-local bootstrap, Control Plane-Edge mTLS projection/lease wire, Client-Control Plane wire, Control Plane HTTP Edge/fleet status view, Flutter Client status consumer를 확인할 때 | `agent-spec/control/control-plane-operations.md` | `agent-contract/inner/control-plane-edge-wire.md`, `agent-contract/inner/client-control-plane-wire.md`, `apps/control-plane/internal/wire/edge_server.go`, `apps/control-plane/internal/credentiallease/service.go` |
|
|
|
|
## 작성 규칙
|
|
|
|
- 한국어 설명을 우선하고, 코드/계약 식별자는 원문을 유지한다.
|
|
- 현재 구현 기준으로 작성한다.
|
|
- 기능 목록과 주요 흐름을 먼저 파악할 수 있게 작성한다.
|
|
- 코드/계약/테스트 evidence를 우선한다.
|
|
- 계약 원문은 복제하지 않고 링크한다.
|
|
- 코드 진입점과 도메인룰 성격의 상세 경계는 반복하지 않는다.
|
|
- 불확실한 내용은 단정하지 않고 `부분`, `불명확`, `확인 필요`로 남긴다.
|