ArtifactDiff

Una puerta de verificación de cambios de contratos para humanos y agentes de IA.

Demuestra que un agente de IA cambió solo los términos del contrato de Office/PDF que autorizaste — semántica, visual y criptográficamente — antes de que el documento sea entregado.

ArtifactDiff es local-first y offline. Convierte una edición solicitada, como “cambiar el período de pago de 30 días a 45 días”, en una política congelada, verifica el candidato y escribe un Review Bundle inmutable que tanto humanos como agentes pueden inspeccionar.

Estado del proyecto: 0.1.0 alpha. El núcleo contract-safe y el Golden Path firmado están implementados y cubiertos por más de 900 pruebas automatizadas. El empaquetado y la automatización de lanzamiento público aún están en progreso.

Qué detecta

ArtifactDiff está deliberadamente diseñado para fallar de forma cerrada. La revisión sigue siendo bloqueante por defecto y un hallazgo de FALLO no puede ser aprobado.

Related MCP server: Proof Layer MCP

Golden Path de tres minutos

Requisitos previos: Python 3.11+ y una copia local de este repositorio. La demo usa solo contratos sintéticos y no realiza ninguna solicitud de red después de instalar las dependencias.

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

La ejecución crea tres Review Bundles firmados con Ed25519 y verificados de forma independiente:

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

El caso review permanece bloqueado. Para demostrar la transición de cadena de eventos firmada con un revisor humano sintético explícitamente simulado, usa un directorio de salida diferente:

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

--approve-review es solo para demo. Las aprobaciones reales siguen siendo acciones humanas interactivas a través de artifactdiff review o artifactdiff approve; los agentes no pueden aprobar sus propios hallazgos. Consulta el recorrido del Golden Path para ver los archivos generados y los límites de privacidad.

El flujo de trabajo

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

El Review Bundle es el sistema de registro. El escritorio de revisión local es solo una interfaz de loopback autenticada sobre ese bundle.

Interfaces humanas y de automatización

El mismo límite de aplicación impulsa todas las interfaces:

• CLI: crear/validar/sellar políticas, abrir sesiones controladas, verificar cambios, inspeccionar hallazgos, aprobar hallazgos y verificar o empaquetar bundles.

• Escritorio de revisión local: inspeccionar un bundle y firmar un hallazgo a la vez sin enviar contratos ni claves privadas a JavaScript del navegador.

• MCP: herramientas acotadas de inspección/borrador/validación/verificación local para agentes de IA, con raíces de entrada y salida separadas y sin capacidad de aprobación ni firma verificada.

• HTML offline: informes de revisión humana portátiles vinculados a hechos verificados.

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

Para un host MCP, configura raíces absolutas separadas por separadores de ruta antes de iniciar el servidor stdio:

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

MCP intencionalmente no puede aprobar hallazgos ni realizar firmas verificadas.

Por qué esto no es otro diff de PDF

Modelo de seguridad y privacidad

• Local-first y offline; no se requiere cuenta ni servicio en la nube.

• contract-safe está habilitado por defecto, sin autorización implícita.

• Las ediciones esperadas exactas están vinculadas a su cláusula y ocurrencia.

• Partes, dinero, monedas, fechas, duraciones, porcentajes, encabezados, pies de página, firmas, sellos y anexos están protegidos por defecto.

• Ed25519 offline es el mecanismo de confianza central; la identidad empresarial se puede agregar mediante adaptadores más adelante.

• La evidencia por defecto es minimal; full es explícito y sealed está cifrado para destinatarios nombrados.

• Las respuestas de MCP están acotadas y no devuelven contratos completos, imágenes de páginas ni material de claves.

Lee el diseño de la puerta de verificación aprobado y el registro de aceptación del Plan 4.5 para conocer el modelo completo de confianza y veredicto.

Soporte de formatos actual

• PDF → PDF

• DOCX → DOCX

• DOCX → PDF

• Estructura de contratos en inglés, chino y bilingüe

• Renderizado opcional de DOCX mediante LibreOffice; el renderizado de PDF es local

Desarrollo

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

El repositorio actualmente contiene cobertura de aceptación de pruebas unitarias, de integración, de manipulación, CLI, MCP, escritorio de revisión, formato cruzado y Golden Path firmado.

Próximos hitos

• Corpus sintético público reproducible y puerta de cero falsos positivos

• Acción de GitHub para revisión de solicitudes de extracción de documentos binarios

• Medios de demostración y Review Bundle de ejemplo descargable

• Esquemas, modelo de amenazas, SBOM, procedencia y lanzamiento alpha firmado

• Límites de complementos para analizadores, renderizadores, firmas, cifrado y almacenamiento empresariales

ArtifactDiff se está construyendo en torno a una promesa concreta: cuando un agente edita un contrato, puedes demostrar exactamente qué se le permitió cambiar — y que no cambió nada más.