Foreign-order resilience: render orphan Drive IDs and turn them into source discovery

[WilfordGrimley]

Owner-ratified direction, 2026-07-22. Milestone: Federation v1. Priority: polish-tier (behind funnel/consensus work).

The feature in one paragraph

Today the editor renders only what the catalog already knows: an imported order XML whose identifiers come from un-indexed drives shows "card not found" per slot, even though a public Google Drive file ID is a globally unique, self-sufficient image address. This feature makes the editor resilient to foreign orders — any mpc-autofill-lineage XML opens visually intact here — and then closes the loop by treating each orphan ID as a catalog-growth lead: derive the drive it came from and offer it to the source-intake flow. Editor parity for users; discovery funnel for the catalog; a concrete adoption argument for federation ("your orders survive the move").

User stories

1. Import: As a user importing an order built against another instance, I see my actual card images, not placeholders — with the orphans honestly labeled as "from your file, not in our catalog."
2. Discovery: As the same user, when orphans are present I'm offered: "these images come from a drive we don't index — suggest it as a source?" One tap files the lead.
3. Operator: As the catalog operator, suggested drives arrive as structured intake leads (root folder ID, file count, sample names), not free-text requests.

Phase 1 — orphan rendering (frontend only)

• On identifier lookup miss, synthesize a minimal card object: identifier + the slot's XML search query as its stand-in name.
• Image loads direct from Google (lh3/lh4.googleusercontent.com/d/<id>), never through our CDN Worker — the Worker's cache stays catalog-only; we do not become an open proxy for arbitrary IDs.
• Downgrade to the existing "card not found" only when the image fetch itself fails (private/deleted/revoked).
• Orphans get no version picker, tags, or consensus surfaces; visually distinct treatment.
• Votes-off/base-parity safe: no dependency on the vote system (candidate row for docs/upstreaming/extractable-primitives.md at build time).

Phase 2 — source derivation + suggestion

• Backend endpoint: given an orphan file ID, call Drive API files.get?fields=parents with our existing indexer credentials, walk parents to the shared root, files.list to summarize it (count, sample filenames). Indexing metadata only — no pixel storage (governing premise).
• Editor surfaces the one-tap "suggest this drive as a source" flow on orders containing orphans; suggestions land as structured intake leads for owner review.
• Known limit: per-file sharing without folder sharing dead-ends the walk — degrade gracefully to "couldn't identify the drive."
• VERIFY AT PICKUP (Tron): empirically confirm files.get?fields=parents returns parents for anyone-with-link files under our API credential class before building; this claim is from documentation knowledge, not yet tested against our key.

Explicitly out of scope

Authenticated proxying of private drives to general users. Serving is unauthenticated-GET by design; bridging private content through our credentials would republish it via our domain — separate design/security decision if ever wanted. (Users' OWN private files already work client-side via their own OAuth session in the Drive-connect surfaces.)

Acceptance

• A test XML referencing public un-indexed IDs renders images for every reachable slot; revoked ID degrades to not-found; no requests for orphan IDs appear in Worker logs.
• Phase 2: suggestion flow produces a structured lead from a single orphan ID on a folder-shared drive; per-file-shared fixture degrades gracefully.

[WilfordGrimley]

Addition from owner review (2026-07-22):

Resolution tiering is a Phase 1 requirement. Orphan images served direct from Google's image CDN must reproduce the same two-tier discipline our Worker enforces for catalog cards:

• Preview/editor tiles: size-parameterized URL (https://lh3.googleusercontent.com/d/<id>=w<px> — pick the px to match our existing small-thumbnail tier) so browsing an orphan-heavy order doesn't pull megabytes per slot.
• PDF export: original-resolution fetch (=d parameter, or an explicit large =w) — matching the full/quality tier the catalog path uses. Acceptance: an exported PDF containing an orphan embeds the high-res image; the editor grid never requests it.

[WilfordGrimley]

Security review complete; owner ratified all policy calls (2026-07-22). Build conditions now binding:

Per-surface ruling (Phase 1):

Surface	Orphan rendering
Self-import (your own XML)	Allowed
Your own saved decks	Allowed
Shared decks viewed by others	Deny by default → not-found; render only behind an explicit per-deck recipient opt-in ("this deck references N images from a source we don't index — show them?") with provenance labeling
PDF export	Mirrors the deck's ruling; full-res fetch only on explicit export action, never speculative

Mechanical conditions (all Phase 1 surfaces):

• Strict Drive-ID allowlist regex (^[A-Za-z0-9_-]{10,200}$-shaped) validated before URL construction on every entry surface; reject → not-found, never fetch. URL built via URL APIs, size params code-fixed, never from input.
• referrerpolicy="no-referrer" on every orphan image fetch. Accepted residual (owner-ratified): the fetch itself remains a signal to the file's owner on author-only surfaces; this residual is the standing reason cross-user default is deny.
• Stand-in name (XML query text) treated as untrusted: length-capped, control-chars stripped, escaped-text/alt sinks only; verify data-card-* emission is safe with arbitrary names.
• Client-side pacing + per-deck orphan count ceiling; grid uses small tier only, lazy/viewport-gated.
• Orphan→catalog upgrade carries zero orphan-side trust: upgrade happens only via normal indexing; no client cache keyed on orphan ID may poison the catalog fetch.

Phase 2 (parents-walk) gated on an empirical credential test before build: three fixtures (folder-shared public file → parents present; file-only-shared public file → parents empty, graceful dead-end; private/garbage IDs → uniform response shape, no 403-vs-404 oracle). Endpoint requires auth + rate limit + server-side ID validation; if our credential class can read any non-public metadata, this endpoint must use an anonymous-equivalent key. Intake leads: rate-limited, deduped, owner-review-only, metadata-only.

Policy queue (non-blocking): Terms/policy note covering third-party image display + takedown path ships alongside the feature.

[WilfordGrimley]

Owner rulings, 2026-07-22 (second round — orphan states + scope addition):

• Failed orphan renders the existing "Image unavailable" placeholder (the card exists; only its image failed) — supersedes this issue's earlier "downgrade to card-not-found" wording. Blocked / unavailable / not-found remain three visually distinct states.
• Orphan badge text flexes by context ("Your file" on author surfaces, "Shared file" on a recipient's opted-in view); same visual treatment.
• The shared-deck consent is reversible (a "Hide" control after opt-in), remembered per deck.
• Phone provenance line keeps the existing 2-line clamp; no new CSS.

Scope addition — replacement suggestions (Phase 1): an orphan slot retains its XML search query, and offers "find this card in our catalog" — the standard version picker populated by that query; choosing a version swaps the orphan for the catalog card. No new search infrastructure. Individual orphan files are never indexed directly — indexing stays drive-level via the Phase 2 suggest-as-source flow (source model + owner review preserved). Phase 2 may enrich matching with the Drive file's name metadata under the same oracle-safe endpoint conditions.

[WilfordGrimley]

PROMOTED to high priority (owner, 2026-07-23) with fresh symptoms: text-import token 1x Kharn [mpc:1FItgPw7VK_Tbv6dMiqdy5zd-jAoEC9mn] does not register; XML import of an unindexed back face surfaces as Invalid Cards row Back | b:null | 1LrVX0pUcye9n_0RtaDNVl2xPrQgn7CYf (owner screenshot, proxyprints.ca/editor). Implementation dispatched against the ratified Phase-1 design.