genichin
e6b6a8715b
Core Implementation (BAT-010):
- Add daemon registry schema and CRUD operations (req-023)
- Implement single-daemon asset assignment constraint (one asset per daemon)
- Add daemon_id field to service_token for daemon identification
- Add daemon.py CLI module for daemon management commands
- Add 20260513_0016_daemon_model.py migration for daemon tables
API Changes:
- GET /v1/assets: include daemon_id in AssetResponse
- POST /v1/assets/{asset_id}/ledger/trades: require daemon token binding
- GET /v1/user_info: include daemon metadata
- Enhanced service-token rotate to preserve daemon bindings
CLI Commands:
- pfhub daemon register --name <name> --runtime-id <runtime-id>
- pfhub daemon list
- pfhub daemon get <daemon-id>
- pfhub daemon revoke <daemon-id>
Requirements (REQ-023, REQ-028):
- REQ-023: Daemon Registry and Service Token Daemon Binding (Interface, Approved)
* AC-1: daemon CRUD operations
* AC-2: service token daemon binding for POST /v1/assets/{asset_id}/ledger/trades
* AC-3: single daemon per asset (exact-one assignment model)
- REQ-028: README.md Daemon Provisioning Runbook update (Documentation, Approved)
Documentation:
- Add dcy-006 Discovery for daemon-id and single-daemon asset assignment
- Update README.md with Daemon Provisioning Runbook section
- Add BAT-010 batch documentation with planning, implementation, verification
- Update rel-006 release document (daemon model implementation)
- Update data-model.md with daemon and daemon_asset_assignment tables
- Update interface-contract.md with daemon registry APIs
- Update runtime-flows.md with daemon lifecycle flows
Breaking Changes:
- REQ-005~009, REQ-011~012 status reverted to Approved due to revised contract
* daemon_id field addition and exact-one asset assignment requirement
* Existing Implemented evidence invalidated by contract revision
* BAT-001/002/008 re-verification required
Testing:
- Add test_daemon_registry.py for daemon CRUD operations
- Add test_daemon_assignment.py for single-asset assignment constraints
- Update test_auth.py, test_cli.py, test_v1.py for daemon support
- Verify daemon token binding in trade endpoint authorization
Impact:
- Database: 2 new tables (daemons, daemon_asset_assignments)
- Migration: 20260513_0016 creates daemon model schema
- CLI: 4 new daemon subcommands
- API: daemon_id propagation through v1 endpoints
- Verification: BAT-001/002/008 re-verification gates next release
4.3 KiB
4.3 KiB
BAT-010 Planning
- Status: confirmed
- Batch: BAT-010
- Profile: standard
Included REQ
- REQ-009: v1 API DB 스키마 migration (daemon schema 포함)
- REQ-023: Daemon Registry 관리 경로
- REQ-005: service-token 발급 daemon binding
- REQ-012: service-token rotate daemon_id 불변식
- REQ-006: GET /v1/assets daemon-scoped
- REQ-007: GET /v1/user_info daemon_id 필드
- REQ-008: POST /v1/assets/{asset_id}/ledger/trades daemon assignment authorization
- REQ-011: baseline docs daemon-aware 갱신
- REQ-028: README.md daemon provisioning runbook
Delivery Plan
의존 순서에 따라 아래 순서로 구현한다.
- REQ-009 — Alembic migration:
daemons테이블 신규 생성,auth_tokens.daemon_idFK 컬럼 추가,portfolios.managed_by_daemon_idFK 컬럼 추가, 기존 레코드 NULL backfill. 기존 revision chain 및IF NOT EXISTS정책 준수. - REQ-023 — Daemon registry CRUD: domain model(
Daemonentity), repository(create_daemon,get_daemon_by_slug,list_daemons_for_user,update_daemon), management route 또는 CLI subcommand. daemon_slug owner-unique validation. - REQ-005 — service-token issuance daemon binding:
POST /auth/service-tokens와pfhub service-token issue가 existing daemon registry entry에 1:1 binding. unknown daemon 입력 명시적 거부. - REQ-012 — service-token rotate daemon_id 불변식: rotate 시
token_hash,token_prefix,runtime_id만 갱신,daemon_id유지. CLI rotate 출력에daemon_id포함. - REQ-006 — GET /v1/assets daemon-scoped:
managed_by_daemon_id = token.daemon_id필터 적용. NULL token 403 fail-closed. - REQ-007 — GET /v1/user_info daemon_id 필드: 응답 스키마에
daemon_id추가. NULL backfill token은daemon_id: null진단 노출. - REQ-008 — POST /v1/assets/{asset_id}/ledger/trades daemon assignment authorization:
managed_by_daemon_id = token.daemon_id검증. mismatch/미배정/NULL token 403 fail-closed. - REQ-011 — baseline docs 갱신:
docs/interface-contract.md,docs/data-model.md,docs/runtime-flows.md에 daemon binding/assignment/403 policy/rotate invariant 반영. - REQ-028 — README.md 갱신: daemon provisioning 절차, enforcement enablement gate 4종 evidence, runtime_id/daemon_id 역할 구분 반영.
Dependencies
- Internal:
- REQ-009 migration은 REQ-023~028 구현 전에 schema가 존재해야 한다.
- REQ-023 daemon registry가 구축된 후 REQ-005/012 binding 구현이 가능하다.
- REQ-005/012가 daemon binding을 제공한 후 REQ-006/007/008 daemon-scoped authorization이 가능하다.
- REQ-011/028 문서화는 구현 단계 마지막 또는 구현 완료 직후 수행한다.
- External:
- 기존 Alembic revision chain (최신 head revision과 연결 필요)
- 기존 service-token bearer auth 모델 유지 (read/trade-write/admin permission 불변)
Design Gate
- Design Required Before Implementation: yes
- Reason: 신규
Daemon엔티티의 API transport 형태(HTTP endpoint vs CLI subcommand vs 혼합), daemon_slug owner-unique constraint 설계, enforcement enablement gate 활성화 방식, NULL backfill 기간 동안의 fail-closed boundary 정의 등 구현 착수 전 확정이 필요한 설계 결정이 있다.
Milestones
- Design confirmed — daemon registry interface 형태, enforcement gate 활성화 방식 확정
- REQ-009 migration 적용 + pytest 통과
- REQ-023 daemon registry CRUD 구현 + targeted test 통과
- REQ-005/012 daemon binding/rotate 구현 + targeted test 통과
- REQ-006/007/008 daemon-scoped API 구현 + daemon A/B 분리 시나리오 테스트 통과
- REQ-011/028 문서 갱신 완료 + 전체 pytest 통과
- Verification — 전체 AC evidence 매핑 완료, ready for release
Risks
- R-1 (High): NULL backfill 상태에서 daemon-scoped enforcement를 켜면 기존 service-token/asset이 연쇄 403에 직면해 운영 중단 발생 가능. 완화: enforcement는 inventory 완료 + dry-run zero-active-NULL/zero-mismatch + release approver 승인 이후에만 활성화.
- R-2 (Medium): daemon registry interface 형태 결정이 늦어지면 REQ-005/023 구현이 지연됨. 완화: design 단계에서 먼저 확정.
- R-3 (Medium): 기존 Alembic chain과 migration 충돌. 완화: 신규 revision을 기존 head에 선형으로 연결,
alembic history정상 여부 migration test에서 확인.