disk-coldstore 0.1.0__tar.gz

disk_coldstore-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

disk_coldstore-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: disk-coldstore
+Version: 0.1.0
+Summary: Tiered laptop storage reclaimer: find junk, LZX-compress cool folders, 7z-archive cold ones — all reversible.
+Author-email: Arya <arya1262023@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Arya-126/coldstore
+Project-URL: Repository, https://github.com/Arya-126/coldstore
+Project-URL: Issues, https://github.com/Arya-126/coldstore/issues
+Keywords: storage,disk-space,compression,7z,lzx,ntfs,windows,cleanup,archive
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Requires-Dist: send2trash>=1.8
+Requires-Dist: py7zr>=0.20
+Dynamic: license-file
+
+# ColdStore
+
+Tiered laptop storage reclaimer for Windows. Point it at a folder, get an
+honest, categorized plan of what can be freed, then apply the plan — every
+action is journaled and reversible.
+
+## What it does
+
+Three tiers, safest first:
+
+| Tier | Trigger | Action | Reversible via |
+| :--- | :--- | :--- | :--- |
+| **JUNK** | Regenerable folders (`node_modules`, `.venv`, `__pycache__`, browser caches, `Temp`) or app caches | Send to Recycle Bin | Restore via Shell.Application COM |
+| **COOL** | Not accessed in 30+ days, non-media content | NTFS/LZX compress in place with `compact.exe` | `compact /u /s /a /i /exe` |
+| **COLD** | Not accessed in 180+ days | 7z archive; original folder replaced with a `.coldstore` stub file | `coldstore restore <stub>` |
+
+Bonus: bit-exact **JPEG -> JPEG XL** lossless transcode using
+[libjxl](https://github.com/libjxl/libjxl) — reversible to the byte-identical
+original JPEG.
+
+## Install
+
+```bash
+pip install coldstore
+```
+
+Optional external tools that unlock extra performance / features:
+
+- **[7-Zip](https://www.7-zip.org/)** — if `7z.exe` is on PATH, cold archiving
+  uses the native binary (much faster on large folders). Otherwise the pure-Python
+  `py7zr` fallback is used automatically.
+- **[libjxl](https://github.com/libjxl/libjxl/releases)** — `cjxl.exe` /
+  `djxl.exe` on PATH enable the bit-exact JPEG -> JXL media tier.
+
+## Usage
+
+```
+coldstore scan     <path>                         # dry-run report of reclaimable space
+coldstore analyze  <path> [--tree]                # WizTree-style disk analysis
+coldstore apply    <path> --junk --cool --cold    # do the work
+coldstore restore  <stub.coldstore>               # restore an archived folder
+coldstore undo     --last N | --entry K           # undo previous actions
+coldstore journal  [--limit N]                    # timeline of everything done
+
+coldstore gui                                     # graphical interface
+coldstore register [--uninstall]                  # register .coldstore file association
+coldstore schedule --target <path> --cadence weekly
+
+coldstore media scan|apply|restore  <path>        # bit-exact JPEG <-> JXL
+```
+
+Recommended first run — read-only, no changes:
+
+```powershell
+coldstore analyze  C:\Users\%USERNAME% --tree --tree-depth 4 --tree-min-share 1
+coldstore scan     C:\Users\%USERNAME% --min-size-mb 100
+```
+
+Then, when you're ready to actually reclaim space:
+
+```powershell
+coldstore apply    C:\Users\%USERNAME% --min-size-mb 100 --junk --cool --cold
+```
+
+Every action is written to `%USERPROFILE%\.coldstore\actions.jsonl`. To undo
+anything:
+
+```powershell
+coldstore journal --limit 20
+coldstore undo --entry 14
+```
+
+## How the tiers avoid overlap
+
+If a folder qualifies as COOL/COLD but contains a JUNK sub-folder, the
+container's projection subtracts the JUNK bytes before estimating savings. The
+report therefore never double-counts across tiers.
+
+## Safety
+
+- Every action is journaled with before/after bytes.
+- JUNK goes to the Recycle Bin (never hard-deleted).
+- COLD archives are integrity-verified with `7z t` (or py7zr's `testzip`)
+  before the original folder is removed.
+- OneDrive cloud-placeholder files are detected via `GetFileAttributesW` (real
+  attribute check, not a path heuristic) and excluded by default.
+- Never touches `C:\Windows`, `Program Files`, `ProgramData`, or the Recycle Bin.
+
+## Requirements
+
+- Windows 10 1607+ (LZX compression) or Windows 11
+- Python 3.10+
+- NTFS filesystem for the COOL tier
+
+## License
+
+MIT

disk_coldstore-0.1.0/README.md

@@ -0,0 +1,97 @@
+# ColdStore
+
+Tiered laptop storage reclaimer for Windows. Point it at a folder, get an
+honest, categorized plan of what can be freed, then apply the plan — every
+action is journaled and reversible.
+
+## What it does
+
+Three tiers, safest first:
+
+| Tier | Trigger | Action | Reversible via |
+| :--- | :--- | :--- | :--- |
+| **JUNK** | Regenerable folders (`node_modules`, `.venv`, `__pycache__`, browser caches, `Temp`) or app caches | Send to Recycle Bin | Restore via Shell.Application COM |
+| **COOL** | Not accessed in 30+ days, non-media content | NTFS/LZX compress in place with `compact.exe` | `compact /u /s /a /i /exe` |
+| **COLD** | Not accessed in 180+ days | 7z archive; original folder replaced with a `.coldstore` stub file | `coldstore restore <stub>` |
+
+Bonus: bit-exact **JPEG -> JPEG XL** lossless transcode using
+[libjxl](https://github.com/libjxl/libjxl) — reversible to the byte-identical
+original JPEG.
+
+## Install
+
+```bash
+pip install coldstore
+```
+
+Optional external tools that unlock extra performance / features:
+
+- **[7-Zip](https://www.7-zip.org/)** — if `7z.exe` is on PATH, cold archiving
+  uses the native binary (much faster on large folders). Otherwise the pure-Python
+  `py7zr` fallback is used automatically.
+- **[libjxl](https://github.com/libjxl/libjxl/releases)** — `cjxl.exe` /
+  `djxl.exe` on PATH enable the bit-exact JPEG -> JXL media tier.
+
+## Usage
+
+```
+coldstore scan     <path>                         # dry-run report of reclaimable space
+coldstore analyze  <path> [--tree]                # WizTree-style disk analysis
+coldstore apply    <path> --junk --cool --cold    # do the work
+coldstore restore  <stub.coldstore>               # restore an archived folder
+coldstore undo     --last N | --entry K           # undo previous actions
+coldstore journal  [--limit N]                    # timeline of everything done
+
+coldstore gui                                     # graphical interface
+coldstore register [--uninstall]                  # register .coldstore file association
+coldstore schedule --target <path> --cadence weekly
+
+coldstore media scan|apply|restore  <path>        # bit-exact JPEG <-> JXL
+```
+
+Recommended first run — read-only, no changes:
+
+```powershell
+coldstore analyze  C:\Users\%USERNAME% --tree --tree-depth 4 --tree-min-share 1
+coldstore scan     C:\Users\%USERNAME% --min-size-mb 100
+```
+
+Then, when you're ready to actually reclaim space:
+
+```powershell
+coldstore apply    C:\Users\%USERNAME% --min-size-mb 100 --junk --cool --cold
+```
+
+Every action is written to `%USERPROFILE%\.coldstore\actions.jsonl`. To undo
+anything:
+
+```powershell
+coldstore journal --limit 20
+coldstore undo --entry 14
+```
+
+## How the tiers avoid overlap
+
+If a folder qualifies as COOL/COLD but contains a JUNK sub-folder, the
+container's projection subtracts the JUNK bytes before estimating savings. The
+report therefore never double-counts across tiers.
+
+## Safety
+
+- Every action is journaled with before/after bytes.
+- JUNK goes to the Recycle Bin (never hard-deleted).
+- COLD archives are integrity-verified with `7z t` (or py7zr's `testzip`)
+  before the original folder is removed.
+- OneDrive cloud-placeholder files are detected via `GetFileAttributesW` (real
+  attribute check, not a path heuristic) and excluded by default.
+- Never touches `C:\Windows`, `Program Files`, `ProgramData`, or the Recycle Bin.
+
+## Requirements
+
+- Windows 10 1607+ (LZX compression) or Windows 11
+- Python 3.10+
+- NTFS filesystem for the COOL tier
+
+## License
+
+MIT

disk_coldstore-0.1.0/coldstore/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

disk_coldstore-0.1.0/coldstore/__main__.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+from rich.console import Console
+
+from .analyze import print_analysis, print_tree
+from .report import build_candidates, print_report
+from .rules import classify
+from .scanner import scan
+
+
+def _do_scan(root: Path, verbose: bool):
+    con = Console()
+    con.print(f"[bold]Scanning[/bold] {root} ...")
+    started = time.time()
+
+    def on_progress(current: Path, count: int) -> None:
+        con.print(f"  [dim]{count} folders scanned — {current}[/dim]", highlight=False)
+
+    result = scan(root, on_progress=on_progress if verbose else None)
+    con.print(
+        f"[dim]Scan finished in {time.time() - started:.1f}s — "
+        f"{result.aggregate.total_folder_count:,} folders, "
+        f"{result.aggregate.total_file_count:,} files, "
+        f"{result.aggregate.total_bytes / (1024**3):.2f} GB[/dim]"
+    )
+    return result
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    root = Path(args.path).resolve()
+    if not root.exists():
+        print(f"error: path does not exist: {root}", file=sys.stderr)
+        return 2
+
+    result = _do_scan(root, args.verbose)
+    min_size = args.min_size_mb * 1024 * 1024
+    scanned = [(s, classify(s, min_size_bytes=min_size,
+                             cool_age_days=args.cool_days,
+                             cold_age_days=args.cold_days)) for s in result.folders]
+    candidates = build_candidates(scanned, min_size_bytes=min_size)
+    print_report(root, scanned, candidates, top_n=args.top)
+    return 0
+
+
+def cmd_analyze(args: argparse.Namespace) -> int:
+    root = Path(args.path).resolve()
+    if not root.exists():
+        print(f"error: path does not exist: {root}", file=sys.stderr)
+        return 2
+
+    result = _do_scan(root, args.verbose)
+    print_analysis(root, result.folders, result.aggregate,
+                   top_folders=args.top_folders,
+                   top_files=args.top_files,
+                   top_exts=args.top_exts)
+    if args.tree:
+        Console().print()
+        print_tree(root, result.folders, max_depth=args.tree_depth, min_share=args.tree_min_share / 100.0)
+    return 0
+
+
+def cmd_apply(args: argparse.Namespace) -> int:
+    from .apply import run_apply
+    root = Path(args.path).resolve()
+    if not root.exists():
+        print(f"error: path does not exist: {root}", file=sys.stderr)
+        return 2
+
+    result = _do_scan(root, args.verbose)
+    min_size = args.min_size_mb * 1024 * 1024
+    scanned = [(s, classify(s, min_size_bytes=min_size,
+                             cool_age_days=args.cool_days,
+                             cold_age_days=args.cold_days)) for s in result.folders]
+    candidates = build_candidates(scanned, min_size_bytes=min_size)
+    return run_apply(
+        root, candidates,
+        do_junk=args.junk,
+        do_cool=args.cool,
+        do_cold=args.cold,
+        yes=args.yes,
+    )
+
+
+def cmd_restore(args: argparse.Namespace) -> int:
+    from .recovery import cmd_restore as _restore
+    return _restore(Path(args.stub))
+
+
+def cmd_journal(args: argparse.Namespace) -> int:
+    from .recovery import cmd_journal_list
+    return cmd_journal_list(limit=args.limit)
+
+
+def cmd_undo(args: argparse.Namespace) -> int:
+    from .recovery import cmd_undo as _undo
+    return _undo(entry_number=args.entry, last_n=args.last)
+
+
+def cmd_gui(args: argparse.Namespace) -> int:
+    from .gui import run_gui
+    run_gui()
+    return 0
+
+
+def cmd_media(args: argparse.Namespace) -> int:
+    from .media import cmd_media_apply, cmd_media_scan, restore_one
+    if args.media_op == "scan":
+        return cmd_media_scan(Path(args.path))
+    if args.media_op == "apply":
+        return cmd_media_apply(Path(args.path), yes=args.yes)
+    if args.media_op == "restore":
+        result = restore_one(Path(args.jxl))
+        if result.ok:
+            print(f"restored: {result.path} {result.note}")
+            return 0
+        print(f"failed: {result.error}", file=sys.stderr)
+        return 1
+    return 2
+
+
+def cmd_register(args: argparse.Namespace) -> int:
+    from .integration import register_file_association, unregister_file_association
+    if args.uninstall:
+        ok, msg = unregister_file_association()
+    else:
+        ok, msg = register_file_association()
+    print(msg)
+    return 0 if ok else 1
+
+
+def cmd_schedule(args: argparse.Namespace) -> int:
+    from .integration import (create_scheduled_scan, delete_scheduled_scan,
+                              query_scheduled_scan)
+    if args.delete:
+        ok, msg = delete_scheduled_scan()
+    elif args.query:
+        ok, msg = query_scheduled_scan()
+    else:
+        if not args.target:
+            print("error: --target is required when creating a schedule", file=sys.stderr)
+            return 2
+        ok, msg = create_scheduled_scan(
+            target=Path(args.target),
+            cadence=args.cadence,
+            min_size_mb=args.min_size_mb,
+        )
+    print(msg)
+    return 0 if ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="coldstore", description="Tiered laptop storage reclaimer.")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    ps = sub.add_parser("scan", help="scan and report reclaimable space (no changes made)")
+    ps.add_argument("path")
+    ps.add_argument("--top", type=int, default=40)
+    ps.add_argument("--min-size-mb", type=int, default=50)
+    ps.add_argument("--cool-days", type=int, default=30)
+    ps.add_argument("--cold-days", type=int, default=180)
+    ps.add_argument("-v", "--verbose", action="store_true")
+    ps.set_defaults(func=cmd_scan)
+
+    pa = sub.add_parser("analyze", help="WizTree-style disk analysis (no changes made)")
+    pa.add_argument("path")
+    pa.add_argument("--top-folders", type=int, default=25)
+    pa.add_argument("--top-files", type=int, default=25)
+    pa.add_argument("--top-exts", type=int, default=20)
+    pa.add_argument("--tree", action="store_true", help="also print an indented folder tree")
+    pa.add_argument("--tree-depth", type=int, default=3)
+    pa.add_argument("--tree-min-share", type=float, default=1.0,
+                    help="prune tree branches below this percentage of root size (default 1.0)")
+    pa.add_argument("-v", "--verbose", action="store_true")
+    pa.set_defaults(func=cmd_analyze)
+
+    pap = sub.add_parser("apply", help="perform recommended actions (interactive by default)")
+    pap.add_argument("path")
+    pap.add_argument("--min-size-mb", type=int, default=50)
+    pap.add_argument("--cool-days", type=int, default=30)
+    pap.add_argument("--cold-days", type=int, default=180)
+    pap.add_argument("--junk", action="store_true", help="process JUNK candidates (Recycle Bin)")
+    pap.add_argument("--cool", action="store_true", help="process COOL candidates (compact.exe LZX)")
+    pap.add_argument("--cold", action="store_true", help="process COLD candidates (7z archive + stub)")
+    pap.add_argument("--yes", action="store_true", help="do not prompt for confirmation")
+    pap.add_argument("-v", "--verbose", action="store_true")
+    pap.set_defaults(func=cmd_apply)
+
+    pr = sub.add_parser("restore", help="restore a .coldstore stub back to its original folder")
+    pr.add_argument("stub", help="path to the .coldstore stub file")
+    pr.set_defaults(func=cmd_restore)
+
+    pj = sub.add_parser("journal", help="show recent journal entries")
+    pj.add_argument("--limit", type=int, default=30)
+    pj.set_defaults(func=cmd_journal)
+
+    pu = sub.add_parser("undo", help="undo one or more previous actions from the journal")
+    grp = pu.add_mutually_exclusive_group()
+    grp.add_argument("--entry", type=int, help="undo a specific journal entry number (see 'journal')")
+    grp.add_argument("--last", type=int, help="undo the last N successful actions")
+    pu.set_defaults(func=cmd_undo)
+
+    pg = sub.add_parser("gui", help="launch the graphical interface")
+    pg.set_defaults(func=cmd_gui)
+
+    pmed = sub.add_parser("media", help="bit-exact JPEG -> JPEG XL lossless transcode (requires libjxl)")
+    med_sub = pmed.add_subparsers(dest="media_op", required=True)
+    med_scan = med_sub.add_parser("scan", help="report JPEGs and estimated savings")
+    med_scan.add_argument("path")
+    med_apply = med_sub.add_parser("apply", help="transcode JPEGs to JXL with byte-exact verification")
+    med_apply.add_argument("path")
+    med_apply.add_argument("--yes", action="store_true")
+    med_restore = med_sub.add_parser("restore", help="restore a .jxl back to its bit-exact .jpg")
+    med_restore.add_argument("jxl")
+    pmed.set_defaults(func=cmd_media)
+
+    preg = sub.add_parser("register",
+        help="register .coldstore file association (double-click to restore)")
+    preg.add_argument("--uninstall", action="store_true", help="remove the association instead")
+    preg.set_defaults(func=cmd_register)
+
+    psch = sub.add_parser("schedule",
+        help="create/query/delete a Windows scheduled task that runs 'scan' periodically")
+    psch.add_argument("--target", help="folder to scan (required when creating a schedule)")
+    psch.add_argument("--cadence", choices=["daily", "weekly", "monthly"], default="weekly")
+    psch.add_argument("--min-size-mb", type=int, default=100)
+    psch.add_argument("--query", action="store_true", help="show the existing scheduled task")
+    psch.add_argument("--delete", action="store_true", help="remove the scheduled task")
+    psch.set_defaults(func=cmd_schedule)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

disk_coldstore-0.1.0/coldstore/actions.py

@@ -0,0 +1,157 @@
+"""Pure per-candidate action functions used by both the CLI and GUI.
+
+Each `do_*` function returns an `ItemResult` and does NOT print or journal.
+The caller owns UI + journaling."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .archive import ArchiveError, archive_folder
+from .journal import Action, Journal
+from .report import Candidate
+
+
+@dataclass(slots=True)
+class ItemResult:
+    ok: bool
+    op: str
+    path: str
+    before_bytes: int = 0
+    after_bytes: int = 0
+    note: str = ""
+    error: str | None = None
+    extras: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def bytes_freed(self) -> int:
+        return max(0, self.before_bytes - self.after_bytes)
+
+    @property
+    def ratio(self) -> float:
+        if self.after_bytes <= 0:
+            return 1.0
+        return self.before_bytes / self.after_bytes
+
+
+def _send_to_recycle_bin(path: Path) -> tuple[bool, str]:
+    try:
+        import send2trash
+        send2trash.send2trash(str(path))
+        return True, "send2trash"
+    except ImportError:
+        pass
+    except Exception as exc:
+        return False, f"send2trash failed: {exc!r}"
+
+    ps_script = (
+        "Add-Type -AssemblyName Microsoft.VisualBasic; "
+        "[Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory("
+        f"'{str(path).replace(chr(39), chr(39)*2)}',"
+        "'OnlyErrorDialogs','SendToRecycleBin')"
+    )
+    proc = subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command", ps_script],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        return False, f"powershell fallback failed: {proc.stderr.strip()[:200]}"
+    return True, "powershell-recyclebin"
+
+
+_COMPACT_STORED_RE = re.compile(
+    r"([\d,\.\s]+)\s+total bytes of data are stored in\s+([\d,\.\s]+)\s+bytes",
+    re.IGNORECASE,
+)
+
+
+def _parse_compact_output(out: str) -> tuple[int, int] | None:
+    m = _COMPACT_STORED_RE.search(out)
+    if not m:
+        return None
+    def _n(s: str) -> int:
+        return int(s.replace(",", "").replace(".", "").strip())
+    try:
+        return _n(m.group(1)), _n(m.group(2))
+    except ValueError:
+        return None
+
+
+def _compact_lzx(path: Path) -> tuple[bool, int, int, str]:
+    args = ["compact.exe", "/c", "/s", "/a", "/i", "/exe:LZX"]
+    try:
+        proc = subprocess.run(args, capture_output=True, text=True, cwd=str(path))
+    except FileNotFoundError:
+        return False, 0, 0, "compact.exe not found on PATH"
+    except OSError as exc:
+        return False, 0, 0, f"failed to chdir into {path}: {exc!r}"
+
+    out = (proc.stdout or "") + "\n" + (proc.stderr or "")
+    parsed = _parse_compact_output(out)
+    if parsed:
+        return proc.returncode == 0, parsed[0], parsed[1], "compact.exe stored/on-disk"
+    return proc.returncode == 0, 0, 0, (out.splitlines()[-1] if out.strip() else "no output")
+
+
+def do_recycle(candidate: Candidate) -> ItemResult:
+    before = candidate.stats.total_bytes
+    ok, note = _send_to_recycle_bin(candidate.stats.path)
+    return ItemResult(
+        ok=ok, op="recycle", path=str(candidate.stats.path),
+        before_bytes=before, after_bytes=0 if ok else before,
+        note=note, error=None if ok else note,
+    )
+
+
+def do_compact_lzx(candidate: Candidate) -> ItemResult:
+    ok, before, after, note = _compact_lzx(candidate.stats.path)
+    if before == 0:
+        before = candidate.stats.total_bytes
+    return ItemResult(
+        ok=ok, op="compact_lzx", path=str(candidate.stats.path),
+        before_bytes=before, after_bytes=(after or before),
+        note=note, error=None if ok else note,
+        extras={"algorithm": "LZX"},
+    )
+
+
+def do_archive(candidate: Candidate) -> ItemResult:
+    before = candidate.stats.total_bytes
+    try:
+        stub_path, meta = archive_folder(candidate.stats.path)
+    except ArchiveError as exc:
+        return ItemResult(
+            ok=False, op="archive_7z", path=str(candidate.stats.path),
+            before_bytes=before, after_bytes=before,
+            note="archive failed", error=str(exc),
+        )
+    return ItemResult(
+        ok=True, op="archive_7z", path=str(candidate.stats.path),
+        before_bytes=meta.original_bytes, after_bytes=meta.archive_bytes,
+        note="archived",
+        extras={
+            "stub_path": str(stub_path),
+            "original_name": meta.original_name,
+            "sha256_archive": meta.sha256_archive,
+        },
+    )
+
+
+def record_result(journal: Journal, candidate: Candidate, result: ItemResult) -> None:
+    journal.record(Action(
+        ts=time.time(),
+        op=result.op,
+        path=result.path,
+        verdict=candidate.classification.verdict.value,
+        bytes_before=result.before_bytes,
+        bytes_after=result.after_bytes,
+        reversible=True,
+        detail={"note": result.note, **result.extras},
+        outcome="ok" if result.ok else "error",
+        error=result.error,
+    ))