Trace Code Provenance with ArchWiz Forensics

ArchWiz includes a dedicated forensic toolchain for tracing where code came from, assessing the impact of a change before you make it, and recovering lost implementations. This guide walks you through a complete forensic investigation using the provenance and restoration tools available in the monorepo.

Research file history with archaeo

Start any investigation by pulling the full history of a target file. archaeo shows commits, authors, and message summaries.

archaeo src/auth/middleware.py

Expected output:

[archaeo] 14 commits for src/auth/middleware.py
a1e4c8d  2025-01-10  alice  "Add JWT validation"
7f3a9b2  2025-01-08  bob    "Refactor auth flow"
3d8e1f0  2025-01-05  alice  "Initial middleware scaffold"

Check impact before changing with oracle

Before you edit a file, run oracle to see which other files and tests depend on it.

oracle src/auth/middleware.py

Expected output:

[oracle] 7 dependents for src/auth/middleware.py
src/api/routes.py
src/api/handlers/login.py
tests/test_auth.py
tests/test_middleware.py
docs/proposals/active/auth-42/ITEMS.md

Run the forensic toolchain

Use forensic_toolchain.py to perform a full provenance scan. It orchestrates the fragment matcher, similarity scan, and correlation scout in one pass.

python3 archwiz/forensic_toolchain.py --target src/auth/middleware.py --depth 3

Expected output:

[forensic_toolchain] Starting scan: src/auth/middleware.py
[fragment_matcher] 4 function fragments tracked
[similarity_scan] 2 near-duplicate blocks found
[correlation_scout] 3 path migrations detected

Trace file-path changes with correlation_scout

When a file has moved or been renamed, correlation_scout.py traces its path across history and links the old and new locations.

python3 archwiz/correlation_scout.py --file src/auth/middleware.py --show-migrations

Expected output:

[correlation_scout] Path migrations for src/auth/middleware.py
2025-01-05  src/utils/auth.py        -> src/auth/middleware.py
2024-12-20  src/legacy/auth_old.py    -> src/utils/auth.py

Match function-level provenance with fragment_matcher

Drill down to individual functions to see when they were introduced, modified, or copied from another file.

python3 archwiz/fragment_matcher.py --file src/auth/middleware.py --function validate_token

Expected output:

[fragment_matcher] Function: validate_token
Origin: src/utils/auth.py @ commit 3d8e1f0
Migrated: src/auth/middleware.py @ commit 7f3a9b2
Last modified: 2025-01-10 @ a1e4c8d

Resurrect lost code with restore_version

If a function or file was deleted or broken in a recent commit, use restore_version.py to recover a known-good version.

python3 archwiz/restore_version.py --file src/auth/middleware.py --commit a1e4c8d --dry-run
python3 archwiz/restore_version.py --file src/auth/middleware.py --commit a1e4c8d

Expected output:

[restore_version] Dry-run: would restore src/auth/middleware.py from a1e4c8d
[restore_version] Restored src/auth/middleware.py from a1e4c8d

Always run oracle before restoring an old version. Restoring code without checking dependents can reintroduce outdated interfaces that break downstream modules.

Combine forensics with the knowledge indices for deeper reconnaissance. After running archaeo and oracle, query the index with archivist.py --file <target> --relationships to see the full dependency graph and cross-reference the historical timeline with structural impact.

For more on querying the knowledge base, see the Index rebuild guide. To understand how ArchWiz fits into the broader system, read the ArchWiz component overview.

Get Started

Concepts

Components

Guides

Governance

Proposals

Reference

Trace Code Provenance with ArchWiz Forensics