First-touch source hydration

Request boundary

Only an explicitly opened film/person page or chosen GoodTakes review title requests POST /goodtakes/api/hydration with one canonical subject. Search lists, cast cards, graph nodes, recommendations and avatars never request jobs. Opening a cast link lands on the Knomee subject page, which requests that person alone.

Queue and limits

The existing M4 server owns a durable, deduplicated queue in the ignored runtime worker directory. Registered Knomee, GoodTakes Firebase and M4 origins can request jobs. Requests accept no URLs, keys, operations or arbitrary shell arguments. The global cap is20 new subjects per UTC day and20 queued/running jobs; a single nice19 worker processes one subject at a time, with a ten-minute process deadline. Origin checks reduce accidental cross-site requests; they are not authentication. The global cap bounds abuse of this public metadata service. There is no paid API.

Identity and source selection

hydrate-one verifies the exact IMDb/Wikidata binding from the current hash-verified document, existing mapping, or a unique P345 lookup. It fetches only that Wikidata entity. Producer5 additionally reads up to200 directly credited entities in batches of50 to build a film graph. It never follows their relations, hydrates their profiles, downloads their portraits or mints their identities. Fields and links are additive; existing fields, portraits, addresses, reviews and immutable older records remain. FamilySearch is linked only from a single valid, non-deprecated P2889 value, never name-matched. Wikipedia representative images precede Wikidata P18. Each candidate tries its thumbnail then original file before moving to another exact-identity candidate. Only source-provided HTTPS Wikimedia upload/thumbnail routes qualify; technical HTTP, timeout or invalid-image failures are retained and try the next route. Pinning, hash and pointer failures remain fail-closed, never download retries. Owner direction on2026-10-03 separates licensing review from download availability: retain source licence/credit/revision; do not reject a candidate solely for its licence. Unresolved/non-reusable rights remain explicitly marked as pending review, never relabeled reusable or provider-authorized. No source image means placeholder; technical source exhaustion means inspection-required, not false ready.

Publication and integrity

Source bytes, images, licence records and metadata are archived immutably in the internal runtime worker's build/archive/ and pinned through the existing local Kubo daemon RPC. The daemon owns its external-volume block store; background Java does not open removable-volume files or initialize another IPFS repository. Exact pinned readback precedes public-origin readback and the registered oracle's off-chain metadata pointer update. Dynamic hash-named bytes serve from an additive /oracle/ overlay, not by rewriting a frozen release or rebuilding Firebase for every subject. Both clients read the same resolved pointer and verify its hash before rendering. This service never calls review, contract admission, fact attestation, reward or spending endpoints.

Client recovery

Clients check status up to66 times at ten-second intervals, including background tabs, covering the worker's ten-minute deadline. Returning to the tab refreshes status. Ready cancels an older in-flight detail lookup before refreshing the subject, so its stale pointer cannot win the publication race. Failures preserve existing details. Concurrent mounts share an in-flight admission request. Polling within that visit only reads status after admission; a later explicit visit can request the server's version-aware upgrade again. Failed reads have a small retry control. Neither retry nor revisiting bypasses the server's uncertain-job fence or republishes a signed authorization. Producer version2 distinguishes image-ready from no source image and accepts Commons' exact HTTPS upload and thumbnail hosts. On the next explicit open, an earlier successfully completed version1 job is checked once for its missing image; its completion and log are retained. Uncertain jobs never replay. Existing verified fields and portraits are not replaced. Portrait authorization is retained before its pointer write, with uncertain publication fenced.

Producer version3 also resolves a film article's exact representative image from Wikipedia's local file repository. Commons-only lookup misses locally hosted posters. The article and file revisions, original licence and source binding are retained. Producer version4 prefers the article's valid image response and retains Commons and Wikidata candidates, including disagreements, with source/file revisions and original licence labels. Disagreement does not block publication. Each candidate keeps its own source binding. Selected bytes still require safe Wikimedia URLs, valid image bytes, exact pin readback and metadata hashes. Existing images remain. A completed older job without an image gets one new check on the next explicit visit, retaining its prior completion and versioned log. Uncertain jobs never replay. Ready invalidates both title detail and live catalog caches so verified images can reach cards. Title and review pages read the exact opened subject's hash-verified metadata even when an image job fails. Ready and uncertain terminal states refresh that read. They share queued/running/verification/ready/inspection/limit feedback; verification failures preserve the saved title and local review text. A refreshed metadata pointer never inherits a content CID from the previous document. Earlier source records and saved projections remain intact. Queued jobs survive service restart; interrupted running jobs become uncertain and never resume automatically. The producer records its exact authorization before publication. A retained authorization whose pointer does not match requires manual inspection, never a blind resend. Logs and authorizations are private runtime files.

Metadata hydration version2 retains the short Wikidata synopsis and adds a Wikipedia lead summary with article revision, attribution, licence and pinned source response. Its new authorization is versioned; earlier attempts remain intact and must match the live pointer or a verified subsequent portrait revision before preparation. Film pages offer source image alternatives, another HTTPS image URL and editable factual correction/evidence text. A browser-local fragment carries the text to the current native composer, which previews it and requires an explicit import. Existing draft text is never overwritten automatically. QUALIA assertions/denials use the existing approval, capacity and submission flow. VITA stays separate. Publication does not automatically replace a listing or establish that source-selected details are settled facts. Images are linked, not uploaded or fetched from arbitrary hosts.

For an inspected uncertain film whose metadata pointer already matches its retained authorization, pause the producer and run tools/reconcile-published-hydration.main.kts --subject film:ttNNNNNNN from the runtime directory. It preserves the failed job/log, verifies identity and content hashes, creates only a new reconciled revision, and marks the same job ready only after live readback. It never resends an old signed payload. Restart the service after removing the pause marker to reload the status.

First-visit connections (producer5)

The earlier graph publisher requires minted profiles for every node. First-touch uses exact source identifiers and revision-bound source records instead. Each node links to its exact Knomee subject and offers a separate source link; a profile link does not imply mint provenance. No name matching or recursive enrichment. Cast, director, creator, writer, producer and production-organization edges retain the film's Wikidata revision and property. Deprecated claims are excluded. Related source responses and graph bytes are archived and pinned, and the public graph must read back exactly before a new film metadata pointer is authorized.

Completed film jobs from earlier producers get one upgrade on the next explicit visit, retaining the old job and log even when their poster is already ready. Metadata version3 and a separate v3 authorization retain earlier signed attempts. Existing graphs and details remain; uncertain jobs still require inspection and never automatically replay. Empty source relations produce a root-only graph; oversized or failed source reads require inspection rather than silent truncation. The existing daily/queue caps, deadline and ready-triggered detail refresh apply. Unit tests remain deferred under machine RAPID POC; the repository's generic test minimum is recorded for the next explicitly scoped unit-test pass.

Installation and rollback

Owner approval to install the existing registered film-oracle credential is required. From a clean pushed checkout:

kotlin tools/install-first-touch.main.kts --host SSH_ALIAS --root /absolute/existing/repository --key-target /absolute/user/.config/knomee/film-oracle.env

The installer refuses a different signer, never overwrites an existing key, checks the frozen wire vector, installs the worker and retains a prior server script before restarting the existing nice19 LaunchAgent. No Funnel/DNS change is made. Rollback restores that prior script and restarts the same LaunchAgent. Keep the queue, dynamic immutable overlay, archive and pinned blocks; do not delete published source history.

Read-only planning:

kotlin tools/film-oracle/film-minter.main.kts hydrate-one --subject person:nm0866055 --plan

An uncertain job requires inspecting resolveSubject, the staged exact metadata, retained authorization and private log. Reconcile the existing pointer first. No automatic requeue, signed resend or enrichment of unrelated cast members is allowed.

For a proven pre-publication storage stall only, pause the producer with the runtime build/PAUSED marker, restart the service, then run the operator-only tools/reconcile-first-touch.main.kts from its runtime directory. It refuses any retained signed authorization, stops only exact subject/script processes, checks authorization absence again and retains the failure before returning the same job to queued. Removing the pause marker and restarting resumes that queue. Never use this helper for a signed or uncertain publication.