# Film graph and media contracts

## Sources and identities

`tools/film-oracle/film-knowledge.main.kts` retrieves film credits from Wikidata properties `P57`,
`P170`, `P58`, `P162`, `P161`, and `P272`. It records the source entity, property, entity revision,
retrieval time, source URL, and target external identifiers on every edge.

The importer uses `film:tt...`, `person:nm...` when Wikidata supplies an IMDb person identifier,
`person:wd-Q...` otherwise, and `organization:wd-Q...`. The tracked
`tools/film-oracle/identity-aliases.json` preserves the first canonical choice and rejects collisions.

The supported entry point is the resumable GoodTakes hydration runner:

```text
npm run hydrate:plan
npm run hydrate:catalog -- --only tt7366338
```

## Durable publication

The runner checkpoints each completed phase under `.goodtakes/hydration/`. It invokes the lower-level
Kotlin tools in the required order and is safe to rerun. Canonical metadata, graphs, source images,
rights records, and normalized source imports must first pass through M4. The M4-side process runs at
nice level 19, archives the exact bytes on PROMETHEUS, pins them with CIDv1, reads them back with
`ipfs cat`, and verifies the archive and IPFS SHA-256 values against the local bytes. Publication
fails closed on any mismatch. GoodTakes records the result under `public/oracle/cid-receipts/`.

Files under `public/oracle/` and the Firebase/M4 static releases are web and CDN recovery mirrors.
M4 PROMETHEUS plus the verified CID receipt is the storage authority. `public/data/` remains the
release projection consumed by the product.

`publish` fails unless every referenced identity resolves, its profile URL serves, and its profile
bytes match the URL content hash. The graph is canonical compact JSON, pinned with CIDv1 on the M4
node, and referenced by the next film metadata revision. Semantic graph cycles are allowed;
publication ancestry remains separate.

## Media rights

`media-asset/v1` admits only `REUSABLE_LICENSE`, `PROVIDER_AUTHORIZED`, or `NON_FREE_EDITORIAL`.
Provider media requires a provider and terms URL. Non-free editorial media requires copyright
status, an item-specific rationale, and intended title-page context. Fair use is a recorded
case-specific rationale, never a license promotion. The `servable` field is operator-controlled.
Unserving or unpinning does not guarantee deletion from other IPFS peers.

The TMDB lane is optional and must remain disabled without configured credentials. If enabled, the
product Credits surface must carry the current required notice and logo before deployment.

## Ownership

Knomee owns the generic producer authorization and identity-resolution APIs. GoodTakes owns all film
source selection, hydration policy, seeds, graph semantics, media rights records, and acceptance.