[P2][Spec-first] WavePlanDagV2 runtime adoption + bounded dry-run integration

[seoseo-ai]

상위 조사: #1635 P2-C.
기존 계약: docs/specs/wave-plan-dag-v2/spec.md (PR #1710, review fix #1711).
선행 읽기 모델: docs/specs/task-lineage-read-model/, PR #1638/#1690/#1693.
관련 epic: #1601.

배경

#1635의 P2-C 조사 결과로 bounded WavePlanDagV2 source-only 계약과 deterministic dry-run fixture가 머지됐다. 계약은 선형 wave-plan v1을 유지하면서 DAG/분기 제안의 스키마, 상한, cycle/unknown dependency 차단, all-matching 검증을 정의한다.

현재 스펙은 runtime producer/consumer, dispatcher integration, persistence 또는 실제 실행을 명시적으로 포함하지 않는다. 따라서 lineage read model은 존재하지만 DAG 계획을 안전하게 채택·실행하는 후속이 추적되지 않는다.

목표

기존 v1을 깨지 않고 WavePlanDagV2를 default-off runtime surface에 연결해, 생성된 계획이 schema validation과 bounded dry-run rehearsal을 통과한 경우에만 실행 후보가 되도록 한다.

범위

• v2 plan admission/parser를 기존 source-only 계약과 동일한 폐쇄 스키마로 구현
• deterministic dry-run: cycle, missing dependency, unreachable stage, fanout/depth/total-node budget, all-matching 검증
• task-lineage children/leaves/lineage read model을 이용한 duplicate-follow-up 및 stale frontier 검증
• 계획 생성 권한과 실행 권한 분리; 모델 생성 출력은 직접 실행하지 않음
• v1과 v2의 versioned dispatch 경계 및 v1 호환성 고정
• default-off/record-only 관측 모드와 bounded public/operator diagnostics
• restart/replay/idempotency 및 partial dispatch 실패 시 원자성·복구 계약
• deterministic integration fixtures와 no-network conformance tests
• focused tests, full npm run check, public-readiness/external-secret scan, 독립 리뷰

수용 기준

• 유효한 합성 DAG가 dry-run에서 결정적 순서와 bounded 실행 계획을 산출한다.
• cycle, unknown dependency, budget 초과, all-matching 위반은 task 생성 전에 안정된 reason code로 fail closed한다.
• v2 비활성화 시 기존 wave-plan v1의 입력·출력·실행 동작이 완전히 동일하다.
• 모델/워커 출력은 schema validation과 dry-run 성공 없이는 실행 또는 persistence authority를 얻지 못한다.
• 중복 follow-up과 stale frontier가 lineage read evidence로 식별되며 자동 mutation 없이 operator-visible하게 투영된다.
• record/default-off rollout과 단일 플래그 rollback이 문서화된다.

비목표

• 모델이 생성한 임의 JS 오케스트레이션 스크립트 실행
• 무제한 DAG 성장 또는 동적 budget 상향
• v1 즉시 폐기
• 라이브 기본값 전환이나 자동 대규모 fanout

안전 경계

이 이슈는 production deploy, broker/worker/Gateway restart, live DAG dispatch/canary, DB migration, cross-broker mutation, provider send, secret 이동, release 또는 GitHub ruleset 변경을 승인하지 않는다. 실제 record/canary/enforce 활성화는 정확한 대상·상한·rollback을 포함한 별도 운영자 승인이 필요하다.

[jinon86]

Start — soonwook(vps6). #1800 slice 1: WavePlanDagV2 런타임 admission/parser + 결정론적 dry-run.

범위

• 스펙 §2–§6 런타임 구현(packages/broker/src/wave-plan-dag-v2/): 폐쇄 스키마 admission·그래프 불변 검증(단일 structural root, leaf 존재, known endpoints, self/duplicate edge 차단, reachability, cycle=Kahn+ASCII 사전순 tie-break, 한도 32/64/8/8/8), canonical encoding + framed digest(§6), 순수 읽기전용 dry-run(§5 상태/사유 enum과 조인 규칙), stable rejection reasons 전 목록.
• 골든 교차검증: fixtures/contract/wave-plan-dag-v2.json의 2개 receipt 벡터와 핀된 manifest/receipt digest를 런타임이 재현하고, 체커(test/conformance/check-wave-plan-dag-v2.mjs)와의 기각 사유 패리티를 테스트로 고정합니다 — [P2][Spec-first] TaskAttemptRecordV1 runtime producer + failure-sharing read path #1799 slice 1·2가 레코드와 view에 세운 것과 동일한 방벽입니다.

경계

• 계약 문서(docs/specs/wave-plan-dag-v2/spec.md)는 변경하지 않습니다 — docs: define bounded WavePlanDagV2 dry-run contract #1710/#1711이 freeze한 소스 전용 계약 그대로입니다.
• default-off: store·route·dispatcher·persistence 통합 없음. 순수 함수만 노출하고 기존 wave-plan v1은 무변경입니다([P1][research] Karpathy autoresearch/AgentHub + Anthropic 문서 검토 기반 nexus 업그레이드 후보 (claim graph / lineage DAG / ratchet lane) #1635 측정처럼 v1은 유지).
• 후속 슬라이스 이월: lineage duplicate-follow-up/stale-frontier projection(항목 3), versioned v1/v2 dispatch 경계, record-only 관측 플래그·bounded diagnostics(항목 6), restart/replay/partial-failure 원자성 계약(항목 7).
• 라이브 활성화·배포 없음. source-only PR만.

이 코멘트가 착수 예약입니다(관례 제안: jinwon-int/ccc-node#1143).

[jinon86]

Done (slice 1) — PR #1992, merge 67629c44

Start 코멘트 범위 그대로입니다. 계약 문서는 변경하지 않았고 default-off도 그대로입니다 — store·route·dispatcher·persistence 통합 없음, wave-plan v1 무변경.

구현 — packages/broker/src/wave-plan-dag-v2/

• errors.ts — §5 stable rejection reasons 전체(17종) 폐쇄 어휘
• digest.ts — §6 canonical JSON + framed SHA-256 (A2A-WAVE-PLAN-DAG-V2\0 프레임)
• manifest.ts — closed-schema admission, 그래프 불변(단일 structural root, leaf 존재, known endpoints, self/duplicate edge 차단, reachability, Kahn+ASCII tie-break 위상정렬, 32/64/8/8/8 한도), exact manifest digest
• dry-run.ts — 결정론적 순수 dry-run → WavePlanDagDryRunReceiptV2; 부분 스냅샷은 fail-closed waiting, 미충족 조인은 not_selected

골든 교차검증

• 픽스처의 두 receipt 벡터를 바이트 단위 재현 — 핀된 manifest digest(65aeff14…)와 receipt digests 2개 포함. 체커 mutation table(duplicate_stage→cycle_detected 등 7케이스)과 기각 사유 패리티를 테스트로 고정했습니다. #1799가 레코드·view에 세운 것과 동일한 방벽입니다.
• RED 확인: digest payload에서 edge 정렬을 제거하자 골든 테스트 즉시 fail — 바이트 락이 실제로 회귀를 잡습니다.

의도된 차이 (1건)

런타임은 기각을 throw 대신 ok:false 데이터로 반환합니다. 체커는 큐레이션된 픽스처(잘못된 입력 = 저작 오류)를 보지만, 런타임은 비신뢰 proposal을 받으므로 dispatcher 통합 슬라이스가 사유 코드를 분기할 수 있어야 합니다(#1799 slice 2의 exclude-vs-reject 판단과 같은 계열). 사유 코드·메시지는 동일합니다.

매니페스트

broker test manifest step-17에 dist/wave-plan-dag-v2/*.test.js 글롭 추가(#1883 이후 dist 하위 디렉터리 관례 동일). legacyEquivalent 동기 갱신, 보존 가드 자기일치 확인.

검증

main 머지 커밋(67629c44)에서 재검증: 신규 테스트 16/16 pass, conformance 26 checks ok, release gate ok, script budget 전 항목 변동 없음. GitHub CI check·broker·layout·analyze·CodeQL 전부 SUCCESS, seoseo-ai 승인 후 squash 머지.

잔여 (이 이슈)

• lineage duplicate-follow-up / stale-frontier projection (항목 3)
• versioned v1/v2 dispatch 경계 · v1 호환성 고정
• record-only 관측 모드 플래그 · bounded public/operator diagnostics (항목 6)
• restart/replay/idempotency · partial dispatch 원자성 계약 (항목 7)

라이브 활성화·배포 없음. source-only.

[jinon86]

Start (slice 2) — soonwook(vps6). slice 1(#1992, merge 67629c44) 이후 범위입니다.

범위

항목 6 — default-off/record-only 관측 모드 + bounded public/operator diagnostics 전체와 항목 7의 순수 함수 하위집합(결정론 재생성 고정)을 wave-plan-dag-v2 모듈 안에 구현합니다.

• observe.ts: 관측은 모드 인자로만 활성화됩니다 — off(기본)에서는 {observed:false} 외에 아무것도 산출하지 않고, record_only만 bounded 요약을 냅니다. 의도적으로 행동 변형(enforce류) 변형은 union에 넣지 않습니다 — 관측이 곧 권한이 되는 문을 원천 차단합니다(§1 경계).
• public 관측(폐쇄 필드만): admitted 여부, §5 stable rejection reason(closed enum), 개수(clamp 상한+도달 플래그, malformed 대용량 배열도 유계), receipt 발급 여부/사유. 태스크 ID·메시지·자유문자열 없음.
• operator 관측(분리 표면): 길이 상한 메시지(240자 truncate), 위상순서·receipt digest(admitted 때만) — [P2][Spec-first] TaskAttemptRecordV1 runtime producer + failure-sharing read path #1799 slice 2의 public/operator 분리 패턴 동일.
• 항목 7 순수 부분: 동일 입력→바이트 동일 수신재생성(admission 멱등성, dry-run 반복 호출 동일성), 입력 구조적 격리(observer는 입력을 clone 후 검증 — 검증 후 입력 변이가 이미 산출된 관측에 영향 없음)를 테스트로 고정합니다. restart/replay의 store·persistence 계약은 후속(dispatch 통합 슬라이스) 이월입니다.

착수 전 확인한 것 — 항목 3(lineage 중복/stale 검증)은 이월합니다

• docs/specs/task-lineage-read-model/spec.md:102 — "Semantic duplicate detection (AgentHub explicitly left this out; so do we)" — read model 자체가 의미론적 중복 판정을 범위 밖으로 명시했습니다.
• V2 manifest 폐쇄 스키마(§3)에는 task 참조 필드가 존재하지 않습니다. stage↔task 바인딩이 스펙 어디에도 정의돼 있지 않으므로, 지금 구현하려면 계약 밖 스키마를 새로 발명해야 합니다.
• 그 바인딩 결정은 항목 "v1/v2 versioned dispatch 경계"(dispatch 통합 슬라이스, 운영자 결정 필요)의 전제라 같이 가야 합니다. 조용히 스키마를 만드는 대신 본 코멘트로 명시 이월합니다.

경계

• 계약 문서·conformance 체커·골든 픽스처 무변경, 매니페스트 글롭 추가 불필요(기존 dist/wave-plan-dag-v2/*.test.js가 커버).
• store·route·플래그 주입·배포 없음 — 관측 함수는 순수하며 기본값이 off. source-only PR만.

이 코멘트+이전 슬라이스 관례로 착수 예약합니다(jinwon-int/ccc-node#1143).

[jinon86]

Done (slice 2) — PR #1993, merge 199a6132

Start 코멘트 범위 그대로입니다: 항목 6 전체 + 항목 7의 순수 함수 부분. 계약 문서·체커·골든 픽스처 무변경, default-off 유지.

구현 — observe.ts (순수 모듈 하나)

• default-off: off(기본값 export)는 유효 proposal에도 {observed:false}만 산출. 관측은 매 호출의 mode 인자로만 활성화되고 모듈 레벨 플래그가 없습니다 — 향후 live wiring의 rollback은 호출부 값 하나를 off로 되돌리는 변경뿐입니다(수용기준의 단일 플래그 rollback).
• acting 변형 부재: mode 유니언이 off | record_only로 폐쇄돼 있어 enforce류 변형은 유니언을 깨야만 추가할 수 있습니다 — 관측이 권한으로 흐르는 문을 타입이 막습니다(§1 경계).
• bounded diagnostics: public 투영은 boolean·§5 closed reason enum·개수(cap 64 clamp + 도달 플래그)뿐 — 스테이지 100개짜리 malformed proposal도 유계로 사라집니다. stage id·digest·자유문자열 미노출을 인코딩 검사로 고정. operator 표면은 메시지(240자 truncate)·다이제스트·위상순서 추가 — [P2][Spec-first] TaskAttemptRecordV1 runtime producer + failure-sharing read path #1799 slice 2의 public/operator 분리와 동일한 축.
• 항목 7 순수 부분: admission 재호출 deep-equal, 동일 rehearsal의 바이트 동일 receipt 재생성(핀 다이제스트 포함), 옵서버 입력 스냅샷으로 후변경 불변성 고정. store·persistence 계약(항목 7 나머지)은 dispatch 통합 슬라이스 이월입니다.

RED 확인

count clamp 제거 변이 → oversized 케이스 즉시 fail, 복구 확인.

항목 3 이월 근거 (재확인)

task-lineage read model은 semantic duplicate detection을 의도적으로 제외(spec.md:102)하고 freeze된 V2 manifest 폐쇄 스키마에는 stage↔task 바인딩 필드가 없습니다. duplicate-follow-up/stale-frontier 검증에는 그 바인딩 계약이 먼저 필요하므로 v1/v2 versioned dispatch 경계 슬라이스의 전제로 이월합니다 — Start 코멘트에 상세 기록.

검증

main 머지 커밋에서 재검증: observe 13/13, slice-1 회귀 16/16 (dist 합산 29/29), conformance 26 checks ok, release gate ok, seoseo-ai 독립 승인 후 jinon86 squash 머지.

잔여 (이 이슈)

• v1/v2 versioned dispatch 경계 + v1 호환성 고정 ← 다음 슬라이스 후보 (항목 3의 선행)
• restart/replay/idempotency · partial dispatch 원자성의 store·persistence 계약
• dispatcher dry-run read path · bounded route 노출

라이브 활성화·배포 없음. source-only.

[jinon86]

Slice 3 사전 검토 — v1/v2 versioned dispatch 경계 설계 스케치 (착수 전 방향 확인)

slice 1·2(#1992/#1993) 이후 남은 항목 중 versioned dispatch 경계를 착수하기 전, 코드상 현재 위상을 확인했고 설계 선택지를 정리합니다. 아직 착수(claim)하지 않았습니다 — 방향 확인 후 시작합니다.

실츬한 현재 위상

항목	확인 결과
v1 진입	validateWavePlanSpec(core/wave-plan.ts:87) — 폐쇄 필드 투영. v2 형태 payload(stage에 gate 없음)는 wave_spec_invalid로 기각. v2 payload가 조용히 v1으로 재해석되는 경로는 존재하지 않음(fail-closed 이미 달성)
v1 dispatch	stage의 dispatch.manifestRef는 참조만 보유하고, next-stage advance는 특권 수동 신호(route 제한). 실제 스테이지 디스패치 자동화는 코어에 없음
v2	순수 함수만(admission+dry-run+observe). store·route 없음

추천 — 얇은 순수 경계 분류기 (옵션 1)

wave-plan-dag-v2/dispatch-boundary.ts(신규 순수 모듈):

• classifyWavePlanIntake(payload) — payload의 kind를 검사해 (a) WavePlanDagManifestV2가 아니면 검증 없이 identity pass-through로 v1 표면 귀속만 선언(비간섭 구조적으로 고정), (b) V2 manifest면 admission 통과 + dry-run receipt 요구를 만족해야만 rehearsal_candidate로 분류, 아니면 §5 stable reason으로 기각.
• 닫힌 WavePlanDagV2IntakeRecord 반환(버전 라우팅 결정 + 유계 fact).
• 기존 v1 validator/store/route 무변경. 미래 route 통합 시 "분류기를 먼저 거친다"는 계약을 타입과 픽스처로 고정하는 층입니다.

근거: §1이 이 계약에 route/store/dispatcher integration을 명시 금지하므로 경계는 순수 분류층으로만 정의되고, v1 호환성 고정은 "v1 payload는 분류기를 통과해도 바이트 동일하게 v1로 간다"는 비간섭 픽스처로 강제됩니다. default-off·source-only는 slice 1·2와 동일.

선택지

1. 옵션 1(추천) — 위 얇은 순수 분류기 slice 3으로 착수
2. 옵션 1 + dispatch-intake record를 broker 타깃 관측(observation)에도 연결한 확장
3. 바인딩 계약(item 3)부터 — 운영자 결정 필요(스키마 발명 포함)
4. 다른 순서/보류

운영자 결정 필요 사항: 항목 3의 stage↔task 바인딩 스키마는 어느 쪽이든 이번 스코프에서 제외되며, 결정은 별도(장기 dispatch 통합 때)로 유지합니다.

[jinon86]

Start (slice 3) — soonwook(vps6). 옵션 1 확정에 따라 얇은 순수 분류기를 착수합니다.

직전 코멘트(설계 스케치)의 옵션 1 그대로입니다:

범위

• wave-plan-dag-v2/dispatch-boundary.ts(신규 순수 모듈): classifyWavePlanIntake(payload)
  • payload가 kind: WavePlanDagManifestV2 객체가 아니면 검증 없이 identity pass-through — v1 표면 귀속만 선언하는 비간섭 결과(routesTo: v1_wave_plan_spec). 기존 v1 validator/store/route 무변경.
  • V2 manifest면 admission 통과(rehearsal_candidate) 또는 §5 stable reason 기각(rejected_v2).
• 닫힌 WavePlanDagV2IntakeRecordV1 반환: 버전 라우팅 결정 + 유계 fact(bucket, reason, 관측 연결용 bounded digest 필드).
• classification이 곧 권한이 아님을 타입으로 고정: record는 dispatch 액션 필드를 전혀 갖지 않음.

경계

• core/wave-plan.ts·wave-plan-store.ts·wave-plan-routes.ts 무변경. 라우트 통합은 별도 슬라이스.
• default-off 해당 없음(입력 함수), 라이브 활성화·배포 없음. source-only PR만.

이전 슬라이스와 동일하게 이 코멘트로 착수 예약합니다.

[jinon86]

Done (slice 3) — PR #1994, merge 4d354191

옵션 1 그대로입니다: 기존 v1 validator/store/route 무변경, versioned dispatch 경계만 순수 층으로 추가.

구현 — dispatch-boundary.ts

• classifyWavePlanIntake(payload, request?) — 정확히 하나의 폐쇄 질문에 답합니다: 이 intake의 소유 버전은 어디인가.
• kind가 V2가 아니면(null·문자열·배열 포함) 검증 없이 identity pass-through(v1_wave_plan_spec) — kind 외에는 아무것도 읽지 않고 어떤 입력도 throw하지 않습니다.
• V2 manifest는 slice-1 admission으로: 통과 시 v2_rehearsal_candidate(요청 동반 시 rehearsal 결과+closed §5 reason), 실패 시 v2_rejected.
• intake record는 액션 필드가 없는 폐쇄 유니언입니다 — 분류는 권한이 아니며(§1) acting bucket을 추가하려면 유니언 변경이 필요해 경계가 리뷰 가능하게 유지됩니다.

비간섭 핀

validateWavePlanSpec 판정을 분류 전후로 비교하는 테스트(deep-equal / throw 보존)로 분류기를 거쳐도 v1 payload의 운명이 바뀌지 않음을 고정했습니다. RED 확인: kind 체크 제거 변이에서 pass-through 핀 2건 즉시 fail.

검증

main 머지 커밋에서 재검증: 신규 7/7, wave-plan-dag-v2 전체 dist 36/36, conformance 26 checks ok, release gate ok. seoseo-ai 독립 승인 후 jinon86 squash 머지.

잔여 (이 이슈)

• restart/replay/idempotency · partial dispatch 원자성의 store·persistence 계약 (항목 7 나머지)
• dispatcher dry-run read path · bounded route 노출
• stage↔task 바인딩 계약(항목 3) — 위 라우트/스토어 작업 때 운영자 결정 필요

라이브 활성화·배포 없음. source-only.

[jinon86]

Slice 4 사전 검토 — 항목 7 나머지(restart/replay/idempotency · 부분 실패 원자성 계약) 설계 스케치

slice 3(#1994)에 이어 항목 7의 나머지를 착수하기 전 설계를 정리합니다. 아직 claim하지 않았습니다 — 확인 후 시작합니다.

코드상 현재 위상 (실측)

• v1 wave-plan store(core/wave-plan-store.ts): 순수 상태머신은 타임스탬프 프리(restart 시 byte-identical 재개), 브로커 클럭은 별도 주입, BrokerSnapshot canonical-blob 경유 저장. reaper는 detection만.
• 확장점: broker.registerSnapshotExtension()이 사이드카 상태의 스냅샷 편입 경로로 존재 — 단 아직 코어 연결은 하지 않을 계획.
• V2: 지금까지 순수 함수만 — 영속 대상이 없었음. 이번이 첫 "저장될 것"의 등장.

추천 설계 — 증거 보존형 순수 레코드 스토어 (옵션 A)

wave-plan-dag-v2/record-store.ts(신규 순수 모듈):

저장 대상(폐쇄 레코드만) — admitted manifest(digest 키) + rehearsal 결과(receipt 또는 기각 사유):

• 키 = (manifestDigest, receiptDigest) 쌍. 동일 레코드 재기록(at-least-once 재전달)은 멱등 no-op, 같은 manifest의 다른 rehearsal 결과는 모두 보존(증거 소실 방지)하고 삽입 서수+digest로 결정론적 순서.
• 부분 쓰기 원자성: 배치 쓰기는 전부 검증 후 일괄 커밋(all-or-nothing). Half-built receipt("receipt의 일부만")는 표현 자체가 없어 영속 불가.
• 중단 안전 흐름 규약: admission 저장 → rehearsal → receipt 저장 순서가 미래 통합의 필수 순서. 중단되면 admitted-unrehearsed 또는 admitted+receipt 두 상태만 존재하고 둘 다 재생성 가능(순수 함수 재실행) — restart/resume 계약.
• 복구 시 무결성: restore()는 레코드 하나라도 변질돼 있으면 구조화 사유와 함께 전체 거부(fail-closed). 관측 view(slice 2)의 fail-open과 반대인 이유: 이건 판독용 view가 아니라 서명 경계 문서(증거)의 보존이라 조용한 유실이 worse. 스냅샷 형태는 PersistedWavePlan[]와 같은 값-배열 규약으로 registerSnapshotExtension 호환(단 본 슬라이스에서 broker 연결 없음 — route/dispatcher 슬라이스 과제).

운영자 결정 필요 사항

1. restore 충돌 정책 — 추천은 위의 전체 거부(fail-closed). 대안: 변질 레코드 격리+카운트 후 나머지 복원(slice 2식 fail-open). 증거 보존 성격상 추안이지만 최종 결정은 운영자.
2. 보존 한도 — 스토어 자체에는 cap 없음(브로커 스냅샷 생애주기를 따름). 별도 pruning은 [P1] Define the shared-state and HA contract beyond process-local security and SQLite #1504 계약 끝나면 그쪽 lineage 규칙에 맞추는 게 안전해 보임(선점하지 않음).

선택지

1. 옵션 A 착수 (추천 — restore fail-closed)
2. 옵션 A + restore fail-open(격리+카운트)
3. 계약 문서화만(코드 없이) 먼저
4. 다른 순서/보류