video_editing_poc/.claude/skills/video-editing-proof-and-analysis-toolkit/SKILL.md

name

description

video-editing-proof-and-analysis-toolkit

Load this skill after symptom triage when a video-editing change or incident must be proved from first principles: state transitions, timeline or keyframe accuracy, FFmpeg filter/audio graphs, loudness and true peak, highlight-ranking precision/recall/normalized discounted cumulative gain (nDCG), local-model output versus fallback, queue retry/DLQ/idempotency, filesystem atomicity/path confinement, capacity/cost, reproducibility, or causal debugging. Use it to establish or refute a causal mechanism before accepting a benchmark, QA report, cinematic-quality claim, fallback, or production-readiness claim as evidence.

Video Editing Proof And Analysis Toolkit

Purpose

Turn a claim into a prediction, a discriminating experiment, and an auditable conclusion. A mechanism is a causal account that explains the successful cases, failures, and negative controls with the same rules. A green test, an existing file, or a plausible story is not a mechanism.

Repository facts in this skill were verified on 2026-07-21. Numeric baselines in docs/ are historical workspace observations, not current acceptance thresholds.

Use And Routing

Use this skill to derive what an observation should be and to distinguish competing causes. Use these siblings for the surrounding work:

Need	Load instead or next
Classify, approve, implement, or promote a behavior change	video-editing-change-control
Triage a live symptom quickly	video-editing-debugging-playbook
Reconstruct an earlier incident or rejected fix	video-editing-failure-archaeology
Decide the complete acceptance suite or human review	video-editing-validation-and-qa
Interpret codec, color, audio, timing, or editing theory	cinematic-media-engineering-reference
Run approved local diagnostics	video-editing-diagnostics-and-tooling
Change flags or inspect effective configuration	video-editing-config-and-flags
Execute the hardest highlight-quality program	video-editing-cinematic-highlights-campaign

Do not use this skill to authorize rendering, production mutation, DLQ redrive, dependency installation, or model acquisition. Analysis never routes around change control.

Hard Safety Boundary

1. Work offline. Do not call external AI services or enable network access.
2. Use only pre-provisioned, licensed local models and licensed assets whose identity and checksum are recorded.
3. Do not invoke tools/run_local_cv_worker.sh, tools/run_local_asset_worker.sh, or application startup as an experiment. Current defaults can bootstrap runtimes, download packages/models, scan inputs, and render.
4. Reject placeholder silence and synthetic fallback tones as production assets. “A file exists” and “samples are nonzero” do not establish voice, music, or SFX validity.
5. Probe only existing approved media. Do not generate or render media without the approval gate in video-editing-change-control.
6. Never change a production-facing default to test a hypothesis. Use an isolated fixture and explicit test configuration after approval.
7. Keep diagnostic output in target/ or an OS temporary directory. Never alter input/, output/, migrations, source media, or Git history.
8. Run Maven with -o during proof work so Maven fails on a missing cached dependency. Maven offline mode is not egress denial and does not prevent test code or subprocesses from networking; enforce network denial independently.

The Proof Record

Write this record before running an experiment:

Claim:
Competing mechanisms (at least two):
Assumptions and controlled variables:
Predicted numeric/structural observation for each mechanism:
Positive control:
Negative control:
Command and input checksums:
Observed result and uncertainty:
Which mechanisms were falsified:
Adversarial refutation still required:
Decision: reject | retain as candidate | accept for stated scope

Apply these rules:

• Predict a number, interval, ordering, state tuple, or file set before execution. “It should improve” is invalid.
• Change one causal factor at a time. Use an ablation: remove one component while holding all others fixed.
• Preserve negative results. One mechanism must explain both the expected positive and the expected absence under the negative control.
• Separate structural validity (schema, file, command, state) from semantic validity (correct highlight, intelligible voice, appropriate sound) and operational validity (load, crash, recovery).
• Report the denominator, sample selection, hardware, binary/model checksums, and uncertainty. Never promote a single clip or a single warm run.

Recipe 1: Prove State-Machine Invariants

Question. Can an entity reach only legal states, and do queue message state and job state remain consistent?

Assumptions. Define the entity, authoritative writer, transaction boundary, and terminal states. Current enums are ClipJobStatus, EditProjectStatus, and HighlightProjectStatus; enum membership alone does not enforce transitions.

Derive before running. Draw allowed edges and forbidden edges. For every operation predict (before, event, after, durable artifacts). Require terminal-state monotonicity unless an explicit, audited recovery operation exists.

Repo-safe experiment. Inspect all writers, then run focused offline tests:

rg -n 'ClipJobStatus\.|EditProjectStatus\.|HighlightProjectStatus\.|setStatus\(' src/main/java src/test/java
mvn -o -q -Dtest=DatabaseBackedClipJobQueueAdapterTest,HighlightDirectorFlowServiceTest,LocalDirectorSchedulerTest test

Interpretation. A test that reaches the expected final state does not prove forbidden edges are rejected. Add transition-table tests through change control. Current highlight code writes CREATED -> WAITING_FOR_DIRECTOR -> RENDERING -> RENDERED and failures, while ANALYZING/PLANNED exist without a centralized transition guard; treat the model as partially asserted, not enforced.

Adversarial refutation. Attempt stale replay, duplicate completion, failure after side effect, and terminal-to-active transition in an isolated test. Require the same rule to reject all forbidden sources, not controller-only validation.

Worked history. Before commit 1737d8b, one processing exception could make the job FAILED while the DB queue still intended PENDING retry. The mechanism was split ownership of terminal policy. Moving terminal failure to the queue’s max-attempt decision explains both non-terminal retries and DLQ exhaustion.

Recipe 2: Prove Timeline And Duration Arithmetic

Question. Does the planned timeline equal the rendered media timeline?

Assumptions. Fix the edit plan version, source identity, frame rate/timebase, audio sample rate, transition semantics, and output binary. Do not compare a stale plan to a newer render.

Derive before running. For decision i:

source_i = sourceEnd_i - sourceStart_i
rendered_i = source_i / playbackSpeed_i
planned_i = timelineEnd_i - timelineStart_i
timelineStart_1 = 0
timelineStart_i = timelineEnd_(i-1)
T_plan = timelineEnd_last

Current EditPlanValidator permits |rendered_i - planned_i| <= 0.05 s, contiguity error <= 0.001 s, final target error <= 1.0 s, and speed [0.25, 4.0]. These are implementation tolerances, not certified media-quality thresholds. Predict accumulated timing error from frame duration, audio sample period, transitions, and mux timebase before probing.

Repo-safe experiment. For an existing approved plan/output pair:

PLAN=output/edit-projects/PROJECT/edit-plan.json
MEDIA=output/edit-projects/PROJECT/final.mp4
test -f "$PLAN" && test -f "$MEDIA"
ffprobe -v error -show_entries format=start_time,duration -show_entries stream=index,codec_type,time_base,start_time,duration,nb_frames -of json "$MEDIA"
rg -n 'EPSILON|TARGET_TOLERANCE_SECONDS|renderedDuration|plannedDuration' src/main/java/org/example/videoclips/editing/EditPlanValidator.java

Do not infer media duration from RenderManifest.durationSeconds; the multi-clip and per-highlight render paths derive that field from the plan, while the project-level highlight flow sums ffprobe results. Probe the file used by the claim.

Interpretation. Distinguish plan arithmetic error, encoder/mux quantization, and transition overlap. A constant offset on every output implicates command/timebase behavior; error growing per segment implicates accumulation or rounding.

Adversarial refutation. Include fractional frame rates, nonzero stream start time, audio shorter/longer than video, speeds at both limits, and a final partial segment.

Worked history. Current highlight QA sets duration_matches_timeline=true with the explanation that duration is based on the plan. That is asserted QA: it cannot detect a muxed output whose actual duration differs. The discriminating evidence is plan-derived T_plan versus ffprobe-derived stream/container durations.

Recipe 3: Bound Keyframe And Segment Error

Question. Is a cut frame-accurate, or merely aligned to an existing keyframe?

Assumptions. FolderFfmpegClipper and FfmpegVideoClipperAdapter stream-copy in preservation/FAST paths; exact paths re-encode with forced keyframes. Stream copy preserves encoded packets and cannot create a keyframe at an arbitrary boundary.

Derive before running. Let requested boundary be b, surrounding keyframe timestamps k_prev <= b <= k_next, and maximum observed keyframe gap G. Predict the tool-specific chosen boundary from command shape; the empirical error must be compared with |b-k_prev| and |k_next-b|. Do not claim a universal direction without observing the muxer result. For forced-keyframe re-encode, predeclare a bound from output frame duration/timebase and then measure it.

Repo-safe experiment. Probe source keyframes and existing clips only:

SOURCE=/path/to/approved/source.mp4
CLIP=/path/to/existing/clip.mp4
ffprobe -v error -select_streams v:0 -skip_frame nokey -show_frames -show_entries frame=best_effort_timestamp_time,pkt_dts_time -of csv=p=0 "$SOURCE"
ffprobe -v error -show_entries format=start_time,duration -show_entries stream=time_base,start_time,duration -of json "$CLIP"
rg -n 'force_key_frames|segment_time|preserveInputQuality|AccuracyMode.EXACT' src/main/java/org/example/videoclips/folder/FolderFfmpegClipper.java src/main/java/org/example/videoclips/processing/FfmpegVideoClipperAdapter.java

Interpretation. Boundary error tracking source keyframe distance supports keyframe alignment. Error within a predeclared output-frame/timebase bound only in re-encode mode supports forced-keyframe accuracy. Codec names or clip-count metadata do not prove either.

Adversarial refutation. Test long GOP, variable frame rate, B-frames, nonzero start time, and audio packet boundaries. Compare first/last decoded frame content, not container duration alone.

Worked history. The folder workflow explicitly retains a quality-versus-exactness trade-off: packaged preserve-input-quality=true uses -c copy; false uses libx264/AAC and forced keyframes. Calling both modes “exact” would contradict the mechanism.

Recipe 4: Prove FFmpeg Filter And Audio Graphs

Question. Does every intended stream reach the output with the expected timebase, duration, gain, and label?

Assumptions. Freeze the exact command, input stream inventory, asset presence, channel layouts, and current editing properties. Treat optional input syntax separately from filter-label requirements.

Derive before running. Draw a directed graph: input stream -> trim/delay/rate -> gain -> sidechain -> mix -> loudness -> mapped output. For every label predict channel count, sample rate, start/end time, and whether absence is legal. Check video setpts=PTS/speed against audio atempo=speed.

Current renderer facts:

Graph behavior	Current implementation consequence
Segment audio is optional at -map 0:a?	A video-only timeline can be created.
Mix graph starts with [0:a]	A video-only timeline makes the mix graph fail even when music/voice/SFX inputs exist.
Highlight audio-mix failure is caught	The renderer copies the post-timeline, potentially publishing without intended assets.
amix duration=first	Output audio length is governed by timeline audio, not longest asset.
Music+voice uses sidechain compression	Music is the compressed signal; voice is the detector and is also mixed.

Repo-safe experiment. Inspect command construction and probe an existing output:

rg -n 'audioMixCommand|sidechaincompress|amix=|loudnorm=|setpts=|atempo=|fallback.*copy' src/main/java/org/example/videoclips/editing
MEDIA=/path/to/existing/approved/final.mp4
ffprobe -v error -show_streams -show_format -of json "$MEDIA"
ffmpeg -hide_banner -nostats -v error -i "$MEDIA" -map 0:v:0 -f null - -map 0:a:0 -f null -

Interpretation. Command presence proves intent, not application. Require output streams plus measured signal. An audio-less result after a logged mix failure is explained by the catch-and-copy path; a successful graph with wrong loudness needs a different mechanism.

Adversarial refutation. Use video-only source, mono/stereo assets, missing one optional asset, asset longer than timeline, and SFX beyond source-audio end. Never “fix” a graph by inserting prohibited silence.

Worked history. Commit 5d889b0 records “working version but not cinematic.” A valid FFmpeg graph explained renderability but not creative quality; later filters/assets/QA are hypotheses whose contribution still needs ablation and review.

Recipe 5: Measure Loudness, Dynamics, And True Peak

Question. Does mastered audio meet a declared delivery envelope without clipping or masking speech?

Definitions. LUFS-I is integrated program loudness; LRA is loudness range; dBTP is inter-sample true peak. Sample peak from volumedetect is not true peak.

Assumptions. Freeze the exact encoded output, channel layout, measurement tool/version, delivery target, tolerance, and speech windows. Measure after the final lossy encode.

Derive before running. Declare target and tolerance through validation/change control. Packaged filter targets are I=-16, TP=-1.5, LRA=11; they are current defaults, not measured acceptance. Predict integrated loudness, maximum true peak, LRA, silence proportion, and voice/music delta for the fixture.

Repo-safe experiment. Measure an existing approved output; this decodes to a null sink and does not render a file:

MEDIA=/path/to/existing/approved/final.mp4
ffmpeg -hide_banner -nostats -i "$MEDIA" -map 0:a:0 -af 'loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json' -f null - 2>&1
ffmpeg -hide_banner -nostats -i "$MEDIA" -map 0:a:0 -af 'ebur128=peak=true' -f null - 2>&1
rg -n 'loudness-target-i|loudness-true-peak|loudness-range|clippingDetectCommand|volumedetect' src/main/resources/application.yml src/main/java/org/example/videoclips/editing

Interpretation. Compare measured input_i, input_tp, and input_lra to the preregistered envelope. Current QA’s max_volume < -0.1 dBFS clipping check is a sample-peak warning, not proof of the configured -1.5 dBTP limit. One-pass loudnorm filter presence is not measurement.

Adversarial refutation. Include silence, isolated transient, codec round-trip, mono/stereo, and speech-over-music windows. A global LUFS pass can coexist with unintelligible voice; test local speech windows and human intelligibility separately.

Worked history. Commit bb23ac8 added mastering filters. That establishes graph construction, not that every output hits targets, especially when highlight audio failure falls back to copying the timeline.

Recipe 6: Prove Highlight Ranking

Question. Does the ranker find the moments reviewers label as highlights, in useful order?

Assumptions. Build a licensed, versioned evaluation set with independent timestamp labels and category strata. The repository currently has no certified creative golden set. CinematicHighlightAnalyzer uses metadata keyword classification, fixed windows, position roles, and clip-level quality scores repeated across every window; its tests prove bounds/order, not relevance.

Derive before running. Freeze temporal intersection-over-union threshold tau, top K, and split before scoring:

IoU(candidate, truth) = overlap_seconds / union_seconds
precision@K = matched_predictions_in_top_K / K
recall@K = uniquely_matched_truth_windows / truth_window_count
DCG@K = sum((2^relevance_i - 1) / log2(i + 1)); NDCG@K = DCG@K / ideal_DCG@K

Use one-to-one matching so duplicate overlapping candidates cannot inflate recall. Report per category and macro average. Predict metric deltas and confidence intervals before each change; never select tau or K on the test set.

Repo-safe experiment. First prove what current tests do and do not cover:

sed -n '1,220p' src/main/java/org/example/videoclips/editing/CinematicHighlightAnalyzer.java
sed -n '1,180p' src/test/java/org/example/videoclips/editing/CinematicHighlightAnalyzerTest.java
rg -n 'golden|ground.truth|precision|recall|NDCG|IoU' src/test docs

Then evaluate exported candidate JSON against separately reviewed labels with a deterministic evaluator added only through change control. Record exact-match policy, ties, missing categories, and bootstrap seed.

Ablations. Hold candidates fixed and remove one feature family at a time: source position, visual scores, audio events, scene boundaries, semantic/local-model features. A useful feature must predict a preregistered metric change and survive category-stratified negatives.

Interpretation. High precision with low recall means conservative discovery; high recall with low precision burdens the director. NDCG distinguishes useful ordering from an unordered candidate set. Do not aggregate away a failing content category.

Adversarial refutation. Include long clips where the 12-window cap changes step size, generic filenames, repeated scenes, quiet emotional moments, high-motion non-events, and near-duplicate windows.

Worked history. Category-aware planning (5006dfd) followed the “not cinematic” result, but history contains no controlled ranking comparison. Treat category boosts as candidates until labeled-set precision/recall/NDCG and ablations support them.

Recipe 7: Distinguish Model Signal From Fallback

Question. Did a declared local model produce the semantic asset, or did the system emit a placeholder or host fallback?

Assumptions. Freeze the requested asset type/prompt, declared local model checksum, runtime, seed/config, and expected duration. Do not infer provenance from a filename or directory.

Derive before running. Predict all three layers: provenance (model id, local path, checksum, runtime, seed/config), signal (duration, sample rate, channels, RMS/silence, spectrum), and semantics (speech transcript/intelligibility or licensed music/SFX rubric). Require all three. File existence is zero-layer proof.

Repo-safe experiment. Do not invoke the workers. Inspect current fallback paths and measure only an existing candidate asset:

rg -n 'write_silence|write_fallback_tone|fallbackTone|writeSilence|speech-fallback|strict_runtime|strict-runtime' tools/local_asset_worker.py src/main/java src/main/resources
AUDIO=/path/to/existing/candidate.wav
ffprobe -v error -show_streams -show_format -of json "$AUDIO"
ffmpeg -hide_banner -nostats -i "$AUDIO" -af 'silencedetect=noise=-60dB:d=0.2,astats=metadata=0:reset=0' -f null - 2>&1

Historical artifacts may contain exact silence from the former Python voiceover fallback, a 110 Hz low-level music tone, an 880 Hz short SFX tone, Java-generated tones, or host say/espeak speech. Those success paths were removed from the 2026-07-21 working tree. Keep detecting the signatures in old outputs; do not use absence of a known signature as a provenance whitelist.

Interpretation. Silence proves failure. Nonzero samples disprove only digital silence; they do not prove speech or model generation. A stable simple tone matching a known path plus absent model provenance supports fallback. Real speech from a host tool is still not the approved embedded model.

Adversarial refutation. Test a valid model asset, digital silence, known tone, corrupted WAV, unrelated audible audio, and host TTS. The mechanism must classify positives and negatives without relying on filename.

Worked history. On 2026-07-21 the workspace build passed while a clean archive failed LocalAssetGenerationStageTest; tests depended on an untracked virtual environment/host fallback. The working tree now makes that test deterministic and strict readiness fail closed. Environment-coupled success explains the old observations; only a new clean archive can confirm closure.

Recipe 8: Prove Retry, DLQ, Idempotency, And Leases

Question. Does each logical job have bounded attempts and at-most-one durable effect despite crashes and redelivery?

Assumptions. Fix queue mode, max-attempts, retry backoff, visibility timeout, transaction boundary, idempotency key, and side effects. The DB-queue proof does not generalize to the memory queue or a future broker.

Derive before running. For configured maximum M, predict attempt sequence 1..M; failures 1..M-1 yield message PENDING, job QUEUED, and one RETRY_SCHEDULED; failure M yields message DLQ, job FAILED, and terminal events. Predict side-effect cardinality by idempotency key. Let visibility timeout V exceed a measured runtime bound or provide lease extension; otherwise predict overlapping work after V.

Repo-safe experiment. Use existing mocks and read-only inspection:

mvn -o -q -Dtest=DatabaseBackedClipJobQueueAdapterTest test
rg -n 'attemptCount|maxAttempts|visibilityTimeout|RETRY_SCHEDULED|markTerminalFailure|DLQ|Idempotency' src/main/java src/test/java src/main/resources
sed -n '1,260p' docs/dlq-redrive-procedure.md

Interpretation. State correctness does not prove effect idempotency. Compare object key, clip index, database uniqueness constraints, and event counts after duplicate delivery. Current queue claims and processing occur in one transaction method, but FFmpeg/object-storage effects are not rolled back with a database transaction.

Adversarial refutation. Fail after upload/before row save, after row save/before completion, at V-epsilon and V+epsilon, and with two pollers. Do not redrive real DLQ rows as a test.

Worked history. Commit 1737d8b fixed premature terminal job failure. It does not by itself prove exactly-once external effects; that requires idempotency and crash-boundary tests.

Recipe 9: Prove Filesystem Atomicity And Path Confinement

Question. Can a reader observe a partial file, or can untrusted names escape the configured root?

Assumptions. Fix the configured root, filesystem/mount, writer/reader concurrency, crash point, and symlink policy. Lexical normalization and physical filesystem confinement are separate claims.

Derive before running. For publication require write-to-sibling-temp -> fsync as required -> atomic rename on the same filesystem. Predict reader observations as {old, new}, never partial. For confinement require validated token, root.resolve(name).normalize(), startsWith(root), rejection of absolute paths, separators, and ..; decide symlink policy explicitly.

Repo-safe experiment. Run current confinement tests and inspect publication sites:

mvn -o -q -Dtest=FileSystemEditProjectStoreTest,FileSystemHighlightProjectStoreTest,EditPlanInboxScannerTest test
rg -n 'ATOMIC_MOVE|writeValue\(|writeString\(|Files.copy|startsWith\(|validateProjectId|validate.*File' src/main/java/org/example/videoclips/editing

Interpretation. Current stores validate lexical paths but write JSON directly to final files; path confinement tests do not prove crash-safe publication. Highlight source claiming and inbox archival use ATOMIC_MOVE, which can fail across filesystems rather than silently degrade. startsWith on normalized paths does not settle symlink traversal.

Adversarial refutation. Test absolute paths, both separators, .., Unicode/confusable names if accepted, symlink inside root to outside, concurrent readers, process death mid-write, and cross-filesystem move. Keep these in JUnit temporary directories.

Worked history. Existing project.json/manifest files can claim rendered output while media is absent. That history shows why metadata publication and durable artifact publication must be one explicit invariant, not two independent existence checks.

Recipe 10: Build Resource, Capacity, And Cost Models

Question. What arrival rate, concurrency, disk, memory, model residency, and cost can the service sustain?

Assumptions. Freeze workload mix, source durations/codecs, warm/cold model state, hardware, worker topology, storage/database limits, retention, retry rate, and dated prices. State every omitted cost.

Derive before running. Use measured distributions, not a single average:

real_time_factor = processing_seconds / source_seconds
service_rate_per_worker = 1 / mean_job_seconds
required_concurrency ~= arrival_rate_per_second * target_system_time_seconds  (Little's Law)
scratch_bytes >= concurrency * (source + intermediates + output) * safety_factor
compute_cost/source_min = worker_seconds/source_min / 3600 * worker_cost/hour
transfer_seconds/source_min = transferred_MiB/source_min / measured_MiB_per_second

Add fixed local-model memory once per worker process, peak temporary tensors per concurrent inference, FFmpeg threads, JVM heap, and database/object-storage limits. Predict saturation resource and queue-growth slope before load.

Repo-safe experiment. Inspect historical models without treating them as current:

sed -n '1,260p' docs/cost-model-by-video-minute.md
sed -n '1,220p' docs/ffmpeg-preset-benchmark-baseline.md
sed -n '1,220p' docs/object-storage-bandwidth-benchmark-baseline.md
sed -n '1,260p' docs/load-test-signoff.md

The checked-in cost harness hardcodes example prices and prior benchmark values. Replace assumptions with dated target-environment measurements only after an approved benchmark. Never claim scalability from the stub worker baseline or the documentation-only load signoff.

Interpretation. Validate predictions against p50/p95/p99 service time and resource saturation. If measured queue slope differs, the arrival rate, service-time distribution, concurrency constraint, or retry amplification is missing from the model.

Adversarial refutation. Include cold model load, warm inference, mixed durations, 2x burst, slow storage, disk pressure, codec mix, retry amplification, and a 60-minute endurance run. A model must predict both steady state and backlog growth when arrival_rate > capacity.

Worked history. docs/load-test-signoff.md says execution evidence is pending. Existing local baselines explain planning inputs, not production API/worker throughput or cloud cost.

Recipe 11: Prove Reproducibility With Checksums

Question. Can another approved macOS/Linux/VPS/cloud runtime reproduce the result from the same declared inputs?

Assumptions. Define whether the claim is byte reproducibility or metric-bounded reproducibility. Freeze source/config/model/asset checksums, toolchain, locale/timezone, device, and randomness.

Derive before running. Predict which bytes must be identical and which measurements may vary. Media encodes may differ across FFmpeg/library/hardware builds; in that case require identical inputs/config and bounded semantic/technical metrics, not a fabricated byte-equality promise.

Repo-safe experiment. Capture source tree identity, tool versions, and existing artifact hashes without starting the service:

git rev-parse HEAD
java -version 2>&1
mvn -version
ffmpeg -version | sed -n '1,12p'
ffprobe -version | sed -n '1,5p'
git ls-files -s pom.xml src tools
ARTIFACT=/path/to/existing/approved/artifact
if command -v sha256sum >/dev/null 2>&1; then sha256sum "$ARTIFACT"; else shasum -a 256 "$ARTIFACT"; fi

For a local model record model-file checksum, license, runtime package lock, device, precision, seed, and inference parameters. A model name such as musicgen-small is not an immutable identity.

Interpretation. An identical artifact hash proves byte identity for that artifact only. A mismatch requires localization by input, intermediate, and toolchain hashes; it does not automatically prove semantic regression.

Adversarial refutation. Repeat from a clean archive with network disabled and no untracked virtual environments; compare macOS and Linux. Separate dependency-cache absence from test failure. Do not solve a clean failure by enabling downloads or committing a virtualenv.

Worked history. The workspace’s 216 tests passed while a clean archived checkout failed in local-asset generation. The untracked .venv-local-asset/host behavior is the discriminating variable, so “mvn test passed here” is not reproducible-build proof.

Recipe 12: Perform Causal Debugging

Question. Which single mechanism explains all observations, including negatives?

Assumptions. Freeze the incident time window, build, inputs, configuration, environment, and observation reliability. Mark unknowns rather than silently filling them.

Derive before running. Build a causal graph from input identity -> configuration -> state -> external/local side effects -> persisted metadata -> published artifact -> measured quality. Mark observation points. For each candidate cause, write a prediction matrix before touching code:

Experiment	Mechanism A predicts	Mechanism B predicts	Observation
Positive control	number/state/signature	number/state/signature	pending
Negative control	absence/different value	same value	pending
One-factor ablation	directional delta	no delta	pending
Crash/boundary case	durable state/effects	different tuple	pending

Repo-safe experiment. Locate the actual writers and historical change before selecting one minimal discriminator:

rg -n 'objectKey|markTerminalFailure|duration_matches_timeline|audio_mastering_applied|fallback' src/main src/test
git log --oneline --all -- src/main/java/org/example/videoclips
git show --stat 7307082 1737d8b 5d889b0 9b56e89

Interpretation. Accept only a mechanism whose predictions match the positive, negative, and boundary cases. Correlation with a changed component is insufficient when another mechanism predicts the same observation.

Prefer the smallest experiment that makes predictions diverge. Reject explanations that merely restate the symptom. Preserve logs, checksums, commands, and negative results; do not patch before discrimination unless containing an incident.

Worked examples. Use the historical mechanism, not the headline:

Symptom	Mechanism that explained positives and negatives	Remaining boundary
Signed download failed despite a clip row	Derived fake key differed from persisted objectKey; commit 7307082 made persisted key authoritative.	Production S3 end-to-end proof remains separate.
First transient error looked terminal	Processor finalized failure before queue retry policy; 1737d8b moved terminal decision to exhaustion.	External side-effect idempotency still needs crash tests.
Renderer worked but was not cinematic	Renderability measured graph execution, not semantic highlight/edit quality.	No certified creative golden set or controlled ablation exists.
Workspace build passed, clean archive failed	Untracked runtime/host fallback affected local-asset tests.	Hermetic fake/runtime contract is still open.
Highlight QA passed duration/mastering checks	Some checks are constants or command-presence assertions rather than output measurements.	Probe-derived gates must be added through change control.

Adversarial refutation. Before accepting a mechanism, assign a reviewer to construct the strongest counterexample and a test where the mechanism predicts no effect. If it cannot explain that negative, retain it as a candidate only.

Promotion Checklist

• The proof record was written before execution.
• Inputs, commit, configuration, binaries, models, assets, licenses, and checksums are recorded.
• Commands ran offline and did not bootstrap, download, render without approval, mutate production, or use external AI.
• Structural, semantic, security, and operational claims are separated.
• Positive, negative, boundary, and failure controls passed.
• Ranking work reports denominators, category strata, matching policy, uncertainty, and ablations.
• Media work reports probe-derived duration, streams, loudness, true peak, silence, and human-review evidence where semantic judgment is required.
• One mechanism explains all observations, including negatives; an adversarial reviewer tried to falsify it.
• Unproven conclusions remain labeled OPEN or CANDIDATE.
• Any behavior/default/dependency/model/asset/render/production change proceeds through video-editing-change-control and the validation sibling.

Provenance and maintenance

Sources of record: current Java/Python implementation and tests; application.yml/application.properties; benchmark/runbook documents; Git commits 66e998e, 7307082, 1737d8b, 5d889b0, 5006dfd, bb23ac8, and 9b56e89; and the clean-checkout investigation recorded in video-editing-failure-archaeology.

Re-verify volatile facts before each use:

git rev-parse HEAD
rg -n 'loudness-target-i|loudness-true-peak|loudness-range|strict-runtime|fallback-to-heuristic|max-attempts|visibility-timeout|preserve-input-quality' src/main/resources
rg -n 'duration_matches_timeline|audio_mastering_applied|write_silence|write_fallback_tone|fallbackTone|ATOMIC_MOVE|writeValue\(' src/main tools
rg -n 'precision|recall|NDCG|ground.truth|golden|Execution evidence pending' src/test docs
git show --stat 66e998e 7307082 1737d8b 5d889b0 5006dfd bb23ac8 9b56e89