rara/agent-roadmap/sdd/knowledge-lifecycle/ingestion-and-dataset-lifecycle/SDD.md

SDD: 수집과 Dataset 수명주기

위치

• Milestone: Milestone 문서
• Phase: PHASE.md

상태

[승인됨]

SDD 잠금

• 상태: 해제
• 사용자 리뷰: 없음
• 잠금 항목:
  • 없음

문제 / 비목표

• 문제: source change port와 dataset·artifact 테이블은 있으나 cursor commit, tombstone·ACL, canonical normalization, immutable version과 deterministic rebuild의 end-to-end 의미가 고정되지 않았다.
• 비목표:
  • retrieval index build와 release promotion
  • source vendor별 모든 기능 표준화
  • 대형 원문 content의 PostgreSQL 직접 저장

Source of Truth

영역	기준	메모
Roadmap	Milestone 문서	수집·dataset 범위와 상태 원장
Code	Source port	source cursor와 change stream 기준
External Provider	source revision·cursor	connector는 provider revision을 opaque 값으로 전달한다
User Decision	없음	RARA가 dataset·lineage를 소유하는 책임이 확정되어 있다

State Machine

상태	진입 조건	다음 상태	근거
pending	source가 등록되거나 새 revision이 감지됨	syncing, disabled	source state
syncing	workflow가 cursor lease와 snapshot을 획득함	ready, failed	workflow run
ready	raw·normalized·retrieval dataset version이 확정됨	syncing, disabled	dataset publish event
failed	step 오류로 cursor가 확정되지 않음	syncing, disabled	failure result
disabled	source가 운영상 비활성화됨	pending	control-plane mutation

Interface Contract

• 계약 원문: Source port
• 입력:
  • SourceCursor: 마지막 확정 provider revision과 opaque state
  • SourceChange: key, operation, content, media type, metadata, ACL, revision, observed_at
  • recipe: parser·normalizer·chunker version과 설정
• 출력:
  • raw snapshot artifact와 다음 cursor
  • normalized document·chunk artifact
  • immutable dataset version, stats와 lineage
• 금지:
  • artifact가 durable하지 않은 상태에서 cursor를 확정하지 않는다.
  • tombstone과 ACL change를 일반 upsert로 축약하지 않는다.
  • 동일 dataset version의 content를 in-place 변경하지 않는다.

Acceptance Scenarios

ID	Milestone Task	Given	When	Then
S01	source-cursor	paged source와 중간 failure	sync 재실행	마지막 durable cursor부터 재개하고 change를 잃지 않는다
S02	change-semantics	upsert·delete·ACL change	다음 dataset 생성	삭제 content가 제거되고 ACL revision이 lineage에 남는다
S03	connector-conformance	fake와 최소 실제 connector	conformance suite	paging, retry, tombstone, cursor 시나리오를 통과한다
S04	normalization	동일 raw snapshot과 recipe	반복 정규화	canonical schema와 동일 content hash를 만든다
S05	dataset-version	raw·normalized·retrieval artifact	publish	목적별 불변 version과 stats가 생성된다
S06	artifact-lineage	source revision부터 chunk 결과	lineage 조회	parent-child와 생성 step chain이 끊기지 않는다
S07	rebuild-recovery	artifact publish 전후 failure	동일 revision 재실행	확정 artifact를 재사용하고 실패 artifact는 격리한다

Evidence Map

Scenario	Required Evidence	agent-task 연결	완료 Evidence 기대
S01	cursor commit·resume integration test	agent-task/m-ingestion-and-dataset-lifecycle/...	source-cursor no-loss evidence
S02	tombstone·ACL dataset diff	agent-task/m-ingestion-and-dataset-lifecycle/...	change-semantics deletion·ACL evidence
S03	connector conformance matrix	agent-task/m-ingestion-and-dataset-lifecycle/...	connector-conformance 결과
S04	deterministic normalization test	agent-task/m-ingestion-and-dataset-lifecycle/...	normalization hash evidence
S05	immutable version mutation negative test	agent-task/m-ingestion-and-dataset-lifecycle/...	dataset-version version evidence
S06	lineage traversal query test	agent-task/m-ingestion-and-dataset-lifecycle/...	artifact-lineage full chain
S07	PostgreSQL·artifact fault injection smoke	agent-task/m-ingestion-and-dataset-lifecycle/...	rebuild-recovery reuse·quarantine evidence

Cross-repo Dependencies

• 없음

Drift Check

• Milestone 기능 Task와 Acceptance Scenario가 일치한다.
• Evidence Map이 code-review/complete.log에서 검증 가능하다.
• source 계약 원문은 port 링크로 참조했다.
• 사용자 리뷰가 필요한 항목이 없다.

사용자 리뷰 이력

• 없음

작업 컨텍스트

• 표준선: cursor-after-durable-write, immutable dataset version, content-addressed artifact, explicit tombstone·ACL
• 후속 SDD: Index 게시와 Release 수명주기