Archify Architecture Delta Proof System: Completeness Levels and Deterministic Contracts

The Archify architecture delta proof system is a deterministic, offline contract that generates cryptographically verifiable receipts proving exactly what changed between two validated JSON snapshots, supporting two proof levels (authored and revision-pinned) and a strict completeness guarantee.

Archify's architecture delta proof system provides a deterministic way to verify changes between validated architecture snapshots without relying on live services. According to the tt-a1i/archify source code, this system produces self-contained HTML artifacts and machine-readable receipts that CI pipelines and reviewers can consume to validate architectural changes. The proof system is implemented primarily in archify/delta/architecture-delta.mjs and exposed through the CLI entry point at archify/bin/archify.mjs.

Core Principles of the Delta Proof System

The proof system operates as an atomic, fail-closed workflow that treats validation, comparison, artifact generation, and receipt writing as a single transaction.

Deterministic Matching via Stable IDs

The system strictly matches entities using stable IDs (components[].id and connections[].id). No label-based, position-based, or similarity-based guessing is permitted during comparison. This constraint ensures that the same inputs always produce identical outputs, a requirement for cryptographic verification.

Visual Delta Presentation with Phantoms

The delta overlay visualizes four change types: added (+), removed (−), changed (~), and moved (↔). Removed entities persist as phantoms in the visualization, preserving the spatial memory of the baseline architecture while indicating deletion.

Atomic Fail-Closed Execution

Validation, comparison, artifact generation, and receipt writing execute as a single atomic step. Any failure aborts the entire run and leaves previous artifacts untouched, preventing partial or corrupted delta states from reaching downstream consumers.

Proof Levels and Completeness Guarantees

The receipt includes two critical contract fields: proofLevel and completeness. These are enumerated in the design document at docs/research-architecture-delta-pr-proof-2026-07-23.md (lines 68-70).

The Authored Proof Level

The authored level verifies that both input snapshots contain a validated meta.repository field, or that neither contains one. This level proves only that authored facts changed between the base and head snapshots. It makes no claims about pull request safety, impact analysis, or semantic correctness.

The Revision-Pinned Proof Level

The revision-pinned level requires both sides to contain identical 40-character Git SHAs. This proves the inputs are exact revisions that passed Archify's repository-evidence gate. While stronger than authored, this level still explicitly does not claim PR safety or architectural impact.

Completeness Validation

The receipt always includes a "completeness" field set to "complete" when the compare operation succeeds and contains all required sections (schema version, command, proof level, component/connection change arrays, etc.). According to docs/research-next-stability-delight-2026-07-23.md (lines 77-80), downstream tools like the Delta Review Navigator reject any receipt where completeness !== "complete".

A valid receipt follows this structure (excerpt from docs/research-architecture-delta-pr-proof-2026-07-23.md, lines 138-141):

{
  "schemaVersion": 1,
  "ok": true,
  "command": "compare",
  "type": "architecture",
  "comparatorVersion": 1,
  "completeness": "complete",
  "proofLevel": "authored"
}

Generating and Consuming Delta Artifacts

You can generate delta artifacts using the Archify CLI or inspect receipts programmatically.

Command-Line Generation

Run the deterministic compare routine via the CLI entry point (implemented at archify/bin/archify.mjs, lines 420-444):

node archify/bin/archify.mjs compare architecture \
    base.json head.json architecture-delta.html --json

This command executes the comparison logic in archify/delta/architecture-delta.mjs, producing both an HTML visualization and a sidecar JSON receipt (architecture-delta.html.json).

Programmatic Receipt Inspection

Parse the receipt to verify proof levels before deploying changes:

import fs from 'fs';

const receipt = JSON.parse(
  fs.readFileSync('architecture-delta.html.json', 'utf8')
);

console.log('Proof level:', receipt.proofLevel);
console.log('Completeness:', receipt.completeness);
console.log('Summary:', receipt.summary);

CI Pipeline Integration

Integrate the proof system into GitHub Actions to publish delta summaries safely:

- name: Run Archify delta
  run: node archify/bin/archify.mjs compare architecture base.json head.json delta.html --json

- name: Publish delta summary
  run: |
    receipt=$(cat delta.html.json)
    echo "## Architecture Delta Summary" >> $GITHUB_STEP_SUMMARY

    echo "Proof level: ${{ fromJson(receipt).proofLevel }}" >> $GITHUB_STEP_SUMMARY
    echo "Completeness: ${{ fromJson(receipt).completeness }}" >> $GITHUB_STEP_SUMMARY

The receipt strips repository-specific URLs and paths by contract, making it safe to expose in public CI logs.

Key Implementation Files

File	Role
archify/delta/architecture-delta.mjs	Core compare implementation that produces HTML deltas and JSON receipts
archify/bin/archify.mjs	CLI entry point handling argument parsing and runtime wiring
docs/research-architecture-delta-pr-proof-2026-07-23.md	Formal contract specifying proof levels and completeness guarantees
docs/research-next-stability-delight-2026-07-23.md	Consumer requirements including completeness validation rules
archify/test/architecture-delta.test.mjs	Determinism tests ensuring identical inputs yield identical receipts
examples/checkout-platform-delta.html	Live example of the three-view (Before | Delta | After) UI output

Summary

• Archify's delta proof system provides deterministic, offline verification of architectural changes between two JSON snapshots.
• Stable ID matching ensures reproducibility by using only components[].id and connections[].id, never labels or positions.
• Two proof levels exist: authored (repository verification) and revision-pinned (exact Git SHA verification).
• Completeness must be "complete" for the receipt to be valid; incomplete receipts are rejected by downstream tools.
• Atomic execution guarantees that failures leave no partial artifacts, maintaining system integrity.

Frequently Asked Questions

What does the completeness field indicate in Archify receipts?

The completeness field certifies that the compare run was fully deterministic and successful. When set to "complete", it guarantees the receipt contains all required sections (schema version, command, proof level, change arrays) and that identical inputs will always yield identical HTML, compare-IR, semantic hash, and receipt outputs. Downstream consumers like the Delta Review Navigator explicitly require this flag to be "complete" before processing.

What is the difference between authored and revision-pinned proof levels?

Authored proves that both snapshots have verified repository metadata or none at all, establishing that the changes reflect authored facts. Revision-pinned requires both snapshots to share identical 40-character Git SHAs, proving they are exact revisions that passed Archify's repository-evidence gate. Neither level claims that the changes are safe to merge or have no architectural impact; they only establish provenance and identity.

How does the proof system handle moved components?

The delta visualization marks moved components with a ↔ symbol while preserving their original geometry as phantoms in the baseline view. The underlying receipt tracks these as distinct change entries, allowing reviewers to see both the origin and destination of architectural elements without losing spatial context.

Why does the system restrict matching to stable IDs only?

Restricting entity matching to stable IDs (components[].id and connections[].id) eliminates ambiguity from label changes, repositioning, or refactors. This constraint ensures the proof system remains deterministic and cryptographically verifiable, as any heuristic matching (by name, position, or similarity) could introduce non-determinism and break the guarantee that identical inputs produce identical receipts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}