Ship It Inert First: A Reference-Matching Engine That Was Dead Code for Two Days

Some feature requests are simple to state and dangerous to ship in one PR: "make our generated ad resemble this reference video." Resemble how — the on-camera person, the shot pacing, the hook, the b-roll ratio, the graphics burned into frame? Every one of those is a different subsystem, and wiring all of them at once into a pipeline that already renders paid, irreversible video means one bad merge can degrade every run behind it. I built this feature — a "generation reference" that lets a run's presenter and pacing echo a chosen clip — as roughly fifteen PRs over three days, and the shape of that rollout is the actual subject of this post.

An inert feature that compiles, type-checks, and has test coverage looks exactly like a working one. The only way to tell the difference is to check whether anything actually calls it in production.

The resolver and catalog, wired to nothing

PR #253 built the resolver and the catalog for generation references and shipped with the flag off and the catalog empty. Nothing consumed it. Ingest, the asset route, and the job shape all followed in later PRs — deliberately, so each one could be reviewed and verified against a narrow claim instead of against "does the whole feature work end to end."

The design also diverged from the pattern a sibling tool used for a similar idea. That tool lets an editor say "use the reference itself as the look I want" — because their reference is the aesthetic. Here, referenceVideoPath means something different: it's the competitor's ad being replicated for pacing and structure. Using it directly as a generation reference would lock the presenter to the competitor's on-camera person — the opposite of the intent. Copying an interface from a sibling tool without checking what the field actually means in this pipeline would have shipped a privacy and brand problem disguised as feature parity.

An asset route that has to be reachable without auth

PR #254 built the asset route, and it's a good example of a security decision that looks wrong until you know why. The route is excluded from the auth middleware matcher — same treatment as the avatar-asset route. The reason isn't the browser, it's the vendor: this URL gets handed to Kling as a request parameter, and a third-party vendor cannot attach this pipeline's internal auth header. A browser preview would work fine either way, since it goes through an authenticated proxy. So the route has to be reachable unauthenticated — which is exactly why the path resolution goes through the catalog rather than the filesystem directly:

const entry = getGenerationRefBySlug(slug);
if (!entry || entry.assetFile !== requestedFile) {
  return notFound();
}
// only a slug the catalog explicitly owns can resolve to a file —
// an unauthenticated route can't be turned into an arbitrary-path read

Excluding a route from auth is a five-minute change. Making that safe took understanding exactly which caller — a vendor with no ability to authenticate — forced the exclusion, and constraining the route's reach to only what the catalog explicitly lists.

Refusing an unusable reference instead of silently downgrading

PR #256 staged a chosen reference onto disk — or refused it outright. The refusal path exists because of an asymmetry in how the vendor handles bad input: Kling applies its size constraint to the whole request, and a reference under 720px doesn't degrade gracefully. It 422s every clip in the run, and the retry ladder underneath then renders them plain, silently, without the reference the editor explicitly chose. Refusing at staging time costs one cheap probe. The alternative costs a full paid run that quietly ignored what the editor asked for, with nothing in the output telling them so.

Five PRs of dead code

PR #267 is the PR I'd point to if someone asked what "ship it inert first" actually protects against, because it's also the failure mode inside that same discipline. resolveGenerationRef, stageGenerationRef, and a third helper had zero production callers. job.generationRef was never written by anything. There was no listing route, so a picker UI had nothing to read even if one had been built. Every prior PR had shipped clean, typed, and tested — and dead code that compiles and passes its own tests reads exactly like a working feature from the PR list. The only way #267 caught it was checking wiring specifically, not correctness: does anything outside this file's own tests call this function?

The same PR found an environment-variable collision underneath the dead code: GENERATION_REF_DEFAULT was claimed twice — once as the boolean flag gating the feature, and again inside the resolver's own documented precedence as the name of a default reference. Two different systems reading the same variable name for two different purposes, both silently wrong in a feature nothing was calling yet.

Wiring it in, one behavior at a time

Once the plumbing was verified live, each subsequent PR added exactly one consuming behavior:

A lesson almost lost to a deletion

PR #274 is worth its own paragraph. The PR after it deletes an older scene-swap pipeline entirely, and buried inside that pipeline was a genuinely valuable finding: an earlier version tried FFmpeg-only cut detection, measured it against a real sample, and found it caught roughly one cut in ten — soft and CGI transitions barely move frame-to-frame difference at all — and reverted to a vision-model pass using FFmpeg only as a hint generator. That lesson lived nowhere except inside the code being deleted. Worse: the live production path had never received that fix. It called bare cut-detection directly and inherited the exact failure the swipe path had already fixed and forgotten to propagate. A 41-second reference came back with almost none of its cuts detected, silently, because the fix for that specific failure existed one file away and had never been ported over. Lifting the analysis layer out before the deletion wasn't just code hygiene — it was rescuing a debugging finding that would otherwise have been deleted along with the code that discovered it.

The grammar bug: whose voice is telling this story

Two of the last wiring bugs are about a subtler kind of mismatch than shape or timing. PR #301 found that the reference's own grammar — its script, written from its own presenter's point of view — was deciding who speaks in this pipeline's ad, producing narration that made sense for the reference's cast and not for this one. PR #302 found a narrated scene that was still being authored as if it were a to-camera selfie, a leftover assumption from before reference-mirroring existed. Both are the same class of bug as the dead-code PR, one level up the stack: correctly wired plumbing carrying an assumption from the wrong source.

The pattern

Fifteen PRs to ship one feature is not inefficiency when the feature touches presenter identity, shot pacing, b-roll sourcing, and vendor-facing asset delivery all at once. Each inert PR bought a checkpoint where "nothing changed for existing runs" could be verified before the next behavior went live. The one PR that mattered most for trusting the whole rollout wasn't a feature PR at all — it was the one that stopped and asked whether the five PRs before it had actually done anything, and found out they hadn't.