The reference database is owned by a separate project and must only be opened with SQLite mode=ro. This repository must not store reference metadata or write local file state to that database.

movie.id is the stable external identity for references to movies in the reference database. The initial implementation requires an explicit --database argument and must not assume a default database location.

File operations must be conservative. Any functionality that renames, moves, or removes files should normally support or require a dry run before applying changes.

scripts/match_filenames.py matches local video files against the external reference database. scripts/diagnose_duration_match.py is a manual diagnostic tool that compares one local file with current and historical durations for a specified movie.id; it is not an automated test.

Both scripts require an explicit --database argument and open the reference database strictly read-only with SQLite mode=ro.