ArtifactDiff

인간과 AI 에이전트를 위한 계약 변경 검증 게이트.

AI 에이전트가 문서가 전달되기 전에 승인한 Office/PDF 계약 조건만 변경했는지 — 의미론적으로, 시각적으로, 암호학적으로 — 증명하세요.

ArtifactDiff는 로컬 우선(local-first)이며 오프라인으로 동작합니다. "지급 기간을 30일에서 45일로 변경"과 같은 요청된 편집을 고정된 정책으로 변환하고, 후보를 검증하며, 인간과 에이전트 모두가 검사할 수 있는 불변의 Review Bundle을 작성합니다.

프로젝트 상태: 0.1.0 알파. 계약 안전 코어와 서명된 Golden Path가 구현되었으며 900개 이상의 자동화 테스트로 검증되었습니다. 패키징 및 공개 릴리스 자동화는 아직 진행 중입니다.

감지 항목

ArtifactDiff는 의도적으로 fail-closed 방식입니다. Review는 기본적으로 차단 상태를 유지하며 FAIL 소견은 승인으로 해제할 수 없습니다.

Related MCP server: Proof Layer MCP

3분 Golden Path

전제 조건: Python 3.11+ 및 이 저장소의 로컬 체크아웃. 데모는 합성 계약만 사용하며 의존성이 설치된 후에는 네트워크 요청을 하지 않습니다.

python -m venv .venv
# Activate .venv using your shell, then:
python -m pip install -e ".[dev]"
python scripts/run_contract_golden_path.py --output build/contract-golden-path
python -m json.tool build/contract-golden-path/summary.json

실행 결과 Ed25519로 서명된 3개의 독립 검증 Review Bundle이 생성됩니다:

authorized    raw=pass    effective=pass
review        raw=review  effective=review
unauthorized  raw=fail    effective=fail

review 케이스는 차단된 상태로 유지됩니다. 명시적으로 시뮬레이션된 합성 인간 검토자와 함께 서명된 이벤트 체인 전환을 시연하려면 다른 출력 디렉터리를 사용하세요:

python scripts/run_contract_golden_path.py --output build/contract-golden-path-approved --approve-review

--approve-review는 데모 전용입니다. 실제 승인은 artifactdiff review 또는 artifactdiff approve를 통한 대화형 인간 작업으로 유지됩니다. 에이전트는 자신의 소견을 승인할 수 없습니다. 생성된 파일과 개인정보 보호 경계에 대해서는 Golden Path 연습을 참조하세요.

워크플로

Human instruction
      │
      ▼
contract-safe policy ── freeze + optional Ed25519 authorization
      │
      ▼
controlled agent edit session
      │
      ▼
semantic rules + protected entities + visual envelope
      │
      ├── PASS ───────────────────────────────► deliver
      ├── REVIEW ─► signed per-finding review ─► deliver or reject
      └── FAIL ───────────────────────────────► reject
                          │
                          ▼
                 immutable Review Bundle

Review Bundle이 시스템 오브 레코드입니다. 로컬 리뷰 데스크는 해당 번들 위의 인증된 루프백 인터페이스일 뿐입니다.

인간 및 자동화 인터페이스

동일한 애플리케이션 경계가 모든 인터페이스를 구동합니다:

• CLI: 정책 생성/검증/봉인, 통제된 세션 열기, 변경 검증, 소견 검사, 소견 승인, 번들 검증 또는 패킹.

• 로컬 리뷰 데스크: 계약이나 개인 키를 브라우저 JavaScript로 보내지 않고 번들을 검사하고 한 번에 하나의 소견에 서명.

• MCP: AI 에이전트를 위한 제한된 inspect/draft/validate/local-verify 도구. 입력 및 출력 루트가 분리되어 있으며 승인 또는 검증된 서명 기능이 없음.

• 오프라인 HTML: 검증된 사실에 연결된 휴대용 인간 리뷰 보고서.

artifactdiff --help
artifactdiff policy --help
artifactdiff verify --help
artifactdiff review path/to/review-bundle

MCP 호스트의 경우 stdio 서버를 시작하기 전에 절대 경로, 경로 구분자로 구분된 루트를 구성하세요:

ARTIFACTDIFF_MCP_INPUT_ROOTS=/absolute/contracts
ARTIFACTDIFF_MCP_OUTPUT_ROOTS=/absolute/artifactdiff-output
artifactdiff-mcp

MCP는 의도적으로 소견을 승인하거나 검증된 서명을 수행할 수 없습니다.

이것이 또 다른 PDF diff가 아닌 이유

보안 및 개인정보 보호 모델

• 로컬 우선 및 오프라인; 계정이나 클라우드 서비스가 필요 없음.

• contract-safe가 기본적으로 활성화되며 암시적 승인은 없음.

• 정확한 예상 편집이 해당 조항 및 발생 위치에 바인딩됨.

• 당사자, 금액, 통화, 날짜, 기간, 백분율, 머리글, 바닥글, 서명, 날인 및 첨부물이 기본적으로 보호됨.

• 오프라인 Ed25519가 핵심 신뢰 메커니즘; 엔터프라이즈 ID는 나중에 어댑터를 통해 추가 가능.

• 증거는 기본적으로 minimal; full은 명시적이며 sealed는 지정된 수신자용으로 암호화됨.

• MCP 응답은 제한되며 전체 계약, 페이지 이미지 또는 키 자료를 반환하지 않음.

전체 신뢰 및 판정 모델은 승인된 검증 게이트 설계 및 Plan 4.5 수용 기록을 참조하세요.

현재 형식 지원

• PDF → PDF

• DOCX → DOCX

• DOCX → PDF

• 영어, 중국어 및 이중 언어 계약 구조

• LibreOffice를 통한 선택적 DOCX 렌더링; PDF 렌더링은 로컬

개발

python -m pip install -e ".[dev]"
python -m pytest -q

이 저장소에는 현재 단위, 통합, 변조, CLI, MCP, 리뷰 데스크, 교차 형식 및 서명된 Golden Path 수용 테스트가 포함되어 있습니다.

다음 마일스톤

• 재현 가능한 공개 합성 코퍼스 및 zero-false-pass 게이트

• 바이너리 문서 풀 리퀘스트 리뷰를 위한 GitHub Action

• 데모 미디어 및 다운로드 가능한 예제 Review Bundle

• 스키마, 위협 모델, SBOM, 출처 및 서명된 알파 릴리스

• 엔터프라이즈 파서, 렌더러, 서명, 암호화 및 저장소를 위한 플러그인 경계

ArtifactDiff는 하나의 좁은 약속을 중심으로 구축되고 있습니다: 에이전트가 계약을 편집할 때, 정확히 무엇을 변경하도록 허용되었는지 — 그리고 그 외에는 아무것도 변경하지 않았는지 — 증명할 수 있습니다.