urban/WCX
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update reference database contract for project split

Browse Source
This commit is contained in:
Urban
2026-07-19 18:25:57 +02:00
parent 19af3c8cc2
commit 717750a36b
1 changed files with 24 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/reference-database-read-contract.md
View File

@ -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.