feat(producer): write public render provenance sidecar next to outputs - #3

What

Every successful render now writes a portable JSON receipt next to the output artifact: out.mp4 gets out.mp4.hf-render.json. The sidecar records tool versions (producer / node / ffmpeg), the entry HTML sha256, the compiled-composition hash, @font-face families, a variables hash (count + sha256 of canonical JSON — never the raw values), format / exact-rational fps / resolution / duration / total frames, encoder facts (codec, preset, pixel format), the committed artifact's sha256 + size, per-stage wall-clock timings, worker count, HDR flag, outcome, and capture-readiness warning codes.

• Default ON. --no-provenance (or --provenance false) disables; --provenance <path> relocates the sidecar.
• Batch mode: each row writes its own <row output>.hf-render.json (verified: distinct variables hashes per row). A fixed custom path with --batch is rejected up front.
• Docker mode: the disable flag is forwarded into the container; the default sidecar lands next to the output in the mounted output directory. A custom host path with --docker is rejected up front (not container-visible).
• JSON Schema published at packages/core/schemas/hf-render-sidecar.json ($id https://hyperframes.heygen.com/schema/hf-render-sidecar.json); every emitted sidecar in testing validates against it (ajv, draft 2020-12).
• Docs: docs/reference/render-provenance.mdx, registered under the "Rendering paths" nav group.

Why

Agents and CI need a machine-readable receipt beside the MP4 answering "what rendered this, from what inputs, and how" without re-running anything — reproducibility checks, cache keys, and support triage all want it. Today the closest thing (runtimeEnvSnapshot, perfSummary) is internal-only, and the engine's embedded container tags carry only renderer name + version. The sidecar complements those tags: full receipt, separate file, deliberately excluding secrets (variable values are hashed, no env dump, no host paths/usernames).

How

• packages/producer/src/services/render/provenanceSidecar.ts — sidecar builder + emitter. Wired into renderOrchestrator.ts immediately after artifactTransaction.commit() (the actual commit site; there is no stages/commitArtifact.ts in the codebase). A sidecar write failure logs a warning and never un-completes a render whose artifact already committed.
• Reuses existing producer facts at the commit site: the compiled HTML (fonts scan), the observability composition hash, the encoder preset, perfStages, workerCount, and job warnings. Producer version prefers the bundler-injected __PRODUCER_VERSION__ define (the CLI inlines the producer via noExternal, where the package-walking reader can't resolve) with the filesystem walker as the unbundled fallback; ffmpeg version is probed once via the engine's binary resolution (honors HYPERFRAMES_FFMPEG_PATH) and cached.
• Threading: --provenance flag → render plan (parseProvenanceArg, tri-state) → RenderOptions → createRenderRequest (validated: false or non-empty string) → RenderConfig.provenance → orchestrator. dockerRunArgs forwards --no-provenance.
• png-sequence directory outputs skip artifact sha256/size; encoder is null for png-sequence/gif.

Test plan

• Unit tests added/updated — provenanceSidecar.test.ts (19 tests: path resolution incl. directory outputs, font extraction, canonical variables hashing, receipt shape, secrets-not-embedded, emit integration incl. write-failure and unreadable-entry tolerance) and render.provenance.test.ts (12 tests: flag parsing, plan threading, batch/docker conflicts, docker arg forwarding). Full CLI suite: 3021 passed. Producer unit lane: green except audioPadTrim.integration.test.ts, which fails identically on unmodified main in this environment (host-ffmpeg loudness variance — pre-existing, unrelated).
• Manual testing performed — real end-to-end renders with the branch CLI: single render (sidecar written, output.sha256 matches sha256sum of the MP4), --no-provenance (no sidecar), --provenance <path> (relocated), --batch with 2 rows (one sidecar per row, distinct variables hashes), sidecars validated against the JSON Schema with ajv. bun run build, tsc --noEmit (producer + cli), oxlint/oxfmt, and the full lefthook pre-commit suite (incl. the fallow gate) all pass.
• Documentation updated (if applicable) — docs/reference/render-provenance.mdx + docs/docs.json.

Walkthrough (rendered by HyperFrames itself)

The demo was storyboarded first (script, beat sheet, and seam vector ledger — included on the assets branch as render-provenance-ce-plan.md), built as a HyperFrames composition (source) that passed hyperframes lint and hyperframes check (0 errors, WCAG AA contrast), and rendered with the CLI built from this branch:

node packages/cli/bin/hyperframes.mjs render /tmp/provenance-walkthrough --output walkthrough.mp4 --fps 30

render-provenance-walkthrough.mp4

Public copy: render-provenance-walkthrough.mp4

Self-proof: that render exercised this PR's feature on itself. Its own receipt, render-provenance-walkthrough.mp4.hf-render.json, records

"sha256": "6af87ebf6a630a417e64db98c6d6e05f50f3fa99dcc5063e3757ae3d4e8b8de1"

which is exactly sha256sum of the published MP4 above (verified after download from the public URL).

AI disclosure

This PR — feature code, tests, schema, docs, the walkthrough storyboard, composition, and render — was authored end-to-end by an AI agent (Claude Fable 5, running as a Cursor Cloud Agent), with all repository gates (build, typecheck, lint/format, lefthook, targeted test suites) executed and passing before submission.

_{To show artifacts inline, enable in settings.}