From e44ac0ae0c54c37c97b2117a8f48ad9d9bfae168 Mon Sep 17 00:00:00 2001
From: Anthony Ettinger <anthony@profullstack.com>
Date: Thu, 24 Sep 2026 12:11:55 +0000
Subject: [PATCH] Register the five-second streaming pre-roll format (work
 package A)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Schema and format registration for Crawlproof video pre-roll ads. No
rendering, selection or serving — those are packages B and D. The exit
condition this carries is the narrow one from the spec: existing formats
still work, and an unrendered video cannot serve.

Registering a media format in AD_FORMATS is not enough on its own, and is
actively unsafe: creativesFromCopy() fanned out over the whole registry
into one common design object, so the format would have minted a
video_preroll_5s creative carrying a headline and a palette, marked ready
beside its siblings, and handed an HTML renderer something it would draw
as a banner. So the fan-out is now DESIGN_FORMAT_IDS — the complement of
the new STREAMING_FORMAT_IDS — and the dashboard preview strips and format
editors iterate DESIGN_FORMATS for the same reason. They skip formats with
no creative row today, which hides the problem only until the render
pipeline lands.

Three places now refuse video rather than relying on configuration:

  * fitAdFormat(), the single gate in front of serveAd(), refuses any
    streaming format outright — so the refusal holds even for a slot that
    has somehow been given one.
  * cleanCreative()'s allowlist is the design formats, so a crafted
    updateCreatives payload cannot write a medialess video creative. The
    DB would have refused the write anyway; this makes it a clean
    rejection rather than a constraint violation.
  * ad_creatives.published_revision is null until ffprobe has validated an
    encode, so a video creative is unservable by construction rather than
    by remembering to check.

The migration deliberately breaks from the terminal_ascii and feed_item
precedents: it widens the creative CHECK but adds nothing to slot
inventory and backfills no creatives. A backfill can clone a headline; it
cannot clone a 150-frame H.264 encode.

Adds ad_video_jobs, ad_video_assets, ad_streaming_properties,
ad_video_decisions and ad_video_events. The decision table's unique
(property, session, placement) key is the whole per-session pre-roll rule:
a reconnect, a playlist reload or a retry returns the row that exists
instead of stacking a second ad.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../dashboard/ads/[id]/edit/edit-form.tsx     |   4 +-
 app/(app)/dashboard/ads/new/form.tsx          |   6 +-
 app/(marketing)/ads/page.tsx                  |   3 +-
 app/actions/ads.ts                            |  11 +-
 lib/ads/creative.ts                           |  21 +-
 lib/ads/formats.ts                            |  70 ++++-
 .../20260924130000_ad_video_preroll.sql       | 291 ++++++++++++++++++
 tests/ads-template-copy.test.ts               |   8 +-
 tests/ads-video-format.test.ts                | 124 ++++++++
 9 files changed, 524 insertions(+), 14 deletions(-)
 create mode 100644 supabase/migrations/20260924130000_ad_video_preroll.sql
 create mode 100644 tests/ads-video-format.test.ts

diff --git a/app/(app)/dashboard/ads/[id]/edit/edit-form.tsx b/app/(app)/dashboard/ads/[id]/edit/edit-form.tsx
index da3c66b..272852b 100644
--- a/app/(app)/dashboard/ads/[id]/edit/edit-form.tsx
+++ b/app/(app)/dashboard/ads/[id]/edit/edit-form.tsx
@@ -3,7 +3,7 @@
 import { useState, useTransition } from "react";
 import { useRouter } from "next/navigation";
 import { updateCampaign, updateCreatives, uploadAdAsset } from "@/app/actions/ads";
-import { AD_FORMATS, paletteFor, type AdCreative, type AdFormatId } from "@/lib/ads/formats";
+import { DESIGN_FORMATS, paletteFor, type AdCreative, type AdFormatId } from "@/lib/ads/formats";
 import { AdPreview } from "@/components/ads/ad-preview";
 import { ColorField } from "@/components/ads/color-field";
 import type { AdTheme } from "@/lib/ads/theme";
@@ -185,7 +185,7 @@ export function EditCampaignForm({
       {current && (
         <div className="card space-y-4 p-5">
           <div className="flex flex-wrap items-start gap-4">
-            {AD_FORMATS.map((f) => {
+            {DESIGN_FORMATS.map((f) => {
               const c = creatives.find((x) => x.format === f.id);
               if (!c) return null;
               return (
diff --git a/app/(app)/dashboard/ads/new/form.tsx b/app/(app)/dashboard/ads/new/form.tsx
index 128b202..848424c 100644
--- a/app/(app)/dashboard/ads/new/form.tsx
+++ b/app/(app)/dashboard/ads/new/form.tsx
@@ -3,7 +3,7 @@
 import { useState, useTransition, useRef } from "react";
 import { useRouter } from "next/navigation";
 import { previewAds, saveCampaign, uploadAdAsset } from "@/app/actions/ads";
-import { AD_FORMATS, paletteFor, type AdCreative, type AdFormatId } from "@/lib/ads/formats";
+import { DESIGN_FORMATS, paletteFor, type AdCreative, type AdFormatId } from "@/lib/ads/formats";
 import type { SiteBrand } from "@/lib/ads/brand";
 import { AdPreview } from "@/components/ads/ad-preview";
 import { ColorField } from "@/components/ads/color-field";
@@ -215,7 +215,7 @@ export function NewAdForm() {
               )}
             </div>
             <div className="flex flex-wrap items-start gap-6">
-              {AD_FORMATS.map((f) => {
+              {DESIGN_FORMATS.map((f) => {
                 const c = creatives.find((x) => x.format === f.id);
                 if (!c) return null;
                 return (
@@ -242,7 +242,7 @@ export function NewAdForm() {
           {/* Editor for the active format */}
           <div className="card space-y-4 p-5">
             <h2 className="font-semibold">
-              Edit — {AD_FORMATS.find((f) => f.id === active)?.label}
+              Edit — {DESIGN_FORMATS.find((f) => f.id === active)?.label}
             </h2>
             <div className="grid gap-4 sm:grid-cols-2">
               <label className="block">
diff --git a/app/(marketing)/ads/page.tsx b/app/(marketing)/ads/page.tsx
index e71b882..829a76a 100644
--- a/app/(marketing)/ads/page.tsx
+++ b/app/(marketing)/ads/page.tsx
@@ -11,6 +11,7 @@ import {
 } from "@/lib/ads/pricing";
 import {
   AD_FORMATS,
+  DESIGN_FORMATS,
   PUBLISHER_FORMAT_IDS,
   TERMINAL_FORMAT_ID,
   TERMINAL_COLS_LABEL,
@@ -102,7 +103,7 @@ export default async function AdsMarketingPage() {
           />
           <Card
             title="Every size at once"
-            body={`${AD_FORMATS.length} formats from one campaign: the standard display sizes, a borderless text link that reads as part of the page, an ASCII unit for terminals, and a syndication item for RSS and Atom feeds.`}
+            body={`${DESIGN_FORMATS.length} formats from one campaign: the standard display sizes, a borderless text link that reads as part of the page, an ASCII unit for terminals, and a syndication item for RSS and Atom feeds.`}
           />
           <Card
             title="A budget that actually stops"
diff --git a/app/actions/ads.ts b/app/actions/ads.ts
index f08e9d0..f70d0d9 100644
--- a/app/actions/ads.ts
+++ b/app/actions/ads.ts
@@ -7,7 +7,7 @@ import { isAllowedTargetUrl } from "@/lib/rateLimit";
 import { getOrCreateDefaultOrg } from "@/lib/orgs";
 import {
   generateAdCreatives,
-  AD_FORMAT_IDS,
+  DESIGN_FORMAT_IDS,
   cleanSummary,
   summaryDomain,
   type AdCreative,
@@ -115,7 +115,14 @@ export async function previewAds(input: { url: string }): Promise<
   }
 }
 
-const ALLOWED_FORMATS = new Set<AdFormatId>(AD_FORMAT_IDS);
+// Design formats only. cleanCreative() below produces a design object —
+// headline, body, palette — from a client payload, and the streaming pre-roll
+// has no design object: its creative is media a worker encodes. Allowing it
+// here would let a crafted payload mint a video creative with a headline and no
+// bytes behind it, which is the one row selection must never be able to find.
+// The DB's ad_creatives_revision_check would refuse the write anyway; refusing
+// it here makes that a clean rejection rather than a constraint violation.
+const ALLOWED_FORMATS = new Set<AdFormatId>(DESIGN_FORMAT_IDS);
 // 6- or 8-digit: the editor's opacity slider writes #rrggbbaa.
 const HEX = /^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 
diff --git a/lib/ads/creative.ts b/lib/ads/creative.ts
index 795475a..a26bdc3 100644
--- a/lib/ads/creative.ts
+++ b/lib/ads/creative.ts
@@ -15,6 +15,10 @@ export { summaryParagraphs } from "./feeditem";
 import {
   AD_FORMATS,
   AD_FORMAT_IDS,
+  DESIGN_FORMAT_IDS,
+  STREAMING_FORMAT_IDS,
+  VIDEO_FORMAT_ID,
+  isStreamingFormat,
   brandInitial,
   formatSpec,
   hexToRgba,
@@ -41,7 +45,16 @@ import {
 
 // Re-export the client-safe format primitives so existing server importers of
 // this module keep working; client components should import from ./formats.
-export { AD_FORMATS, AD_FORMAT_IDS, formatSpec, paletteFor };
+export {
+  AD_FORMATS,
+  AD_FORMAT_IDS,
+  DESIGN_FORMAT_IDS,
+  STREAMING_FORMAT_IDS,
+  VIDEO_FORMAT_ID,
+  isStreamingFormat,
+  formatSpec,
+  paletteFor,
+};
 export { renderCreativeText, renderTerminalHtml };
 export type { AdCreative, AdFormatId };
 
@@ -263,7 +276,11 @@ function copyToCreatives(brand: SiteBrand, copy: AdCopy, heroUrl: string | null)
     body: copy.body,
     ctaText: copy.ctaText || "Learn more",
   };
-  return AD_FORMAT_IDS.map((format) => ({
+  // DESIGN_FORMAT_IDS, not AD_FORMAT_IDS: the streaming pre-roll is media the
+  // video worker encodes, not a design object an HTML renderer can take. See
+  // the constant's comment in ./formats for why fanning out over the whole
+  // registry is the bug this avoids.
+  return DESIGN_FORMAT_IDS.map((format) => ({
     format,
     // tiny banner uses the short headline; others use the full one
     headline: format === "banner_320x50" ? copy.shortHeadline || copy.headline : copy.headline,
diff --git a/lib/ads/formats.ts b/lib/ads/formats.ts
index ab4fc31..9f48da7 100644
--- a/lib/ads/formats.ts
+++ b/lib/ads/formats.ts
@@ -72,11 +72,68 @@ export const AD_FORMATS = [
   // pixel box: w/h is only the nominal size the web preview uses when the same
   // creative is rendered as HTML. The real dimension is "one item".
   { id: "feed_item", label: "Feed (RSS/Atom/JSON)", w: 600, h: 120 },
+  // Five-second streaming pre-roll. The only format whose creative is *media*
+  // rather than markup: w/h is the real 16:9 master frame, not a preview size.
+  //
+  // It is deliberately unlike every format above it. The others are generated
+  // synchronously as a design object and rendered to HTML or text at serve
+  // time; this one has to be rendered to an MP4 by a background worker before
+  // it can be shown to anybody, which is why it carries a published media
+  // revision (see ad_video_assets) and why an unrendered one must never reach
+  // a viewer. Keep it out of every list that feeds an HTML or text renderer —
+  // DESIGN_FORMAT_IDS below is the list those call sites want.
+  { id: "video_preroll_5s", label: "Streaming Pre-roll (5s)", w: 1920, h: 1080 },
 ] as const;
 
 export type AdFormatId = (typeof AD_FORMATS)[number]["id"];
 export const AD_FORMAT_IDS = AD_FORMATS.map((f) => f.id) as AdFormatId[];
 
+// The streaming pre-roll id. Named for the same reason TERMINAL_FORMAT_ID and
+// FEED_FORMAT_ID are: several call sites have to branch on it, and this module
+// stays the one place a format id is spelled out.
+export const VIDEO_FORMAT_ID = "video_preroll_5s" as const;
+
+/**
+ * Formats delivered as media the viewer plays, not as a document a renderer
+ * produces.
+ *
+ * Everything outside this list shares one pipeline: copy in, a common design
+ * object out, HTML or ASCII at serve time. A streaming format shares none of
+ * it — there is nothing to render into an iframe, a <pre>, or a feed item, and
+ * the bytes only exist once a worker has encoded them.
+ */
+export const STREAMING_FORMAT_IDS: AdFormatId[] = [VIDEO_FORMAT_ID];
+
+export function isStreamingFormat(id: string | null | undefined): boolean {
+  return !!id && (STREAMING_FORMAT_IDS as string[]).includes(id);
+}
+
+/**
+ * The formats the copy generator fans a campaign's approved copy out into.
+ *
+ * This is what `creativesFromCopy` iterates, and it used to be AD_FORMAT_IDS
+ * outright — every registered format got a row in the same common design
+ * object. That assumption is exactly what a media format breaks: fanning out
+ * over the full list would mint a `video_preroll_5s` creative carrying a
+ * headline, a palette and an image URL, mark it `ready` like its siblings, and
+ * hand an HTML renderer a format it has no template for. The result reads as a
+ * banner, which is the one outcome a five-second pre-roll must never have.
+ *
+ * So the design fan-out is the complement of STREAMING_FORMAT_IDS rather than
+ * the whole registry. Video creatives are created by the video pipeline, which
+ * owns their readiness separately.
+ */
+export const DESIGN_FORMAT_IDS: AdFormatId[] = AD_FORMAT_IDS.filter((f) => !isStreamingFormat(f));
+
+// The same list with its label and nominal box, for the dashboard preview strip
+// and format editors. Those surfaces render every entry through <AdPreview>,
+// which only knows how to draw markup — so they must iterate this rather than
+// AD_FORMATS. They currently skip any format with no creative row, which hides
+// the problem while nothing mints a video creative; that stops being true the
+// moment the video pipeline lands, and a silent banner-shaped video preview is
+// not a failure anyone would notice in review.
+export const DESIGN_FORMATS = AD_FORMATS.filter((f) => !isStreamingFormat(f.id));
+
 // Sizes offered to publishers on the Monetize page — the ones they can copy an
 // embed for and install. A subset of AD_FORMATS that grows as each size is
 // surfaced (one PR per size). Keep the medium rectangle first: it's the safe
@@ -84,7 +141,10 @@ export const AD_FORMAT_IDS = AD_FORMATS.map((f) => f.id) as AdFormatId[];
 //
 // WEB ONLY: these are the formats rendered as an <iframe> by /ad.js and dropped
 // into HTML by the GitHub auto-installer. Text/terminal formats must not be in
-// this list — they're fetched, not embedded.
+// this list — they're fetched, not embedded. Neither must a streaming format:
+// the auto-installer would drop a video unit into somebody's HTML with no
+// player, no entitlement check and no session, which is three different kinds
+// of wrong. Streaming publishers register a property instead.
 export const PUBLISHER_FORMAT_IDS: AdFormatId[] = [
   "banner_300x250",
   "banner_728x90",
@@ -124,6 +184,14 @@ export function fitAdFormat(
   width: number | null | undefined,
   allowed: readonly string[] | null | undefined,
 ): AdFormatId | null {
+  // A streaming pre-roll is never negotiated here. This function is the single
+  // gate in front of serveAd(), which renders HTML and ASCII — so refusing the
+  // format at this one point is what makes "an unrendered video cannot serve"
+  // true no matter how a slot is configured, including a slot that somehow
+  // lists it. Video is selected by the playback decision endpoint instead,
+  // which checks for a published, validated media revision first.
+  if (isStreamingFormat(requested)) return null;
+
   const offers = (f: AdFormatId) => !Array.isArray(allowed) || allowed.includes(f);
   if (!offers(requested)) return null;
 
diff --git a/supabase/migrations/20260924130000_ad_video_preroll.sql b/supabase/migrations/20260924130000_ad_video_preroll.sql
new file mode 100644
index 0000000..2707922
--- /dev/null
+++ b/supabase/migrations/20260924130000_ad_video_preroll.sql
@@ -0,0 +1,291 @@
+-- Streaming pre-roll: the five-second video ad format.
+--
+-- Adds `video_preroll_5s`, a creative served as media a viewer plays before a
+-- stream rather than as a document a renderer produces. Work package A of the
+-- streaming-ads spec: schema and format registration only. Nothing here renders
+-- an MP4, selects one, or serves one — those are packages B and D.
+--
+-- This deliberately does NOT follow the shape of the last two format additions
+-- (20260730120000_ad_terminal_ascii, 20260818120000_ad_feed_item). Both of
+-- those widened the creative CHECK, added the format to every slot's inventory,
+-- and backfilled a creative per campaign from copy that already existed. Steps
+-- 2 and 3 are wrong for a media format, and the reason is the same for each:
+--
+--   * Slot inventory drives serveAd(), which renders HTML and ASCII. Adding the
+--     format there would offer a video to the display path. Streaming
+--     publishers register an ad_streaming_property instead, and video is
+--     selected by the playback decision endpoint, which checks for a published
+--     media revision before it will hand anything to a player.
+--
+--   * A backfill can clone a headline. It cannot clone a 150-frame H.264
+--     encode. Cloning the copy alone would mint rows that look `ready` and have
+--     no bytes behind them — an unrendered video that a serving path would be
+--     entitled to pick. Video creatives are created by the render pipeline,
+--     which sets published_revision only once ffprobe has validated the output.
+--
+-- So the invariant this migration is responsible for is the narrow one: the
+-- format exists and is storable, and nothing that exists today can serve it.
+--
+-- NOTE: prod migration history diverged — apply this single file via psql over
+-- the pooler, do NOT `supabase db push`.
+
+-- 1. Widen the creative format CHECK. -----------------------------------------
+
+alter table public.ad_creatives drop constraint if exists ad_creatives_format_check;
+alter table public.ad_creatives
+  add constraint ad_creatives_format_check
+  check (format in (
+    'banner_300x250', 'banner_728x90', 'banner_320x50',
+    'text_link', 'terminal_ascii', 'feed_item', 'video_preroll_5s'
+  ));
+
+-- 2. Media revision pointers on the creative. ---------------------------------
+--
+-- `requested_revision` is the design revision the advertiser last asked for;
+-- `published_revision` is the one that has validated media behind it. They are
+-- equal on a settled video creative and differ while a render is in flight.
+--
+-- published_revision NULL is the load-bearing state: it means "no validated
+-- media", and it is what selection filters on. A video creative therefore
+-- starts unservable by construction rather than by remembering to check.
+--
+-- Both are null for every non-video creative and every row that exists today;
+-- the display formats have no media and no revisions.
+alter table public.ad_creatives
+  add column if not exists requested_revision integer,
+  add column if not exists published_revision integer;
+
+alter table public.ad_creatives drop constraint if exists ad_creatives_revision_check;
+alter table public.ad_creatives
+  add constraint ad_creatives_revision_check check (
+    (format <> 'video_preroll_5s' and requested_revision is null and published_revision is null)
+    or (format = 'video_preroll_5s' and requested_revision is not null and requested_revision > 0)
+  );
+
+-- One video creative per campaign. The pre-roll is a single placement; a second
+-- one would only ever be ambiguity about which plays.
+create unique index if not exists ad_creatives_one_video_per_campaign
+  on public.ad_creatives(campaign_id)
+  where format = 'video_preroll_5s';
+
+-- 3. Render jobs. -------------------------------------------------------------
+--
+-- A job is keyed by a hash of its immutable inputs (design snapshot, source
+-- asset hashes, locale, audio mode, renderer version, output profile), so an
+-- unchanged design reuses a finished result instead of re-encoding it.
+--
+-- creative_id is nullable because a preview render is started from the Generate
+-- Ads screen before any campaign is saved. A preview job is owner-scoped and
+-- can never be bound to serving until saveCampaign adopts it.
+create table if not exists public.ad_video_jobs (
+  id uuid primary key default gen_random_uuid(),
+  owner_id uuid not null references auth.users(id) on delete cascade,
+  campaign_id uuid references public.ad_campaigns(id) on delete cascade,
+  creative_id uuid references public.ad_creatives(id) on delete cascade,
+  revision integer not null check (revision > 0),
+  render_hash text not null,
+  output_profile text not null default 'default',
+  design jsonb not null default '{}'::jsonb,
+  renderer_version text not null default '',
+  state text not null default 'queued'
+    check (state in ('queued','rendering','validating','ready','failed')),
+  attempts integer not null default 0 check (attempts >= 0 and attempts <= 3),
+  error_code text,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  -- A preview job has no campaign; a campaign job must belong to the campaign's
+  -- creative when it has one.
+  constraint ad_video_jobs_preview_or_campaign
+    check (campaign_id is not null or creative_id is null)
+);
+
+-- The dedupe key: identical inputs are one job, whoever asks and however often.
+create unique index if not exists ad_video_jobs_render_hash_key
+  on public.ad_video_jobs(render_hash, output_profile);
+create index if not exists ad_video_jobs_owner_idx on public.ad_video_jobs(owner_id);
+create index if not exists ad_video_jobs_creative_idx on public.ad_video_jobs(creative_id);
+-- Queue drain order, and the index the depth alert reads.
+create index if not exists ad_video_jobs_pending_idx
+  on public.ad_video_jobs(created_at)
+  where state in ('queued','rendering','validating');
+
+-- 4. Rendered media. ----------------------------------------------------------
+--
+-- One row per (creative, revision, profile): the 1080p downloadable master, the
+-- 720p/480p delivery MP4s, the HLS package, the poster, captions, and the audio
+-- companion are each a profile. Rows are append-only — a new revision never
+-- overwrites an old one, because a decision already issued pins the revision it
+-- promised and must keep resolving to the bytes the viewer was sent.
+create table if not exists public.ad_video_assets (
+  id uuid primary key default gen_random_uuid(),
+  creative_id uuid not null references public.ad_creatives(id) on delete cascade,
+  owner_id uuid not null references auth.users(id) on delete cascade,
+  revision integer not null check (revision > 0),
+  profile text not null
+    check (profile in ('master_1080p','mp4_720p','mp4_480p','hls','poster','captions','audio')),
+  object_key text not null,
+  content_type text not null,
+  byte_size bigint not null check (byte_size > 0),
+  sha256 text not null,
+  width integer,
+  height integer,
+  -- Measured by ffprobe on the encoded output, never copied from the request.
+  duration_ms integer,
+  codecs text,
+  validation jsonb not null default '{}'::jsonb,
+  published boolean not null default false,
+  created_at timestamptz not null default now()
+);
+
+create unique index if not exists ad_video_assets_rev_profile_key
+  on public.ad_video_assets(creative_id, revision, profile);
+create index if not exists ad_video_assets_published_idx
+  on public.ad_video_assets(creative_id, revision)
+  where published;
+
+-- 5. Streaming properties. ----------------------------------------------------
+--
+-- The publisher side of a video fill. A property is a streaming site or app
+-- that has been registered, tested and enabled; its backend authenticates with
+-- a property-scoped credential and is the only thing allowed to assert whether
+-- a viewer needs an ad.
+--
+-- `integration_mode` records which of the spec's three delivery profiles was
+-- tested for this property, because a browser integration does not imply a
+-- receiver one and enabling the wrong one ships a broken pre-roll.
+create table if not exists public.ad_streaming_properties (
+  id uuid primary key default gen_random_uuid(),
+  owner_id uuid not null references auth.users(id) on delete cascade,
+  project_id uuid references public.projects(id) on delete set null,
+  property_key text not null,
+  domain text not null,
+  allowed_origins text[] not null default '{}',
+  slot_id uuid references public.ad_slots(id) on delete set null,
+  credential_ref text,
+  integration_mode text not null default 'client_preroll'
+    check (integration_mode in ('client_preroll','hls_interstitial','server_manifest')),
+  -- Which presentations this property's slot may be filled with. Terminal text
+  -- substitution is off unless explicitly listed: it is a different placement,
+  -- not a fallback the server may choose on a publisher's behalf.
+  allowed_presentations text[] not null default array['video'],
+  enabled boolean not null default false,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create unique index if not exists ad_streaming_properties_key on public.ad_streaming_properties(property_key);
+create index if not exists ad_streaming_properties_owner_idx on public.ad_streaming_properties(owner_id);
+
+-- 6. Playback decisions. ------------------------------------------------------
+--
+-- One row per playback session per placement — that uniqueness is the whole
+-- per-session pre-roll rule. A duplicate request returns the row that already
+-- exists, so a reconnect, a playlist reload, a player remount or a retried
+-- request cannot stack a second ad onto a session that already had one.
+--
+-- `outcome` is terminal state for the session: once it says completed or
+-- failed_open, that session is done regardless of what a client reports later.
+create table if not exists public.ad_video_decisions (
+  id uuid primary key default gen_random_uuid(),
+  property_id uuid not null references public.ad_streaming_properties(id) on delete cascade,
+  playback_session_id text not null,
+  placement text not null default 'preroll',
+  slot_id uuid references public.ad_slots(id) on delete set null,
+  campaign_id uuid references public.ad_campaigns(id) on delete set null,
+  creative_id uuid references public.ad_creatives(id) on delete set null,
+  asset_revision integer,
+  result text not null
+    check (result in ('ad','house','no_ad','unsupported_playback')),
+  reason text,
+  delivery text
+    check (delivery in ('client_mp4','hls_interstitial','server_manifest','terminal_card')),
+  presentation_kind text not null default 'video'
+    check (presentation_kind in ('video','audio','terminal_text')),
+  surface text not null default 'web'
+    check (surface in ('web','pwa','desktop','cli','tui','headless')),
+  -- The destination as promised at decision time. The click redirect resolves
+  -- from here, so editing a campaign's URL afterwards cannot redirect a viewer
+  -- who was shown the old claim to a different place.
+  destination_url text,
+  entitlement_checked_at timestamptz,
+  -- Set once, by the first accepted `start`. Its presence is what a click
+  -- checks before it is allowed to bill.
+  impression_id uuid references public.ad_impressions(id) on delete set null,
+  outcome text
+    check (outcome in ('completed','abandoned','error','fail_open','entitlement_changed')),
+  expires_at timestamptz not null,
+  created_at timestamptz not null default now()
+);
+
+create unique index if not exists ad_video_decisions_session_key
+  on public.ad_video_decisions(property_id, playback_session_id, placement);
+create index if not exists ad_video_decisions_campaign_idx on public.ad_video_decisions(campaign_id);
+create index if not exists ad_video_decisions_created_idx on public.ad_video_decisions(created_at);
+
+-- 7. Playback events. ---------------------------------------------------------
+--
+-- Client-reported measurements, kept separate from the impression ledger on
+-- purpose. A decision is not an impression, a byte range is not a view, and a
+-- text card is not a video completion; keeping these here means none of them
+-- can be mistaken for one by a reporting query that joins the wrong table.
+create table if not exists public.ad_video_events (
+  id uuid primary key default gen_random_uuid(),
+  decision_id uuid not null references public.ad_video_decisions(id) on delete cascade,
+  event_id text not null,
+  event_type text not null check (event_type in (
+    'asset_requested','start','first_quartile','midpoint','third_quartile',
+    'complete','click','error','abandon','entitlement_changed','fail_open',
+    'text_start','text_complete'
+  )),
+  media_time_ms integer check (media_time_ms >= 0),
+  played_ms integer check (played_ms >= 0),
+  measurement_source text not null default 'media_element',
+  error_reason text,
+  client_ts timestamptz,
+  received_at timestamptz not null default now()
+);
+
+-- One-shot progress events dedupe by type; repeated diagnostics dedupe by the
+-- client's own event id.
+create unique index if not exists ad_video_events_once_key
+  on public.ad_video_events(decision_id, event_type)
+  where event_type in (
+    'start','first_quartile','midpoint','third_quartile','complete',
+    'text_start','text_complete'
+  );
+create unique index if not exists ad_video_events_event_id_key
+  on public.ad_video_events(decision_id, event_id);
+
+-- 8. RLS. ---------------------------------------------------------------------
+--
+-- Advertisers see their own render jobs and media. Decisions and events are
+-- written by the service-role client from an authenticated property backend and
+-- are never readable by an end user, so they get RLS with no public policy —
+-- the same shape ad_impressions uses.
+
+alter table public.ad_video_jobs enable row level security;
+alter table public.ad_video_assets enable row level security;
+alter table public.ad_streaming_properties enable row level security;
+alter table public.ad_video_decisions enable row level security;
+alter table public.ad_video_events enable row level security;
+
+drop policy if exists "own video jobs" on public.ad_video_jobs;
+create policy "own video jobs" on public.ad_video_jobs
+  for all using (owner_id = auth.uid()) with check (owner_id = auth.uid());
+
+drop policy if exists "own video assets" on public.ad_video_assets;
+create policy "own video assets" on public.ad_video_assets
+  for all using (owner_id = auth.uid()) with check (owner_id = auth.uid());
+
+drop policy if exists "own streaming properties" on public.ad_streaming_properties;
+create policy "own streaming properties" on public.ad_streaming_properties
+  for all using (owner_id = auth.uid()) with check (owner_id = auth.uid());
+
+-- Keep updated_at honest on the two tables that are edited in place.
+drop trigger if exists ad_video_jobs_touch on public.ad_video_jobs;
+create trigger ad_video_jobs_touch before update on public.ad_video_jobs
+  for each row execute function public.ad_campaigns_touch();
+
+drop trigger if exists ad_streaming_properties_touch on public.ad_streaming_properties;
+create trigger ad_streaming_properties_touch before update on public.ad_streaming_properties
+  for each row execute function public.ad_campaigns_touch();
diff --git a/tests/ads-template-copy.test.ts b/tests/ads-template-copy.test.ts
index b027bf1..7c2491e 100644
--- a/tests/ads-template-copy.test.ts
+++ b/tests/ads-template-copy.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { templateCopy, creativesFromCopy, AD_FORMAT_IDS } from "@/lib/ads/creative";
+import { templateCopy, creativesFromCopy, DESIGN_FORMAT_IDS } from "@/lib/ads/creative";
 import type { SiteBrand } from "@/lib/ads/brand";
 
 const brand: SiteBrand = {
@@ -39,9 +39,11 @@ describe("template copy, for when no model has credit", () => {
     expect(bare.bgColor).toBe("#0b0d10");
   });
 
-  it("yields one creative per format, with the page image as the hero", () => {
+  it("yields one creative per design format, with the page image as the hero", () => {
     const creatives = creativesFromCopy(brand, templateCopy(brand), brand.ogImage);
-    expect(creatives.map((c) => c.format)).toEqual(AD_FORMAT_IDS);
+    // Design formats, not every registered format: the streaming pre-roll is
+    // media a worker encodes and has no design object to generate here.
+    expect(creatives.map((c) => c.format)).toEqual(DESIGN_FORMAT_IDS);
     for (const creative of creatives) {
       expect(creative.imageUrl).toBe(brand.ogImage);
       expect(creative.headline.length).toBeGreaterThan(0);
diff --git a/tests/ads-video-format.test.ts b/tests/ads-video-format.test.ts
new file mode 100644
index 0000000..487c47b
--- /dev/null
+++ b/tests/ads-video-format.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import {
+  AD_FORMATS,
+  AD_FORMAT_IDS,
+  DESIGN_FORMATS,
+  DESIGN_FORMAT_IDS,
+  PUBLISHER_FORMAT_IDS,
+  PUBLISHER_TEXT_FORMAT_IDS,
+  PUBLISHER_FEED_FORMAT_IDS,
+  STREAMING_FORMAT_IDS,
+  VIDEO_FORMAT_ID,
+  fitAdFormat,
+  formatSpec,
+  isStreamingFormat,
+} from "@/lib/ads/formats";
+import { creativesFromCopy, templateCopy } from "@/lib/ads/creative";
+import type { SiteBrand } from "@/lib/ads/brand";
+
+const brand: SiteBrand = {
+  url: "https://nichedb.dev/",
+  domain: "nichedb.dev",
+  title: "NicheDB",
+  description: "An open, ever-growing database of real-time data.",
+  text: "NicheDB is a platform for databases that only ever grow.",
+  logoUrl: null,
+  ogImage: "https://nichedb.dev/icons/icon-512x512.png",
+  themeColor: "#12161f",
+  palette: ["#12161f", "#6ee7b7", "#ffffff"],
+};
+
+// The display formats as they stood before the pre-roll was registered. Spelled
+// out rather than derived, so that a change to the registry has to be a
+// deliberate edit here too.
+const FORMATS_BEFORE_VIDEO = [
+  "banner_300x250",
+  "banner_728x90",
+  "banner_320x50",
+  "text_link",
+  "terminal_ascii",
+  "feed_item",
+];
+
+describe("the streaming pre-roll is registered", () => {
+  it("exists as a format with a real 16:9 master frame", () => {
+    expect(AD_FORMAT_IDS).toContain(VIDEO_FORMAT_ID);
+    const spec = formatSpec(VIDEO_FORMAT_ID);
+    expect([spec.w, spec.h]).toEqual([1920, 1080]);
+    expect(isStreamingFormat(VIDEO_FORMAT_ID)).toBe(true);
+    expect(isStreamingFormat("banner_300x250")).toBe(false);
+    expect(isStreamingFormat(null)).toBe(false);
+  });
+});
+
+describe("registering it changed nothing about the existing formats", () => {
+  it("leaves the design fan-out exactly as it was", () => {
+    expect(DESIGN_FORMAT_IDS).toEqual(FORMATS_BEFORE_VIDEO);
+    expect(DESIGN_FORMATS.map((f) => f.id)).toEqual(FORMATS_BEFORE_VIDEO);
+  });
+
+  it("generates one creative per design format and none for video", () => {
+    const creatives = creativesFromCopy(brand, templateCopy(brand), brand.ogImage);
+    expect(creatives.map((c) => c.format)).toEqual(FORMATS_BEFORE_VIDEO);
+    // The specific failure this guards: a video creative carrying a headline
+    // and a palette, marked ready alongside its siblings, that an HTML renderer
+    // would then draw as a banner.
+    expect(creatives.some((c) => isStreamingFormat(c.format))).toBe(false);
+  });
+
+  it("keeps video out of every publisher-facing format list", () => {
+    for (const list of [
+      PUBLISHER_FORMAT_IDS,
+      PUBLISHER_TEXT_FORMAT_IDS,
+      PUBLISHER_FEED_FORMAT_IDS,
+    ]) {
+      expect(list).not.toContain(VIDEO_FORMAT_ID);
+    }
+    // /ad.js and the GitHub auto-installer embed exactly this list.
+    expect(PUBLISHER_FORMAT_IDS).toEqual([
+      "banner_300x250",
+      "banner_728x90",
+      "banner_320x50",
+      "text_link",
+    ]);
+  });
+
+  it("does not disturb display format negotiation", () => {
+    // A leaderboard on a phone still downgrades to the rectangle, and the
+    // registry's extra entry does not become a fallback candidate.
+    expect(fitAdFormat("banner_728x90", 390, FORMATS_BEFORE_VIDEO)).toBe("banner_300x250");
+    expect(fitAdFormat("banner_300x250", 1200, FORMATS_BEFORE_VIDEO)).toBe("banner_300x250");
+    expect(fitAdFormat("terminal_ascii", null, FORMATS_BEFORE_VIDEO)).toBe("terminal_ascii");
+  });
+});
+
+describe("an unrendered video cannot reach the display serving path", () => {
+  // fitAdFormat is the single gate in front of serveAd(), which renders HTML
+  // and ASCII. Refusing there is what makes this true regardless of how a slot
+  // is configured — including a slot that has somehow been given the format.
+  it("refuses video even when the slot offers it", () => {
+    expect(fitAdFormat(VIDEO_FORMAT_ID, 1920, [...FORMATS_BEFORE_VIDEO, VIDEO_FORMAT_ID])).toBeNull();
+    expect(fitAdFormat(VIDEO_FORMAT_ID, null, [VIDEO_FORMAT_ID])).toBeNull();
+    // No slot list at all normally means "no basis to second-guess"; video is
+    // still refused.
+    expect(fitAdFormat(VIDEO_FORMAT_ID, 1920, null)).toBeNull();
+  });
+
+  it("refuses every streaming format, not just the one we happen to have", () => {
+    for (const id of STREAMING_FORMAT_IDS) {
+      expect(fitAdFormat(id, 1280, AD_FORMATS.map((f) => f.id))).toBeNull();
+    }
+  });
+});
+
+describe("the design-object write path refuses video", () => {
+  // cleanCreative() is not exported, so this asserts the allowlist it is built
+  // from. The hole it closes: a crafted updateCreatives payload naming
+  // video_preroll_5s would otherwise be accepted as a design object and written
+  // as a creative with a headline, a palette, and no media behind it.
+  it("allowlists design formats, not the whole registry", () => {
+    expect(DESIGN_FORMAT_IDS).not.toContain(VIDEO_FORMAT_ID);
+    expect(AD_FORMAT_IDS).toContain(VIDEO_FORMAT_ID);
+    expect(DESIGN_FORMAT_IDS.length).toBe(AD_FORMAT_IDS.length - STREAMING_FORMAT_IDS.length);
+  });
+});