Open questions & decisions

This is the anti-hallucination surface. If a question here isn’t answered, a build agent should ask the operator rather than pick an answer. Items are grouped by area and link back to the feature they affect.

Watermark policy

• No-referrer policy sign-off. The routing decision is made — no-referrer traffic gets the clean image (see Decisions below) — but a written policy sign-off document is required before the first purge runs. Who signs it, and where does it live? → Freemium watermarking
• Worker-cohort removal for flipped hosts. Every flip host is also in the Worker’s referrer cohort, so the Worker watermarks non-hot ids on miss and re-pins wm — a purge does not stick unless cohort removal ships in the same release, and disabling the Snippet alone never restores clean (rollback is dual-lane: Snippet off + cohort backoff + purge). What is the exact removal step per flipped host?
• Pricing-funnel wiring. A watermark only converts if it points the viewer to /pricing. This is the binding constraint on converting watermarked hosts — what’s the exact funnel and CTA?
• Cohort graduation rules. Volume/persistence/confidence thresholds for auto-graduating a non-domain signal into the watermark cohort; which signals are always excluded (browsers, generic runtimes, crawlers, shared social/ search referrers).
• Whale conversion vs. cost-control. Which high-volume hosts have operator-visible watermarks (conversion targets) vs. embedded/app-only players where the mark is unseen (cost-control only)? Requires a manual render audit per host before adding. Specifically: operator-visibility is unverified for H08 (the highest-volume flip host, deliberately last and alone in the rollout) and for the tail batch (H10–H14) — those flips are gated on this verification.

Billing & entitlements

• C02 entitlements (flip-program blocker). C02 is a paying customer whose domain and IP entitlement lists are both empty — zero bypass paths, so the flip program would watermark a paying customer. This must be resolved (fill the entitlements) or explicitly waived before any flip wave ships; the whole rollout is blocked on it. → Paid access
• Projection freshness vs. cost. Raise KV cache TTL 60s → 300s? Is 5-minute propagation acceptable for normal entitlement changes, and does any support flow need a sub-minute revoke path? → Paid access
• Self-serve onboarding. What is the end-to-end “subscribe → list domains → clean in minutes” flow, and what’s the first-wave quickstart?
• Pricing tiers. The free threshold (50k/month) is defined; paid price points and tier structure are not committed here.
• Snippet allow-list sync. The Snippet’s PAYING_DOMAINS/PAYING_IPS are hand-maintained and separate from the Worker’s KV projection — should they be generated from the same source? → Edge watermark router

Delivery & API

• Output formats. Expose animated (.gif/.webp) and still WebP/AVIF through the same path shape, or a query flag? → Thumbnail URL API
• Published size vocabulary. Commit to a documented per-provider _size token list, or keep it provider-derived?
• Playlist mapping growth. Keep the hardcoded playlist→video map, or back it with a resolver cache? → Redirects

Cost & reliability

• Purge tooling before any purge. The current purge tool is single-URL and uncapped. Before the first trickle purge, three things must exist: a batch purge wrapper with per-wave URL caps (50/25/15/5 by volume tier, 20–30 URLs/min), a fail-closed pre-wave cost gate (refuses to run when cache-busting-URL data is missing), and invocations/KV polling to watch worker cost during a wave. Cloudflare has no hard spend cap — alerts only, with ~24 h lag — so every real brake is self-built. → Cache purge API
• Hot-set size vs. coverage. How far to grow the Snippet hot set before the 32 KB bundle ceiling bites; whether to automate a daily hot-set regenerate.
• Hot-set refresh automation for rotating catalogs. Hosts with rotating catalogs (e.g. H03) decay toward ~0% hot coverage in roughly 8 weeks, which erodes deterministic delivery (not coverage — misses fall back to the Worker). Deterministic delivery on those hosts needs automated hot-set refresh; cadence and trigger are undecided.
• Cache-Control: no-store on the watermark 307. The redirect response must carry no-store before flipping any host above ~1M requests/month, so flip decisions stay revocable at the edge. Not yet shipped.
• Miss-path optimization target. After enough P1 attribution samples: fix cache-key fragmentation, remove redundant wm → clean recursion, or reorder negative-cache reads? → Caching & delivery
• Workers Cache adoption. Cloudflare’s new pre-Worker Workers Cache ("cache": { "enabled": true }) offers free request collapsing + SWR, but serves before the Worker runs and keys on URL, not referrer — so it can’t front the clean/watermark variant path yet. Where and when do we adopt it?
  • Direction (2026-07-07): not globally now (it recreates the referrer-blind cache lottery). Pilot on fixed-variant surfaces (shared fallback graphics, a test route); adopt on the image path only after the Snippet encodes the variant in the URL, then let it replace the hand-rolled caches.default layer. The cost estimate is now written: not a cost play — ~$1–$12/mo saved (central ~$5), ceiling ~$13/mo, and negative if enabled naively; adopt for request-collapsing/latency, not savings, and ship the entitlement cacheTtl 60→300s tuning for the cheap KV win. See Workers Cache research, the savings estimate, and Caching & delivery.
• Animated rollout gate. Demand + cost estimate needed before turning animated thumbnails on broadly. → Animated thumbnails

Tools & integrations

• Cache purge contract. Path vs. endpoint vs. account API; API-key only or dashboard too; per-customer rate budget. → Cache purge API
• Shopify launch. Whether/when to push the app through review; how Shopify Billing maps to clean-image entitlement; production hosting/session storage. → Shopify app
• Outreach send-lane automation. How much of the send step to automate vs. keep human-in-the-loop. → Outreach toolkit
• Runbooks audit before public listing. The internal runbooks are published unlisted at /runbooks/; each one needs a scrub audit (no real host, customer, or billing identities) before being linked from public navigation.

Decisions already made (do not relitigate)

• Entitlements run in runtime mode (KV projection preferred, customers.json fallback) — not static.
• The Snippet redirect is the deterministic watermark control point (2026-06-14). Watermark delivery = a 307 redirect to a distinct wm.jpg key; the bare URL always stays clean. Flipping a host = adding it to WM_DOMAINS plus its current ids to the hot set. This supersedes relying on the referrer-blind page-rule cache, where a live re-probe showed delivery had flipped wm-dominant (110/126 uncontaminated reads) and a reverse leak was serving wm to no-referrer/direct users. → Edge watermark router
• No-referrer traffic gets the clean image (2026-06-14). No-referrer volume is dominated by datacenter renderers (DC1/DC2) and SDK defaults that strip referrers; real browsers are a minority. Watermarking it would punish exactly the developer-friendly path. The written policy sign-off is still open above.
• Dev/local traffic gets the clean image, detected by referrer host (2026-06-14). localhost, 127.0.0.1, [::1], *.local, *.test, RFC-1918 hosts, and tunnel domains route clean via an explicit isDevCleanReferrer early return — never user-agent sniffing. The implementation is Planned, not built.
• Edge redirects consolidate in the Snippet — the standalone Cloudflare dynamic-redirect deployer is retired (2026-05-26).
• Watermark transforms fail open to the clean image — never throw.
• Borås loop rule is intentionally narrow (id + UA + self-referrer + ASN 14061) — a path-only rule is too broad.
• No Cloudflare spend ≥ $1/month without a written estimate in docs/.