Rootwise

Audit-first filesystem inventory and evidence-based storage planning for large, disorganized data collections.

Rootwise is a local-first tool for understanding what is stored on a drive before making decisions about preservation, archival, reorganization, or space recovery. It records a bounded metadata inventory outside the source volume, supports query-only review and separate human decisions, derives explainable analysis, and produces non-executable planning proposals.

Current status: 0.23.0-alpha

Rootwise is unreleased and not approved for irreplaceable production data or the original 3.9+ TB collection that motivated it. The current acceptance state is INCOMPLETE.

Core capabilities

• Metadata inventory: bounded, resumable traversal without reading source-file contents.
• Read-only review: query-only inventory search and an optional PySide6 interface.
• Separate decisions: revision-checked human decisions and notes outside the raw inventory.
• Explainable analysis: structural roles, relationships, uncertainty, and Pareto review ranking.
• Proposal-only planning: independently validated storage proposals with no execution ability.
• Permissioned evidence: explicit, bounded content hashing isolated from ordinary review.

Architecture

Source filesystem
        |
        | metadata only
        v
Core scanner --> inventory.db --> Viewer --------> decisions.db
                         |
                         +-----> Analysis --------> derived evidence
                                                    |
decisions.db ---------------------------------------+
                                                    v
                                                 Planning
                                                    |
                                                    v
                                         non-executable proposal

Optional content-reading evidence crosses a separate permission boundary. Validation evaluates artifacts and external evidence but grants no filesystem authority. Rootwise has no archive executor.

See ARCHITECTURE.md for component responsibilities, artifact lifecycles, and trust boundaries.

Quick development setup

The locked reference environment uses CPython 3.12 on Windows x86-64 or manylinux x86-64. From a PowerShell prompt in a clone:

$ErrorActionPreference = "Stop"
py -3.12 tools\bootstrap.py --profile full
$Python = (Resolve-Path ".\.venv\Scripts\python.exe").Path
$Rootwise = (Resolve-Path ".\.venv\Scripts\rootwise.exe").Path
& $Rootwise --help

Bootstrap installs hash-locked dependencies, Rootwise itself, and runs the installed command smoke check. The core runtime still has no third-party dependencies; use the lighter core or headless profile when appropriate. Follow DEVELOPMENT.md for expected output, tests, and the synthetic end-to-end workflow.

Command hierarchy

One rootwise command exposes the six architectural domains:

Task	Command
Scan, export, report, capabilities	rootwise scan ...
Search, decisions, GUI	rootwise view ...
Structural, ranking, temporal, and fused analysis	rootwise analyze ...
Optimize, approve, and preflight proposals	rootwise plan ...
Permissioned and declared evidence	rootwise evidence ...
Acceptance and release evidence	rootwise verify ...

rootwise scan --help
rootwise view --help
rootwise analyze --help
rootwise plan --help
rootwise evidence --help
rootwise verify --help

Run the relevant group or operation with --help before supplying paths. Compatibility scripts remain installed temporarily and print their canonical replacement when invoked.

Safety boundary

The default scanner does not read source-file contents, write to the source volume, create archives, move, rename, copy, link, or delete files, invoke subprocesses, or access the network. Symlinks, junctions, and reparse points are recorded rather than followed.

Viewer and analysis components consume recorded snapshots instead of opening observed live paths. A decision, ranking, plan, approval receipt, or preflight manifest never establishes that an original file is safe to remove.

Read SECURITY.md, the safety invariants, and the threat model before changing a source-facing boundary.

Major limitations

• The complete million-entry scanner, viewer, and analysis campaign has not run.
• Independent-host replication is incomplete.
• The ordinary viewer is functional but not a complete daily-use file browser.
• Optimizer, enrichment, and derived-evidence scale behavior is not accepted for real data.
• Supplied acceptance evidence is digest-bound but not authenticated.
• No Rust scanner, content-preview service, archive executor, or filesystem action component exists.
• Real-drive use remains prohibited until the required evidence and operator review are complete.

Documentation

The primary developer reading path is intentionally limited to three documents:

1. This product overview.
2. ARCHITECTURE.md for the system model and boundaries.
3. DEVELOPMENT.md for installation, testing, and contribution workflows.

After those, use the documentation index to find a specific schema, contract, or protocol. Historical implementation records are retained under docs/archive/, not mixed into the primary path. Release chronology remains in CHANGELOG.md.

License

Rootwise is licensed under the terms in LICENSE.