Know your unknowns · Post-implementation

Quiz me before I merge

Asking for a report with a quiz you must pass turns "I skimmed the diff" into verified understanding — the artifact won't let you feel done until you actually are.

The Prompt

I want to make sure I understand everything that happened in this change before I merge. Give me an HTML report on the export-feature diff — context, intuition, what was done — with a quiz at the bottom that I must pass.

What Claude Produced

Acme · Merge readiness report

Clip export: what changed and why

A 14-file diff that adds server-side clip export to review threads. Read the three sections below, then pass the quiz. If you can't, you're not ready to merge — and that's the point.

feature/clip-export→main · 14 files · 9 commits

files changed

+612

lines added

−148

lines removed

The mental model

One diagram is worth 14 files: where an export request goes now vs. before.

Before this change, "export a clip" meant the browser stitched frames client-side with MediaRecorder and uploaded the result — slow, tab-locked, and broken on Safari. Now the client only requests an export; a new worker renders it server-side from the original media and the client polls a job until a signed download URL appears.

Before · client-side render

ReviewPlayer.tsx

↓

MediaRecorder capture (in-tab)

↓~40–90s, tab locked

PUT /uploads (whole file)

↓

S3 exports/ bucket

After · server-side job

ReviewPlayer.tsx

↓POST /api/exports (returns job id)

export-worker (new, ffmpeg)

↓

S3 exports/ bucket

↓

jobs table (new)

↓client polls every 2s

GET /api/exports/:id → signed URL

Three non-obvious behaviors this introduces

The parts a diff skim won't tell you. Each one is deliberate — here's the reasoning.

Exports render from the original upload, not the proxy the reviewer watched

WhatThe worker pulls media/originals/, never the 720p review proxy. An exported clip can therefore look sharper than what the reviewer saw when they drew their annotations.

WhyEditors export clips to hand off to clients; shipping the compressed proxy would embarrass them. Annotation coordinates are stored normalized (0–1), so they re-project onto the full-res frame correctly.

Whereworker/export/render.ts:41 worker/export/burn_in.ts:88

Export jobs survive a worker crash — via a visibility timeout, not retries

WhatA job row is claimed by setting locked_until = now() + 10min. If the worker dies mid-render, no retry fires; the lock simply expires and the next idle worker picks the job up from scratch.

Whyffmpeg renders aren't idempotent mid-flight, and a retry queue would need dead-letter handling we don't want yet. Lock expiry gives at-least-once semantics with one column. Consequence: a crashed job looks "processing" for up to 10 minutes before recovering.

Wheredb/migrations/0142_export_jobs.sql worker/export/claim.ts:19

Download URLs expire after 24 hours — the export itself lives 7 days

WhatThe signed S3 URL returned by GET /api/exports/:id is valid for 24h, but the underlying object isn't deleted until a 7-day lifecycle rule fires. Re-hitting the endpoint mints a fresh URL with no re-render.

WhyShort URLs limit link-forwarding outside the workspace (exports can contain unreleased footage); the longer object TTL means a stale Slack link costs one API call to revive, not a 90-second re-render.

Whereapi/exports/get.ts:57 infra/s3_lifecycle.tf:23

Existing behavior this leans on

Workspace-scoped signed-URL auth. GET /api/exports/:id does no permission check of its own — it reuses the requireWorkspaceMember middleware that already guards every media route. If that middleware's session handling ever changes (there's an open ticket, BL-2214, about guest reviewer sessions), export downloads change with it. Nothing in this diff would flag that.

Part 2 · Prove it

Six questions before you merge

Not trivia — each one is a decision you'd have to make correctly during an incident or a review.

Score: 0 / 6 · 0 answered

✓

Cleared to merge

6/6 — you can explain this change to whoever gets paged for it. Standard checklist below.

✓Understanding verified (this quiz, 6/6)
✓CI green on feature/clip-export · 412 tests
✓Migration 0142 reviewed — additive, no backfill
○Squash-merge with the summary above as the commit body
○Watch export-worker dashboards for 30 min post-deploy
○Note BL-2214 dependency in the merge comment

Not yet — re-read these sections

You missed the questions below. The gaps map straight back to the report: