1
0
Fork 0
Everything2Everything/docs/research/2026-11-04/agent-core-completion.md

11 KiB

Core 안전성 후속 구현 증거

범위: ConversionEngine, OutputPathHelper, OutputTransaction, provider adapters, 외부프로세스 수명. UI/설정/이력/프리셋은 다른 세션 소유다. 커밋·배포하지 않았다.

RED → GREEN

  1. CoreSafetyCompletionTests 초기 5개 assertion RED:
    • 실패/취소 encoder가 기존 출력에 source를 써서 expected previous successful result와 불일치(2개).
    • 동시 ConvertOne 두 개 중 하나가 IOException으로 Failed 또는 같은 이름 선택.
    • 파일이 가로막은 출력디렉터리에서 expected no exception / actual IOException.
    • 외부 stdout expected <=32768 / actual200002.
  2. 최소 구현: 같은 볼륨 목적지 안의 고유 .e2e-stage-*에 provider 출력 → 성공 후만 final 경로 공개. 기존 파일은 File.Replace, 새파일은 overwrite=false File.Move. AppendNumber 경합은 이름 재선택. 실패·취소 staging 정리. ConvertOne 경로/가용성 오류는 Fail로 정규화(취소 전파).
  3. 관련 20개(CoreSafety 초기5 + BatchInputSafety4 + EngineCharacterization11) GREEN, 실패0, 8초.
  4. 추가 assertion RED:
    • 취소배치 exception에 완료결과가 없어 CompletedResults expected non-null / actual null.
    • 병렬 final progress expected2 / actual1.
    • stdin 미소비 child에서100ms timeout이 적용되지 않아2초 safety cancellation 예외.
  5. 구현: BatchConversionCanceledException.CompletedResults(처리된 성공/실패/skip 결과, 입력순서), 완료progress Index=done, stdin쓰기에도 linked timeout 적용. GREEN은 후속 슬롯에서 확인한다. 최초 GREEN시도는 다른 세션 ReleasePipelineTests.cs:36 CS1012 컴파일오류로 막혀 동작 실패로 계산하지 않았다.

출력 안전성 계약

  • 앱의 ConversionEngine 1hop/마지막multihop/Combine 경계에서 적용된다. provider를 직접 호출하는 라이브러리 사용에는 이 엔진계약이 자동적용되지 않는다.
  • 새 파일 공개는 File.Move(overwrite=false), 기존 파일 교체는 File.Replace로 기존 파일을 먼저 삭제하지 않는다. 다른 프로세스가 이름을 선점하면 AppendNumber가 다음 번호를 선택한다.
  • 원본과 최종경로가 같으면 덮어쓰기를 거부한다. 사용자 원본을 인코더 실패로 훼손하지 않는다.
  • 다중페이지 변환의 파일별 공개는 원자적이나 전체 페이지 묶음의 단일 트랜잭션은 아니다. 디스크·권한 오류가 후반 commit에서 발생하면 앞서 성공한 페이지는 남을 수 있다. 검증 없이 전체 all-or-none을 주장하지 않는다.
  • staging 생성/쓰기 실패는 읽기 쉬운 파일별 실패로 전달된다. OS가 cleanup 자체를 거부한 상황의 잔류까지 완전 보장하지 않는다.
  • provider가 기존 출력을 skip할지 여부는 final commit 시점에 판정하므로 skip 작업도 encode 비용이 들 수 있다.

Word-only 프로세스 격리

root의 내부worker 진입구 assertion RED 확인 뒤 구현했다. RunWordWorker(source,target)는 absolute 원본.doc/.docx 존재, 대상.pdf 미존재, 대상부모폴더 존재를 검사한다. 부모는 현재 apphost의 internal-word-pdf verb를 ExternalProcessRunner로 실행해 timeout/cancel/tree kill을 적용한다. COM은 자식 STA worker에서만 호출한다.

COM이 RPCSS를 통해 WINWORD를 생성하면 단순 프로세스트리 kill에 안 잡힐 수 있으므로 worker가 HWND→PID/starttime receipt를 기록한다. 부모는 시작전 존재하던 Word PID를 제외하고 processName/starttime 일치하는 새 Word만 정리한다. 이미 실행 중인 사용자의 Word 문서를 종료하지 않는다. 실제 Word-only Office 환경의 검증과 일반 도구 timeout 검증은 구분한다.

연구 후보 범위판단

  • R03: 출력충돌/원본보존/부분파일 노출은 직접 재현된 기존 결함이므로 위 engine 경계에서 수정.
  • R20: 실패취소 임시정리, 외부로그 상한, timeout은 기존 흐름의 안전성 수정. 압축폭탄 한도·최대픽셀·HTML 네트워크 정책은 지원범위를 바꾸는 별도 정책으로, 임의 수치로 정상 전문파일을 거부하지 않는다. 실제 자원측정과 사용자 목적에 맞춘 한도를 별도 기록해야 한다.
  • R21: 외부 Word worker는 bounded lifecycle로 격리. 네이티브 Magick 전체 sandbox는 현 변경이 아니며 native access violation까지 앱을 보호했다고 주장하지 않는다.
  • R27: DOCX 공용runner/고유작업폴더/원본stem 및 OCR 정리가 후속 RED 대상. HTML dispatcher flaky는 timing 보고서에 근거를 유지한다.

후속 검증 완료

test-core/core-safety-green.trx: CoreSafetyCompletionTests + ExternalProcessRunnerTests + EngineCharacterizationTests 27/27 통과, 실패0, 5초. stdin timeout, 완료결과 취소 전달, 진행률 최종값/순서, 실패·취소 기존파일 보존, 동명 병렬 공개, 원본stem HEIC adapter, 실제 LibreOffice DOC→PNG 원본stem, 손상PDF OCR 임시폴더 정리를 포함한다. HEIC fixture는 PNG payload의 adapter 경로 검증이며 HEIC codec 품질을 입증하지 않는다.

추가 RED 근거: 어댑터4개 실패(core-adapters-red.trx), 순차 완료progress expected Index1 / actual0. 수정 뒤 위 통합 GREEN으로 검증했다. 따라서 앞의 5번 GREEN대기와 R27 후속예정 상태는 이 결과로 갱신한다.

Progress 계약: Index는 완료파일 수다. FileProgress==1은 해당 파일이 Index에 이미 포함된다. 0<p<1일 때만 추가 분수로 해석한다. 순차 adapter는 동기 전달해 루프 변수 캡처/뒤늦은 콜백을 제거하고 병렬 보고는 완료수 증가와 함께 lock으로 순서를 보존한다.

잔여 확인: sidecar(HTML 이미지/하위폴더)와 여러 결과 중 후반 공개 실패·취소 시 이미 공개된 경로의 전달을 추가 RED로 검증 중이다. 현재 파일별 atomicity가 다중파일 전체 원자성을 의미하지 않는다.

Sidecar·부분 공개·Word 매크로 후속

core-publish-red.trx: 공개후 취소 CompletedResults null, 공개후 후속실패 OutputPaths empty, Word automation 준비 API missing assertion RED. HTML sidecar는 core-sidecar-assertion-red.trx에서 상대이미지 존재 expected true / actual false assertion RED를 별도 확보했다. core-partial-batch-red.trx는 engine batch가 현재 파일의 이미 공개된 페이지를 버려 CompletedResults empty assertion RED였다.

최소 구현 후 core-completion-green.trx 33/33 통과, 실패0, 3초(관련 Core/외부프로세스/특성화+root PlannedOutputDirectory). Sidecar가 있는 변환은 상대경로를 유지하도록 전체 stage를 <원본>_files_<GUID> 폴더로 Directory.Move하고 primary 최종경로를 반환한다. 일반 단일출력 이름은 바꾸지 않는다. 부분 공개후 실패는 Failed 결과 OutputPaths에 공개분을 반환하고, 취소는 BatchConversionCanceledException의 Failed 부분결과로 전달한다. 배치 wrapper가 이 결과와 이전 완료분을 입력순서로 합친다.

Word는 문서 열기 전에 AutomationSecurity=3(msoAutomationSecurityForceDisable), DisplayAlerts=0, Visible=false를 설정한다. 자동화 stub가 실제 적용값을 검증하지만 실제 Office 설치환경의 매크로차단 runtime proof는 아니다. public GetOutputDirectory는 root의 API missing assertion RED 확인을 전달받아 기존 private SSOT resolver wrapper로 추가했다.

추가 확인 중: sidecar Skip 정책이 기존 root primary를 존중하는지 전용 assertion RED 준비.

Sidecar collision 명세: primary 실제 stem 기준 기존 root primary 또는 <primaryStem>_files_* bundle 내 같은 primary가 있으면 Skip은 전체생략한다. AppendNumber/Overwrite는 상대참조 보존을 위해 항상 새고유bundle을 반환하는 안전예외이며, 결과 Message에 이를 고지한다. 이전결과를 삭제하지 않는다. 이 예외는 단일파일출력에는 적용하지 않는다. 새 전용 assertion RED를 슬롯대기중이다.

Core 최종 게이트 및 범위 종료

core-final-red.trx: Skip existing root primary/previous bundle 두 경우 expected Skipped actual Success, bundle Message expected 안내 actual null, parallel invalid custom destination expected no exception actual ArgumentException(NUL path) — 4 assertion RED, 선언 primary순서 보존 시나리오1개는 기존 GREEN. 최소수정 뒤 core-final-green.trx: 관련36/36 GREEN, 실패0, 5초, 빌드경고 출력없음.

Sidecar 최종계약은 실제 첫 primary stem 기준 <primaryStem>_files_<GUID> 폴더다. 반환경로는 선언순서 배열로 보존한다. Skip은 root primary 또는 동일 primary stem의 기존 bundle 내부 primary가 있으면 전체생략한다. Overwrite/AppendNumber의 sidecar는 기존자료를 파괴하지 않고 새bundle을 반환하며 결과 Message로 예외를 고지한다. 단일파일 collision 계약은 그대로다. 디렉터리 열람/공개 오류는 파일별 Failed로 정규화한다.

CORE08 parallel grouping도 invalid output path 오류를 고유 groupkey로 격리해 ConvertOne 파일별 오류경계에서 처리한다. 따라서 한 파일/잘못된 목적지가 배치 전체 예외로 빠지는 재현을 해결했다. 이 검증 뒤 Core 생산코드 수정 범위는 닫고 root 전체통합·릴리즈 게이트를 기다린다. 전체 스위트 통과/10초준수/패키지·실제배포 성공은 이 child의 관련36개 증거로 주장하지 않는다.

릴리즈 전 P1 추가: 다른 큐 원본 덮어쓰기 방지

Root 최종안전리뷰에서 현재source만 보호하면 a.jpg+a.png→원본폴더/png+Overwrite가 다른 큐 원본 a.png를 교체함을 확인했다. core-originals-red.trx에서 독립배치, Combine(첫원본same.jpg+다른원본same.tif→tif), 별도engine 동시배치 세 시나리오 모두 original 바이트 expected / converted result actual assertion RED를 확보했다.

InputFileProtection은 프로세스 내 active engine source fullpath를 대소문자 무시 refcount로 등록한다. ConvertMany는 전체입력수명 동안 등록하고 ConvertOne도 단건수명 동안 등록한다. 등록과 최종 publish 보호검사+Move/Replace가 같은 lock을 사용하므로 별도engine의 활성batch끼리도 보호된다. 보호된 경로면 기존원본을 그대로 두고 명확한 Failed 메시지를 반환한다. using disposal로 성공/실패/취소시 등록을 해제한다. Combine도 batch전체source 등록 범위에 포함된다.

core-originals-green.trx: CoreSafetyCompletion+BatchInputSafety+EngineCharacterization 41/41 GREEN, 실패0, 3초, 빌드경고 출력없음. 보호집합은 현재 프로세스에 등록된 fullpath 기준이다. 다른 앱프로세스의 입력집합, 아직시작되지않은 별도futurebatch, hardlink/junction 등 파일identity별칭을 탐지했다고 주장하지 않는다. AppendNumber의 외부프로세스 출력경합 안전공개와 이 입력보호 경계는 구분한다.