awstorage 0.1.0__tar.gz

awstorage-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

awstorage-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: awstorage
+Version: 0.1.0
+Summary: Scan a drive, get a ranked inventory of what fills it, classified re-fetchable or not, diffed against last time -- before you delete anything.
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Aitherium/awstorage
+Project-URL: Repository, https://github.com/Aitherium/awstorage.git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: recover
+Requires-Dist: awrecover>=0.1.0; extra == "recover"
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# awstorage
+
+**Every drive on every node, indexed, classified and diffed -- so you can see what you own before you delete it.**
+
+```bash
+pip install git+https://github.com/Aitherium/awstorage.git
+awstorage scan E:/ --depth 3 --catalog inventory.db
+awstorage inventory --catalog inventory.db
+awstorage propose --catalog inventory.db --snapshot 1
+awstorage apply   --catalog inventory.db --proposal 3 --root E:/        # dry run
+awstorage apply   --catalog inventory.db --proposal 3 --root E:/ --yes  # quarantine it
+awstorage revert  E:/.awstorage-quarantine/3-20260901T230000            # changed your mind
+```
+
+Stdlib only. Works alone, offline, on the box whose disk is full.
+
+## What it does
+
+1. **Scan** a root into a *snapshot*: every directory tree to a bounded depth with
+   its bytes, file count and newest mtime, plus the largest files. Bounded by a time
+   budget; a scan that runs out marks the snapshot `TRUNCATED` instead of printing a
+   total that looks complete and is not.
+2. **Classify** each tree: `package-cache`, `build-temp`, `model-weights`,
+   `container-store`, `dataset`, `backup`, `repo`, `logs`, `service-state`, `media`,
+   `vm-disk`, `unknown` -- and whether it is **re-fetchable**. Heuristics offline;
+   plug any `complete(prompt) -> str` model callable into `LLMClassifier` and every
+   verdict records whether a rule or a model made it, so a wrong call is auditable.
+3. **Catalog** snapshots in SQLite and **diff** them: what appeared, vanished, grew
+   and shrank since last time. "What filled the disk?" becomes a query.
+4. **Propose** actions under a written policy. Rules pre-approve only re-fetchable
+   classes past a size and an age; `service-state`, `dataset`, `vm-disk`, `backup` and
+   `unknown` are never auto. Everything else is proposed for a human to approve.
+5. **Apply** -- dry run by default. A delete is a **quarantine**: the tree is renamed
+   onto the same volume under `<root>/.awstorage-quarantine/`, `revert` puts it back
+   byte-for-byte, and only `quarantine --purge-older-than N --yes` reclaims the bytes.
+   `apply` refuses anything outside the declared roots, anything that changed since the
+   scan, and anything neither pre-approved nor approved. Every outcome is ledgered.
+
+## Python
+
+```python
+import awstorage
+from pathlib import Path
+
+snap = awstorage.classify_snapshot(awstorage.scan(Path("E:/"), max_depth=3))
+cat = awstorage.Catalog("inventory.db")
+sid = cat.put_snapshot(snap)
+for row in awstorage.rank(snap)[:10]:
+    print(row["exclusive_bytes"], row["cls"], row["refetchable"], row["path"])
+props = awstorage.propose(snap, awstorage.default_policy(), snapshot_id=sid)
+awstorage.apply(props[0], roots=[Path("E:/")], dry_run=True)
+```
+
+## The three rules
+
+- **Measure before you delete.** A `du` answers one question once.
+- **Re-fetchable is a property, not a guess.** The classifier says why.
+- **Deleting is a policy, not a mood.** Dry run, roots, fingerprints, quarantine, ledger.
+
+## Composes with
+
+- **awrecover** -- `backup_hook=lambda p: awrecover.snapshot(p, store, label)` turns
+  `backup-then-delete` into a restorable snapshot first.
+- **awdk / awnode / awsh** -- run the scanner where the disk is, post snapshots to a
+  shared catalog, render proposals in a shell or a desktop panel.
+- **awgraph** -- `awstorage graph` emits nodes and typed edges (`contains`,
+  `duplicate_of`) any graph store can ingest.
+
+`awstorage --self-test` proves the refusals still refuse and the quarantine still reverts.
+
+Apache-2.0.

awstorage-0.1.0/README.md

@@ -0,0 +1,71 @@
+# awstorage
+
+**Every drive on every node, indexed, classified and diffed -- so you can see what you own before you delete it.**
+
+```bash
+pip install git+https://github.com/Aitherium/awstorage.git
+awstorage scan E:/ --depth 3 --catalog inventory.db
+awstorage inventory --catalog inventory.db
+awstorage propose --catalog inventory.db --snapshot 1
+awstorage apply   --catalog inventory.db --proposal 3 --root E:/        # dry run
+awstorage apply   --catalog inventory.db --proposal 3 --root E:/ --yes  # quarantine it
+awstorage revert  E:/.awstorage-quarantine/3-20260901T230000            # changed your mind
+```
+
+Stdlib only. Works alone, offline, on the box whose disk is full.
+
+## What it does
+
+1. **Scan** a root into a *snapshot*: every directory tree to a bounded depth with
+   its bytes, file count and newest mtime, plus the largest files. Bounded by a time
+   budget; a scan that runs out marks the snapshot `TRUNCATED` instead of printing a
+   total that looks complete and is not.
+2. **Classify** each tree: `package-cache`, `build-temp`, `model-weights`,
+   `container-store`, `dataset`, `backup`, `repo`, `logs`, `service-state`, `media`,
+   `vm-disk`, `unknown` -- and whether it is **re-fetchable**. Heuristics offline;
+   plug any `complete(prompt) -> str` model callable into `LLMClassifier` and every
+   verdict records whether a rule or a model made it, so a wrong call is auditable.
+3. **Catalog** snapshots in SQLite and **diff** them: what appeared, vanished, grew
+   and shrank since last time. "What filled the disk?" becomes a query.
+4. **Propose** actions under a written policy. Rules pre-approve only re-fetchable
+   classes past a size and an age; `service-state`, `dataset`, `vm-disk`, `backup` and
+   `unknown` are never auto. Everything else is proposed for a human to approve.
+5. **Apply** -- dry run by default. A delete is a **quarantine**: the tree is renamed
+   onto the same volume under `<root>/.awstorage-quarantine/`, `revert` puts it back
+   byte-for-byte, and only `quarantine --purge-older-than N --yes` reclaims the bytes.
+   `apply` refuses anything outside the declared roots, anything that changed since the
+   scan, and anything neither pre-approved nor approved. Every outcome is ledgered.
+
+## Python
+
+```python
+import awstorage
+from pathlib import Path
+
+snap = awstorage.classify_snapshot(awstorage.scan(Path("E:/"), max_depth=3))
+cat = awstorage.Catalog("inventory.db")
+sid = cat.put_snapshot(snap)
+for row in awstorage.rank(snap)[:10]:
+    print(row["exclusive_bytes"], row["cls"], row["refetchable"], row["path"])
+props = awstorage.propose(snap, awstorage.default_policy(), snapshot_id=sid)
+awstorage.apply(props[0], roots=[Path("E:/")], dry_run=True)
+```
+
+## The three rules
+
+- **Measure before you delete.** A `du` answers one question once.
+- **Re-fetchable is a property, not a guess.** The classifier says why.
+- **Deleting is a policy, not a mood.** Dry run, roots, fingerprints, quarantine, ledger.
+
+## Composes with
+
+- **awrecover** -- `backup_hook=lambda p: awrecover.snapshot(p, store, label)` turns
+  `backup-then-delete` into a restorable snapshot first.
+- **awdk / awnode / awsh** -- run the scanner where the disk is, post snapshots to a
+  shared catalog, render proposals in a shell or a desktop panel.
+- **awgraph** -- `awstorage graph` emits nodes and typed edges (`contains`,
+  `duplicate_of`) any graph store can ingest.
+
+`awstorage --self-test` proves the refusals still refuse and the quarantine still reverts.
+
+Apache-2.0.

awstorage-0.1.0/awstorage/__init__.py

@@ -0,0 +1,97 @@
+"""awstorage -- every drive on every node, indexed, classified and diffed.
+
+Scan a root, get a SNAPSHOT: every directory tree down to a bounded depth with
+its bytes, file count and newest mtime, plus the largest files. Classify each
+tree (cache / build-temp / model-weights / dataset / backup / repo / logs /
+service-state / media / unknown) and mark whether it is RE-FETCHABLE. Store
+snapshots in a catalog and DIFF them, so "what grew since last week" is a
+query rather than a memory. Turn the classification into PROPOSALS under a
+written policy, and APPLY only what the policy pre-approves or a human
+approved -- dry-run by default, ledgered, and never outside a declared root.
+
+    import awstorage
+    from pathlib import Path
+
+    snap = awstorage.scan(Path("E:/"), max_depth=3, time_budget_s=120)
+    awstorage.classify_snapshot(snap)                # heuristics, offline
+    cat = awstorage.Catalog(Path("inventory.db"))
+    sid = cat.put_snapshot(snap)
+    for row in awstorage.rank(snap)[:20]:
+        print(row["bytes"], row["path"], row["cls"], row["refetchable"])
+    props = awstorage.propose(snap, awstorage.default_policy())
+    awstorage.apply(props[0], roots=[Path("E:/")], dry_run=True)
+
+Three rules it exists to enforce:
+
+**Measure before you delete.** A `du` answers one question once. A snapshot
+answers the same question every week, and the diff between two is the
+question you actually had ("what filled the disk?").
+
+**Re-fetchable is a property, not a guess.** A tree is re-fetchable when a
+known producer can recreate it (a package cache, a build output, a model
+weight that lives on a mirror). The classifier records WHY it decided that,
+and whether a heuristic or a model decided -- so a wrong call is auditable.
+
+**Deleting is a policy, not a mood.** `apply` refuses anything outside the
+declared roots, anything whose fingerprint changed since the scan, and any
+class the policy does not pre-approve unless a human approved that proposal.
+It writes a ledger row either way. A dry run is the default.
+
+The package is stdlib-only and speaks to nothing. Fleet integration (a scanner
+per node, a catalog behind an API, a GUI, an autonomous steward, model-backed
+classification) lives in the platform that imports it -- awstorage works alone.
+"""
+
+from __future__ import annotations
+
+from ._fs import SCHEMA_VERSION, ScanError, scan
+from .catalog import Catalog
+from .classify import (
+    CLASSES,
+    Classifier,
+    HeuristicClassifier,
+    LLMClassifier,
+    classify_snapshot,
+    classify_tree,
+)
+from .diff import diff_snapshots
+from .graph import to_graph
+from .policy import (
+    ApplyRefused,
+    Proposal,
+    apply,
+    default_policy,
+    list_quarantine,
+    propose,
+    purge_quarantine,
+    revert,
+)
+from .report import rank, summarize
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "ScanError",
+    "scan",
+    "Catalog",
+    "CLASSES",
+    "Classifier",
+    "HeuristicClassifier",
+    "LLMClassifier",
+    "classify_snapshot",
+    "classify_tree",
+    "diff_snapshots",
+    "to_graph",
+    "ApplyRefused",
+    "Proposal",
+    "apply",
+    "default_policy",
+    "list_quarantine",
+    "propose",
+    "purge_quarantine",
+    "revert",
+    "rank",
+    "summarize",
+    "__version__",
+]

awstorage-0.1.0/awstorage/_fs.py

@@ -0,0 +1,222 @@
+"""Bounded, resumable directory scanning -> a snapshot dict.
+
+A snapshot is a plain dict (JSON-serialisable) so it can cross any wire:
+
+    {"schema": 1, "node": "<hostname>", "root": "E:/", "taken_at": "...",
+     "max_depth": 3, "time_budget_s": 120, "truncated": false,
+     "trees": [ {"path": "E:/Caches", "depth": 1, "bytes": 157_000_000_000,
+                 "files": 12000, "dirs": 340, "newest_mtime": 1756000000.0,
+                 "oldest_mtime": 1700000000.0, "fingerprint": "sha1:..."} ],
+     "top_files": [ {"path": ..., "bytes": ..., "mtime": ...} ],
+     "errors": ["E:/System Volume Information: PermissionError"],
+     "elapsed_s": 41.2}
+
+`trees` holds every directory at depth <= max_depth (depth 0 is the root),
+each with the AGGREGATE of everything beneath it -- so a parent's bytes
+already include its children's. Consumers that want exclusive sizes subtract.
+
+The fingerprint is sha1 over (bytes, files, newest_mtime): cheap, and enough
+to notice that a tree changed between the scan and an apply. It is NOT a
+content hash; awstorage never reads file contents.
+
+Bounded on purpose: a scan that runs forever on a 4 TB drive is one nobody
+runs twice. `time_budget_s` stops the walk and marks the snapshot TRUNCATED
+(a real field, printed by every consumer) rather than returning a total that
+looks complete and is not.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import socket
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable
+
+SCHEMA_VERSION = 1
+
+# Directories that are never worth descending into: either they lie about size
+# (reparse/junction targets, /proc) or they are the OS's own business.
+DEFAULT_SKIP_NAMES = frozenset(
+    {
+        "$recycle.bin",
+        "system volume information",
+        "proc",
+        "sys",
+        "dev",
+        "run",
+    }
+)
+
+
+class ScanError(Exception):
+    """The scan could not run at all (root missing, unreadable, not a dir)."""
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _norm(p: Path) -> str:
+    # Forward slashes everywhere so the same tree has ONE spelling in the
+    # catalog whether it was scanned from Windows, WSL, or a Linux node.
+    return str(p).replace("\\", "/")
+
+
+def fingerprint(bytes_: int, files: int, newest_mtime: float) -> str:
+    h = hashlib.sha1(f"{bytes_}|{files}|{int(newest_mtime)}".encode())
+    return "sha1:" + h.hexdigest()[:16]
+
+
+def scan(
+    root: Path | str,
+    *,
+    max_depth: int = 3,
+    time_budget_s: float = 300.0,
+    top_files: int = 50,
+    skip_names: Iterable[str] = DEFAULT_SKIP_NAMES,
+    node: str | None = None,
+    follow_symlinks: bool = False,
+) -> dict:
+    """Walk `root` and return a snapshot dict. Never raises past the root check.
+
+    Per-entry errors (permission denied, vanished file) are recorded in
+    `errors` and the walk continues; only an unusable ROOT raises ScanError.
+    """
+    root_p = Path(root)
+    if not root_p.exists():
+        raise ScanError(f"root does not exist: {root}")
+    if not root_p.is_dir():
+        raise ScanError(f"root is not a directory: {root}")
+    skip = {s.lower() for s in skip_names}
+    t0 = time.monotonic()
+    deadline = t0 + float(time_budget_s)
+
+    # Aggregates keyed by the directory path (string), for dirs at depth <= max_depth.
+    agg: dict[str, dict] = {}
+    errors: list[str] = []
+    biggest: list[tuple[int, float, str]] = []  # (bytes, mtime, path) kept small
+    truncated = False
+
+    def account(dir_key: str, size: int, mtime: float, is_file: bool) -> None:
+        a = agg[dir_key]
+        a["bytes"] += size
+        if is_file:
+            a["files"] += 1
+        else:
+            a["dirs"] += 1
+        if mtime > a["newest_mtime"]:
+            a["newest_mtime"] = mtime
+        if mtime and (a["oldest_mtime"] == 0.0 or mtime < a["oldest_mtime"]):
+            a["oldest_mtime"] = mtime
+
+    def ensure(path_str: str, depth: int) -> None:
+        if path_str not in agg:
+            agg[path_str] = {
+                "path": path_str,
+                "depth": depth,
+                "bytes": 0,
+                "files": 0,
+                "dirs": 0,
+                "newest_mtime": 0.0,
+                "oldest_mtime": 0.0,
+                "git": False,
+            }
+
+    root_key = _norm(root_p)
+    ensure(root_key, 0)
+    # Stack of (dir path, depth, ancestors-at-or-below-max-depth keys)
+    stack: list[tuple[str, int, tuple[str, ...]]] = [(str(root_p), 0, (root_key,))]
+
+    while stack:
+        if time.monotonic() >= deadline:
+            truncated = True
+            break
+        d, depth, owners = stack.pop()
+        try:
+            it = os.scandir(d)
+        except OSError as exc:
+            errors.append(f"{_norm(Path(d))}: {type(exc).__name__}")
+            continue
+        with it:
+            for e in it:
+                try:
+                    if e.is_symlink() and not follow_symlinks:
+                        continue
+                    if e.is_dir(follow_symlinks=follow_symlinks):
+                        if e.name == ".git" and owners[-1] in agg:
+                            # A git working tree: its build outputs may be TRACKED
+                            # (tenant repos `git add -f` their dist/), so the policy
+                            # must not auto-delete inside one. Recorded, not decided.
+                            agg[owners[-1]]["git"] = True
+                        if e.name.lower() in skip:
+                            continue
+                        child_depth = depth + 1
+                        child_key = _norm(Path(e.path))
+                        for k in owners:
+                            account(k, 0, 0.0, is_file=False)
+                        if child_depth <= max_depth:
+                            ensure(child_key, child_depth)
+                            stack.append((e.path, child_depth, owners + (child_key,)))
+                        else:
+                            stack.append((e.path, child_depth, owners))
+                    else:
+                        st = e.stat(follow_symlinks=follow_symlinks)
+                        size = int(st.st_size)
+                        mtime = float(st.st_mtime)
+                        for k in owners:
+                            account(k, size, mtime, is_file=True)
+                        if top_files > 0:
+                            biggest.append((size, mtime, _norm(Path(e.path))))
+                            if len(biggest) > top_files * 4:
+                                biggest.sort(reverse=True)
+                                del biggest[top_files:]
+                except OSError as exc:
+                    errors.append(f"{_norm(Path(e.path))}: {type(exc).__name__}")
+
+    biggest.sort(reverse=True)
+    trees = []
+    for a in sorted(agg.values(), key=lambda x: (x["depth"], x["path"])):
+        a = dict(a)
+        a["fingerprint"] = fingerprint(a["bytes"], a["files"], a["newest_mtime"])
+        trees.append(a)
+
+    return {
+        "schema": SCHEMA_VERSION,
+        "node": node or socket.gethostname(),
+        "root": root_key,
+        "taken_at": _now_iso(),
+        "max_depth": int(max_depth),
+        "time_budget_s": float(time_budget_s),
+        "truncated": truncated,
+        "trees": trees,
+        "top_files": [
+            {"path": p, "bytes": b, "mtime": m} for b, m, p in biggest[:top_files]
+        ],
+        "errors": errors[:200],
+        "error_count": len(errors),
+        "elapsed_s": round(time.monotonic() - t0, 2),
+    }
+
+
+def exclusive_bytes(snapshot: dict) -> dict[str, int]:
+    """Bytes owned by each tree EXCLUDING its scanned children (depth-aware)."""
+    by_depth: dict[int, list[dict]] = {}
+    for t in snapshot["trees"]:
+        by_depth.setdefault(t["depth"], []).append(t)
+    children: dict[str, int] = {}
+    for depth, trees in by_depth.items():
+        if depth == 0:
+            continue
+        parents = by_depth.get(depth - 1, [])
+        for t in trees:
+            # The parent is the depth-1 tree whose path is the longest prefix of ours.
+            cand = [p["path"] for p in parents
+                    if t["path"].startswith(p["path"].rstrip("/") + "/")]
+            if cand:
+                parent = max(cand, key=len)
+                children[parent] = children.get(parent, 0) + t["bytes"]
+    return {t["path"]: max(0, t["bytes"] - children.get(t["path"], 0))
+            for t in snapshot["trees"]}