qzx diagnoseStorage

Observed output example

Captured with QZX 0.2.2.0.15 on Windows 11; exit code 0. Host-dependent values and duration can vary.

Example command: qzx diagnoseStorage ../artifacts/qzx-evidence/storage-triage --min-file-size 1KB --max-files 10 --duplicate-min-size-kb 1 --max-depth 2 --json

{
    "success": true,
    "message": "Storage diagnosis completed for 'C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage': 99.4% used with 19.85 GB free; 3 file(s) matched the large-file threshold. Confirmed 1 duplicate group(s) with 9.75 KB of redundant logical content. QZX did not delete or modify any files.",
    "path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage",
    "partial": false,
    "read_only": true,
    "scan_scope": {
        "max_depth": 2,
        "depth_inclusive": true,
        "large_file_min_size": "1KB",
        "max_large_files_returned": 10,
        "duplicate_scan_requested": true,
        "duplicate_min_size_kb": 1
    },
    "probe_status": {
        "capacity": "ok",
        "large_files": "ok",
        "duplicates": "ok"
    },
    "assessment": {
        "capacity_status": "critical",
        "percent_used": 99.4,
        "total_bytes": 3718889074688,
        "total_readable": "3.38 TB",
        "free_bytes": 21313945600,
        "free_readable": "19.85 GB",
        "large_files_matched": 3,
        "large_files_returned": 3,
        "duplicate_groups": 1,
        "duplicate_files": 2,
        "confirmed_reclaimable_bytes": 9984,
        "confirmed_reclaimable_readable": "9.75 KB",
        "reclaimable_space_basis": "logical_content_bytes",
        "physical_reclaimable_bytes": null
    },
    "capacity": {
        "success": true,
        "message": "Disk information for 'C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage': 3.36 TB used of 3.38 TB total (99.4% used), 19.85 GB free.",
        "disk_info": {
            "path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage",
            "total_bytes": 3718889074688,
            "used_bytes": 3697575129088,
            "free_bytes": 21313945600,
            "total": "3.38 TB",
            "used": "3.36 TB",
            "free": "19.85 GB",
            "percent": 99.4
        }
    },
    "large_files": {
        "success": true,
        "message": "Found 3 matching files in 'C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage'. Returning 3 files totaling 26.25 KiB.",
        "search_path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage",
        "pattern": "*",
        "recursive": 2,
        "filters": {
            "min_size_bytes": 1024,
            "max_size_bytes": null,
            "modified_after": null,
            "modified_before": null,
            "exclude": [],
            "exclude_dirs": []
        },
        "sort": {
            "by": "size",
            "descending": true
        },
        "matched_count": 3,
        "matched_size_bytes": 26880,
        "matched_size_readable": "26.25 KiB",
        "count": 3,
        "total_size_bytes": 26880,
        "total_size_readable": "26.25 KiB",
        "limit": 10,
        "truncated": false,
        "partial": false,
        "scan_complete": true,
        "skipped_unreadable": 0,
        "skipped_search_paths": 0,
        "skipped_special_files": 0,
        "warnings": [],
        "results": [
            {
                "name": "duplicate-b.bin",
                "path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-b.bin",
                "relative_path": "duplicate-b.bin",
                "depth": 0,
                "size_bytes": 9984,
                "size_readable": "9.75 KiB",
                "modified_timestamp": 1791521129.78047,
                "modified_at": "2026-10-08T23:45:29-05:00"
            },
            {
                "name": "duplicate-a.bin",
                "path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-a.bin",
                "relative_path": "duplicate-a.bin",
                "depth": 0,
                "size_bytes": 9984,
                "size_readable": "9.75 KiB",
                "modified_timestamp": 1791521129.78047,
                "modified_at": "2026-10-08T23:45:29-05:00"
            },
            {
                "name": "unique.bin",
                "path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\unique.bin",
                "relative_path": "unique.bin",
                "depth": 0,
                "size_bytes": 6912,
                "size_readable": "6.75 KiB",
                "modified_timestamp": 1791521129.7814698,
                "modified_at": "2026-10-08T23:45:29-05:00"
            }
        ]
    },
    "duplicates": {
        "success": true,
        "message": "Duplicate files scan completed for 'C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage':\n- Verified duplicate groups: 1; independent file copies: 2.\n- Redundant logical content: 9.75 KB if one copy per group is kept.\n- Scope: directory depth 0 through 2, inclusive; minimum file size 1.00 KB.\n- Hardlink aliases excluded from copy counts: 0.\n\nTop duplicate groups to review (byte-for-byte verified):\n  1. 9.75 KB redundant logical content; 2 independent copies of 9.75 KB each.\n     C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-a.bin\n     C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-b.bin\n\nCoverage: 1 directories, 3 files examined; 2 independent files hashed.\nExcluded from traversal: 0 dependency directories, 0 directory links; 0 directories beyond the requested depth.\nResult completeness: complete within the stated scope.\n\nRedundant logical content is not a measurement of recoverable physical disk space. Hardlink aliases are not independent copies; compression, sparse files, shared extents and snapshots can change the space actually freed.\nReview each group and keep an intentional copy before making any changes.\nQZX did not delete or modify any files.",
        "scan_path": "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage",
        "total_groups": 1,
        "total_duplicate_files": 2,
        "reclaimable_bytes": 9984,
        "reclaimable_space_readable": "9.75 KB",
        "reclaimable_space_basis": "logical_content_bytes",
        "physical_reclaimable_bytes": null,
        "space_estimate_note": "Redundant logical content is not a measurement of recoverable physical disk space. Hardlink aliases are not independent copies; compression, sparse files, shared extents and snapshots can change the space actually freed.",
        "duplicate_groups": {
            "2467aef9f30a32bd4940b61dc4cd366c8c4f1677f514591d8cf1e0acf61f158e": {
                "sha256": "2467aef9f30a32bd4940b61dc4cd366c8c4f1677f514591d8cf1e0acf61f158e",
                "verification": "byte_for_byte",
                "size_bytes": 9984,
                "size_readable": "9.75 KB",
                "files": [
                    "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-a.bin",
                    "C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-b.bin"
                ],
                "independent_file_count": 2,
                "reclaimable_bytes": 9984
            }
        },
        "hardlink_aliases": [],
        "read_only": true,
        "partial": false,
        "scan_complete": true,
        "scan_scope": {
            "max_depth": 2,
            "depth_inclusive": true,
            "min_size_bytes": 1024,
            "excluded_directories": [
                ".git",
                ".venv",
                "env",
                "node_modules"
            ],
            "follow_directory_links": false,
            "hydrate_offline_files": false
        },
        "scan_statistics": {
            "directories_scanned": 1,
            "files_seen": 3,
            "independent_files": 3,
            "files_hashed": 2,
            "hash_attempts": 2,
            "byte_comparisons": 1,
            "hardlink_aliases_skipped": 0,
            "below_minimum_skipped": 0,
            "file_links_skipped": 0,
            "special_files_skipped": 0,
            "directory_links_skipped": 0,
            "excluded_directories": 0,
            "depth_limited_directories": 0,
            "offline_files_skipped": 0
        },
        "warnings": [],
        "warning_count": 0,
        "warning_counts": [],
        "warning_sample_truncated": false
    },
    "recommendations": [
        {
            "priority": "high",
            "action": "Review the largest files and confirmed duplicate groups before adding more data.",
            "reason": "The target filesystem is 99.4% used."
        },
        {
            "priority": "review",
            "action": "Inspect the returned large-file paths and decide which are intentional; size alone is never a deletion signal.",
            "reason": "Files at or above 1KB were found within depth 2."
        },
        {
            "priority": "review",
            "action": "Review each duplicate group and keep at least one intentional copy before removing anything manually.",
            "reason": "Byte-for-byte verification found 1 group(s) with 9.75 KB of redundant logical content; actual physical disk savings were not measured."
        },
        {
            "priority": "info",
            "action": "Use getDiskHealth separately only when hardware health is relevant; capacity pressure does not imply a failing disk.",
            "reason": "S.M.A.R.T. health and filesystem capacity are separate diagnostic questions."
        }
    ],
    "warnings": [],
    "related_commands": [
        "getDiskSpace",
        "findFiles",
        "findDuplicateFiles",
        "getDiskHealth"
    ],
    "report": "Storage diagnosis: C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\nFilesystem capacity: 99.4% used; 19.85 GB free of 3.38 TB. Status: critical.\nLarge files: 3 matched; 3 returned for review.\n\nLargest files to review (size alone is not a deletion signal):\n  1. 9.75 KB  C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-b.bin\n  2. 9.75 KB  C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-a.bin\n  3. 6.75 KB  C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\unique.bin\n\nDuplicates: 1 verified group(s), 2 independent file copies, up to 9.75 KB reclaimable content (logical bytes; physical disk savings not measured).\n  1. 9.75 KB redundant logical content; 2 independent copies of 9.75 KB each.\n     C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-a.bin\n     C:\\Team Dropbox\\Valis Idealis\\Ale\\Programacion\\QZX - Quick Zap Exchange\\artifacts\\qzx-evidence\\storage-triage\\duplicate-b.bin\n\nScope: directory depth 0 through 2 (inclusive); large-file threshold 1KB; duplicate threshold 1 KiB.\nThresholds and directory exclusions limit coverage; see scan_scope and the probe results in --json.\nResult completeness: complete within the requested scope and enabled probes.\n\nRedundant logical content is not a measurement of recoverable physical disk space. Hardlink aliases are not independent copies; compression, sparse files, shared extents and snapshots can change the space actually freed.\nSafety: read-only diagnosis; QZX did not delete or modify files.",
    "meta": {
        "command": "diagnoseStorage",
        "command_maturity": {
            "stage": "alpha",
            "label": "Alpha",
            "sequence": 2,
            "public_executable": true,
            "stability": "interface_may_change",
            "summary": "Available for real use and feedback while its interface and behavior can still evolve.",
            "promotion_review_required": false,
            "assessment_scope": "development_checkout"
        },
        "duration_ms": 8.26,
        "schema_version": 1
    }
}

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": [
        "success",
        "message",
        "meta"
    ],
    "properties": {
        "success": {
            "type": "boolean"
        },
        "message": {
            "type": "string"
        },
        "meta": {
            "type": "object",
            "required": [
                "command",
                "command_maturity",
                "duration_ms",
                "schema_version"
            ],
            "properties": {
                "command": {
                    "type": "string"
                },
                "command_maturity": {
                    "type": "object",
                    "required": [
                        "stage",
                        "label",
                        "sequence",
                        "public_executable",
                        "stability",
                        "summary",
                        "promotion_review_required",
                        "assessment_scope"
                    ],
                    "properties": {
                        "stage": {
                            "type": "string"
                        },
                        "label": {
                            "type": "string"
                        },
                        "sequence": {
                            "type": "integer"
                        },
                        "public_executable": {
                            "type": "boolean"
                        },
                        "stability": {
                            "type": "string"
                        },
                        "summary": {
                            "type": "string"
                        },
                        "promotion_review_required": {
                            "type": "boolean"
                        },
                        "assessment_scope": {
                            "type": "string"
                        },
                        "note": {
                            "type": "string"
                        },
                        "review": {
                            "type": "object",
                            "required": [
                                "reviewed_on",
                                "rationale",
                                "evidence"
                            ],
                            "properties": {
                                "reviewed_on": {
                                    "type": "string",
                                    "format": "date"
                                },
                                "rationale": {
                                    "type": "string"
                                },
                                "evidence": {
                                    "type": "array",
                                    "minItems": 1,
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "replacement": {
                                    "type": "string"
                                }
                            },
                            "additionalProperties": false
                        }
                    },
                    "additionalProperties": true
                },
                "duration_ms": {
                    "type": "number"
                },
                "schema_version": {
                    "type": "integer"
                }
            },
            "additionalProperties": true
        },
        "assessment": [],
        "capacity": [],
        "details": [],
        "duplicates": [],
        "error": [],
        "error_code": [],
        "large_files": [],
        "partial": [],
        "path": [],
        "probe_status": [],
        "read_only": {
            "type": "boolean"
        },
        "recommendations": [],
        "related_commands": {
            "type": "array"
        },
        "report": [],
        "scan_scope": {
            "type": "object",
            "properties": {
                "max_depth": [],
                "depth_inclusive": {
                    "type": "boolean"
                },
                "large_file_min_size": [],
                "max_large_files_returned": [],
                "duplicate_scan_requested": [],
                "duplicate_min_size_kb": []
            },
            "additionalProperties": true
        },
        "warnings": []
    },
    "additionalProperties": true
}

Errors and limits

The public contract requires success=false and a descriptive message on failure. This catalog does not yet declare a command-specific error taxonomy; inspect the result and do not invent error codes.

QZX is alpha software. Optional dependencies, permissions, and host capabilities can change the result.

Evidence workflow: captured and digest-validated.