# Technical review: video-library-manager

## Metadata

| Field | Value |
|--------|--------|
| Repository path | `dl-organizer` (package `vlm`) |
| Verification date (UTC) | 2026-04-07 |
| Git revision verified | `working tree (post-refactor)` |
| Test run | `pytest -q` → **507 passed** |

## Scope

- Source: `src/vlm/**/*.py`, `tests/`
- Config: `pyproject.toml`
- Assumption: single-user local library; artifacts semi-trusted; no formal threat model in repo.

## Executive summary

The planned hardening work is complete and the suite is green. The earlier review findings around unsafe move/rename sources, silent duplicate fallback, exact-string duplicate joins, quarantine run aborts, ambiguous `find` partial-success handling, and dict-typed plan loading are all addressed in the current codebase. The remaining observation is low-priority packaging overlap: `textual` is still declared in both the `dev` and `tui` optional extras, even though the runtime optional-boundary bug is fixed.

Weighted score (0–10): **9.0**.

## Score rubric

| Criterion | Score | Notes |
|-----------|-------|--------|
| Module boundaries / pipeline | 8.8 | Commands → domain modules remain explicit and well-separated. |
| Execution safety (filesystem) | 9.0 | Source and destination root checks are enforced for move/rename execution (`src/vlm/executor.py:204-249`). |
| Planning / duplicate logic | 9.0 | Duplicate resolution now fails explicitly on bad inputs and canonicalizes path matching (`src/vlm/duplicate_resolve.py:16-58`, `src/vlm/planner.py:42-57`, `src/vlm/planner.py:151-203`). |
| Data I/O & validation | 9.0 | Validated plan JSON now flows through a typed construction boundary (`src/vlm/io.py:247-326`). |
| Error handling consistency | 9.0 | Unsupported quarantine categories return failed results; execute loop contains per-operation exceptions (`src/vlm/quarantine.py:116-140`, `src/vlm/executor.py:108-130`). |
| Test signal | 9.2 | Full suite is green and regression coverage targets the hardened edges. |
| Dependencies | 8.5 | Runtime dependency posture is lean, but `textual` remains duplicated across optional extras (`pyproject.toml:12-20`). |

## Resolved findings

### F1 [Resolved] Move/rename source now constrained to `library_root`

**Evidence:** `src/vlm/executor.py:204-249`, `tests/test_path_safety.py:76-137`.

Execution now rejects crafted or hand-edited plans whose move/rename source or destination escapes the configured library root.

---

### F2 [Resolved] `by_quality` no longer silently falls back to first item

**Evidence:** `src/vlm/duplicate_resolve.py:44-58`, `src/vlm/planner.py:187-203`, `tests/test_duplicate_resolve.py:223-230`, `tests/test_planner.py:619-669`.

Missing or misaligned quality data now raises an explicit resolver error, and planning converts the group into manual review instead of quietly selecting index `0`.

---

### F3 [Resolved] Duplicate group ↔ identities join no longer depends on exact string equality

**Evidence:** `src/vlm/planner.py:42-57`, `src/vlm/planner.py:152-169`, `tests/test_planner.py:672-720`.

Canonical path keys are used consistently for duplicate-group matching and quality-comparison lookup.

---

### F4 [Resolved] Quarantine failures no longer abort the whole execute pass

**Evidence:** `src/vlm/quarantine.py:116-140`, `src/vlm/executor.py:108-130`, `tests/test_quarantine.py:84-110`, `tests/test_executor.py:951-1004`.

Unsupported quarantine categories now produce failed `OperationResult`s, and the execute loop continues after unexpected per-operation failures.

---

### F5 [Resolved] `find` non-zero exit behavior is now explicit

**Evidence:** `src/vlm/scanner.py:158-214`, `tests/test_scanner.py:140-186`.

Partial stdout is retained with an explicit warning; a non-zero exit with no stdout yields an empty deterministic result.

---

### F6 [Low] Optional dependency overlap remains

**Evidence:** `pyproject.toml:12-20`.

`textual` is still listed in both `dev` and `tui`. This is now a packaging/documentation concern only; the runtime issue was removed by the guarded import strategy in `src/vlm/review_tui.py:16-30` and lazy CLI import in `src/vlm/cli.py:567-602`.

---

### F7 [Resolved] Validated JSON no longer remains dict-typed at the hot execution boundary

**Evidence:** `src/vlm/io.py:247-326`, `tests/test_io.py:112-203`.

Plan loading now validates schema shape and immediately constructs an `ExecutionPlan` object.

---

### F8 [Resolved] Unknown duplicate strategy no longer defaults to first item

**Evidence:** `src/vlm/duplicate_resolve.py:54-58`, `tests/test_duplicate_resolve.py:233-237`.

Unexpected strategy strings now fail explicitly via `DuplicateResolutionError`.

## Verified strengths

| Claim | Evidence |
|--------|----------|
| Optional TUI boundary is runtime-safe | `src/vlm/cli.py:567-602`, `src/vlm/review_tui.py:16-30`, `tests/test_cli_review_plan.py:237-343` |
| Path component sanitization and planner root checks remain in place | `src/vlm/planner.py:42-57`, `src/vlm/planner.py:151-203` |
| Quarantine manifest two-phase flow remains intact | `src/vlm/quarantine.py:221-320` |
| JSON artifact validation still exists and now feeds a typed plan path | `src/vlm/io.py:165-326` |
| Parallel ffprobe behavior remains available when metadata extraction is enabled | `src/vlm/scanner.py:85-101` |

## Priority order

1. Optional-extra cleanup (`pyproject.toml:12-20`) if packaging clarity is important.
2. Otherwise, current review items are complete and the main focus can shift to new feature work.

## Verification log (current codebase)

| Statement in this doc | Checked against |
|------------------------|-----------------|
| TUI runtime boundary | `src/vlm/cli.py:567-602`, `src/vlm/review_tui.py:16-30`, `tests/test_cli_review_plan.py:237-343` |
| Move/rename source + destination checks | `src/vlm/executor.py:204-249`, `tests/test_path_safety.py:76-137` |
| Quarantine failure contract + execute containment | `src/vlm/quarantine.py:116-140`, `src/vlm/executor.py:108-130`, `tests/test_executor.py:951-1004` |
| Duplicate resolver fail-fast behavior | `src/vlm/duplicate_resolve.py:16-58`, `tests/test_duplicate_resolve.py:223-237` |
| Duplicate path normalization | `src/vlm/planner.py:42-57`, `src/vlm/planner.py:152-169`, `tests/test_planner.py:672-720` |
| Scanner partial-result contract | `src/vlm/scanner.py:158-214`, `tests/test_scanner.py:140-186` |
| Typed plan I/O boundary | `src/vlm/io.py:247-326`, `tests/test_io.py:112-203` |
| Full-suite baseline | `pytest -q` on 2026-04-07 → **507 passed** |

This document reflects the current post-refactor state rather than the pre-refactor defect list.