diff --git a/docs/reference-database-read-contract.md b/docs/reference-database-read-contract.md index 7b44a46..879f76d 100644 --- a/docs/reference-database-read-contract.md +++ b/docs/reference-database-read-contract.md @@ -1,17 +1,17 @@ -# Read contract for the WCX reference database +# Producer contract for read access to the WCX reference database ## Purpose and ownership -This document defines the current SQLite read contract used by -`scripts/match_filenames.py` when matching local video filenames against the -WCX reference database. The contract identifies the database objects that the -file-management code depends on and the compatibility boundary that the -reference-data project must preserve. +This document defines the SQLite read contract that this reference-data +project provides to the external file-management repository +`/storage/disk1/WCX-collection`. The contract identifies the database objects +that WCX-collection depends on and the compatibility boundary that this +producer must preserve. -The reference-data project owns the database schema, canonical metadata, -history, and aliases. It is the sole writer to the reference database. -File-management code is a consumer only and must open the database through a -SQLite URI with `mode=ro` and `uri=True`. +This reference-data project owns the database schema and all reference data, +including canonical metadata, history, and aliases. It is the sole writer to +the reference database. WCX-collection is an external read-only consumer and +must open the database through a SQLite URI with `mode=ro` and `uri=True`. Local file paths, local processing state, matching decisions, and collection state are outside this contract and must not be written to the reference @@ -19,8 +19,9 @@ database. ## Connection contract -`scripts/match_filenames.py` resolves the configured database path, converts -it to a file URI, appends `?mode=ro`, and opens it as follows: +The consumer in `/storage/disk1/WCX-collection` resolves the configured +database path, converts it to a file URI, appends `?mode=ro`, and opens it as +follows: ```python database_uri = f"{database_file.resolve().as_uri()}?mode=ro" @@ -42,7 +43,7 @@ The current contract contains exactly three tables and ten selected columns: | `movie_name_alias` | `movie_id`, `alias`, `normalized_alias`, `source` | | `movie_history` | `movie_id`, `duration_seconds`, `archived_at` | -No other table or column is read by `load_movies()`. +No other table or column is read by WCX-collection's current database loader. ### Column meanings for matching @@ -66,7 +67,8 @@ must therefore refer to `movie.id`, never to a name as an identifier. ## SQL queries -The current implementation executes exactly these three queries. +The current WCX-collection implementation executes exactly these three +queries. ### Current movies @@ -138,12 +140,14 @@ historical durations are also compatible with the current query contract. ## Process for contract changes -Before the reference-data project makes an incompatible change: +As producer and schema owner, the reference-data project is responsible for +preserving this contract. Before it makes an incompatible change: 1. Identify the affected table, column, value semantics, or relationship and document the proposed replacement. -2. Update the file-management consumer to support the new contract, preferably - with a transition period in which it can read both forms. +2. Coordinate with WCX-collection and update the consumer to support the new + contract, preferably with a transition period in which it can read both + forms. 3. Create a disposable database containing representative current names, aliases, current durations, and historical durations under the proposed schema. @@ -155,5 +159,6 @@ Before the reference-data project makes an incompatible change: 7. Remove the old contract only after both projects explicitly agree that no active consumer depends on it. -The projects must coordinate any incompatible change; the reference-data -project must not silently break or reinterpret the documented read contract. +The reference-data project must not deploy an incompatible schema or semantic +change until a compatible WCX-collection version is available. It must not +silently break or reinterpret the documented read contract.