@event4u/agent-config 5.10.0 → 6.0.0

package/src/scripts/ai-video/lib/audio-adapter-contract.md

@@ -0,0 +1,210 @@
+# Audio Adapter Contract (v1)
+
+> Single source of truth for every adapter under
+> `scripts/ai-video/audio-adapters/`. Sibling of the video/image
+> [`adapter-contract.md`](adapter-contract.md) (v2) — deliberately a
+> **separate contract**, not a `kind` extension of v2: audio analysis is
+> a synchronous filter (stdin path → stdout JSON), while v2 is an async
+> render queue (submit/poll/fetch). Mixing the two shapes in one
+> contract was rejected by AI-council design review (claude-sonnet-4-5 +
+> gpt-4o, 2026-06-07): a filter forced through submit/poll/fetch
+> triples the orchestrator's error states for no benefit. **Lip-sync is
+> NOT covered here** — it is an async hosted render job and ships as a
+> regular v2 adapter under `scripts/ai-video/adapters/` (see
+> [`model-capabilities/syncso.json`](model-capabilities/syncso.json)).
+
+## Scope
+
+Two adapter classes, one executable shell entry each under
+`scripts/ai-video/audio-adapters/<id>.sh`:
+
+| Class | Input | Output (stdout JSON) |
+|---|---|---|
+| `audio-analysis` | song file | `{bpm, beats, downbeats, sections}` |
+| `lyrics` | vocal stem / song file | word-level timestamps + per-line speaker |
+
+The orchestrator (`/video:from-song`) never bundles or imports ML
+dependencies — an adapter either wraps an **operator-installed local
+CLI** (allin1, whisperx) or calls a **hosted API**. The suite ships the
+wrapper, never the model ("skill suite, not an app" — council
+2026-06-06).
+
+## Subcommands
+
+Every audio adapter implements three:
+
+| Subcommand | Purpose | I/O |
+|---|---|---|
+| `analyze` | Run the analysis | stdin JSON · stdout result JSON |
+| `capability` | Declare class + provided fields | stdout JSON |
+| `dry-run` | Deterministic fixture, no network/exec | stdout same shape as `analyze` |
+
+`analyze` is **synchronous** — it blocks until the result is ready.
+Hosted backends poll internally. **Async threshold (council 2026-06-07):
+if a backend's p95 runtime exceeds ~50% of the orchestrator step
+timeout (`AIV_AUDIO_TIMEOUT`, default 600 s), the adapter must move to
+the v2 async triple instead — do not stretch this contract.**
+
+## Stdin JSON (consumed by `analyze`)
+
+```json
+{
+  "audio_path": "/abs/path/song.wav",
+  "stem": "vocals",
+  "language": "en"
+}
+```
+
+- `audio_path` — mandatory; absolute path to a readable audio file.
+  Validated before any exec: must exist, must contain an audio stream.
+- `stem` — optional hint (`vocals` | `mix`); adapters that separate
+  stems internally (allin1) may ignore it.
+- `language` — optional ISO hint for lyrics adapters.
+- Unknown top-level keys are logged to stderr and ignored (v2 rule).
+
+## Stdout JSON — `audio-analysis` class
+
+```json
+{
+  "schema": 1,
+  "source": "allin1",
+  "bpm": 120.0,
+  "beats": [0.52, 1.02, 1.52],
+  "downbeats": [0.52, 2.52],
+  "sections": [
+    {"start": 0.0, "end": 12.5, "label": "intro", "energy": 0.41}
+  ]
+}
+```
+
+- `bpm` — number; `beats` / `downbeats` — ascending seconds.
+- `sections[].label` — canonical set `intro | verse | chorus | bridge |
+  inst | outro | start | end` plus the probe's `build | drop |
+  breakdown`; free-form labels are allowed but consumers only act on
+  the canonical set.
+- `sections[].energy` — optional 0..1; present keeps the shape a strict
+  superset of `probe-audio.sh` output so consumers need one code path.
+- `source` — the backing tool/API id; consumers surface it in reports.
+
+## Stdout JSON — `lyrics` class
+
+```json
+{
+  "schema": 1,
+  "source": "whisperx",
+  "language": "en",
+  "lines": [
+    {"start": 1.20, "end": 3.40, "text": "hello world",
+     "speaker": "SPEAKER_00"}
+  ],
+  "words": [
+    {"start": 1.20, "end": 1.45, "word": "hello", "speaker": "SPEAKER_00"}
+  ]
+}
+```
+
+- `lines[].speaker` — the **raw diarization label** (`SPEAKER_00`, …),
+  or `"?"` when diarization is unavailable or a line mixes speakers.
+  The adapter NEVER invents a name. Mapping labels → cast names is the
+  `song-to-script` skill's job (operator roster); unmatched stays `"?"`
+  per [`media-sync-ground-truth`](../../../rules/media-sync-ground-truth.md).
+- `words` — optional; present when the backend aligns word-level.
+- Timing is **verbatim transcript output** — consumers must not re-time
+  lines. `scripts/ai-video/lib/validate-vocal-map.sh` enforces this
+  downstream (every vocal-map entry must match a transcript line).
+
+## `capability` output
+
+```json
+{"kind": "audio-analysis", "provides": ["bpm", "beats", "downbeats", "sections"], "backend": "local-cli"}
+```
+
+`kind` ∈ `audio-analysis | lyrics`. `backend` ∈ `local-cli | hosted`.
+
+## Configuration — `agents/.ai-video.xml`
+
+Audio adapters reuse the existing provider registry (council Q3 —
+the feature boundary is AI video, not audio vs video):
+
+```xml
+<provider id="allin1" kind="audio-analysis">
+  <lifecycle>experimental</lifecycle>
+  <enabled>true</enabled>
+  <dry-run>true</dry-run>
+</provider>
+```
+
+- Local-CLI adapters need no `<api-key>`; hosted ones use the same
+  `<api-key>` / `<endpoint>` elements as v2 providers.
+- The `<enabled>false</enabled>` kill-switch refuses `analyze` exactly
+  like v2 refuses `submit` (exit 6).
+- Every provider block carries a `<lifecycle>` tag per
+  `provider-lifecycle-discipline`; every adapter carries the matching
+  `Lifecycle:` header comment.
+
+## Fallback semantics — `probe-audio.sh` (council Q4, option c)
+
+`probe-audio.sh` (zero-dependency energy/silence segmentation) remains
+the floor; the audio-analysis adapter is the upgrade path, **never a
+hard requirement**. The orchestrator resolves in this order:
+
+1. **No audio-analysis provider configured** (no block in the XML, or
+   adapter script absent) → run `probe-audio.sh`. Normal path, no
+   warning beyond the existing probe `method` report line.
+2. **Provider configured + healthy** → `analyze` result drives timing;
+   the report names the `source`.
+3. **Provider configured + transient failure** (network timeout, HTTP
+   5xx/429 — exit 75) → retry once, then fall back to `probe-audio.sh`
+   with ONE warning line in the report (not per-call log flood).
+4. **Provider configured + config failure** (missing key, missing local
+   CLI, HTTP 401/403, malformed output — exits 3/6/7) → **hard-fail**
+   with an actionable message ("install X / fix key / set
+   `<enabled>false</enabled>` to opt out"). A configured adapter that
+   silently degrades hides config errors from the operator.
+
+## Exit codes (aligned with v2)
+
+| Code | Meaning |
+|---|---|
+| 0 | result JSON on stdout |
+| 2 | usage error / unknown subcommand (fail-closed dispatch) |
+| 3 | required tool / fixture missing |
+| 4 | live call refused under `AIV_DRYRUN=true` (hosted backends) |
+| 6 | provider disabled or key missing |
+| 7 | invalid input (bad `audio_path`, malformed stdin) |
+| 10 | trust-boundary violation |
+| 75 | transient backend failure (caller may retry / fall back) |
+
+`AIV_DRYRUN=true` (the default) refuses **hosted** `analyze` calls with
+exit 4. Local-CLI execution has no spend and MAY run under dry-run
+default, but MUST exit 3 with the install hint when the CLI is absent.
+
+## Trust boundary
+
+Identical to v2 — explicit here because council review flagged the gap:
+
+- Any URL returned by a hosted backend is fetched via `aiv_fetch_url`
+  (size cap + timeout), never raw curl.
+- Any file path emitted in the result JSON is validated via
+  `aiv_validate_artifact_path` against the project root.
+- Keys never appear in argv; stderr is piped through
+  `aiv_redact_stream`.
+- Backend-returned text (lyrics) is data, never eval'd or interpolated
+  into shell.
+
+## Dry-run fixtures
+
+`scripts/ai-video/lib/fixtures/<adapter-id>/analysis.json` — same
+directory convention as v2 (`fixtures/<id>/result.json`). The fixture
+is the contract-shaped output for a deterministic reference track;
+tests pin its shape. CI never needs ffmpeg, allin1, whisperx, or a key.
+
+## See also
+
+- [`adapter-contract.md`](adapter-contract.md) — v2 render contract
+  (lip-sync adapters live there).
+- [`probe-audio.sh`](probe-audio.sh) — the zero-dependency fallback.
+- [`validate-vocal-map.sh`](validate-vocal-map.sh) — downstream
+  ground-truth enforcement for lyric timing.
+- [`../../skills/song-to-script/SKILL.md`](../../skills/song-to-script/SKILL.md)
+  — the consumer.

package/src/scripts/ai-video/lib/comfyui-nodes.allowlist.json

@@ -0,0 +1,21 @@
+{
+  "schema": 1,
+  "comment": "ADR-060 §2 — pinned custom-node allowlist for the comfyui adapter. A workflow referencing a class_type outside core_class_types AND outside a pinned custom_nodes entry is HARD-REFUSED (exit 7, named node). There is no bypass flag by design. Every custom_nodes entry pins repo + git commit SHA and carries risk_tier (high = monthly audit, low = quarterly). Kill-switch: >2 CVSS>=7 CVEs in 90 days removes the entry and deprecates dependent templates.",
+  "core_class_types": [
+    "CLIPLoader",
+    "CLIPTextEncode",
+    "CreateVideo",
+    "EmptyLTXVLatentVideo",
+    "KSampler",
+    "LTXVConditioning",
+    "LTXVScheduler",
+    "LoadImage",
+    "SamplerCustom",
+    "SaveVideo",
+    "UNETLoader",
+    "VAEDecode",
+    "VAELoader",
+    "Wan22ImageToVideoLatent"
+  ],
+  "custom_nodes": []
+}

package/src/scripts/ai-video/lib/comfyui-templates/ltx-2.json

@@ -0,0 +1,79 @@
+{
+  "_meta": {
+    "schema": 1,
+    "model": "ltx-2",
+    "verified": false,
+    "fps": 25,
+    "comment": "Package-shipped LTX-2 workflow template (ADR-060 §3). Graph is documented-best-effort from the public ComfyUI LTX-Video example layout — re-export from a live ComfyUI and re-pin BEFORE the first live render. Same substitution-slot rules as wan22-ti2v-5b.json; LoadImage node (id 90) removed when no ref image is supplied. audio_sync per model manifest — the saved container is expected to embed the generated audio track.",
+    "aspect_map": {
+      "16:9": { "width": 1216, "height": 704 },
+      "9:16": { "width": 704, "height": 1216 },
+      "1:1": { "width": 960, "height": 960 }
+    }
+  },
+  "prompt": {
+    "37": {
+      "class_type": "UNETLoader",
+      "inputs": { "unet_name": "ltx-2.safetensors", "weight_dtype": "default" }
+    },
+    "38": {
+      "class_type": "CLIPLoader",
+      "inputs": { "clip_name": "t5xxl_fp16.safetensors", "type": "ltxv", "device": "default" }
+    },
+    "39": {
+      "class_type": "VAELoader",
+      "inputs": { "vae_name": "ltx-2_vae.safetensors" }
+    },
+    "6": {
+      "class_type": "CLIPTextEncode",
+      "inputs": { "text": "{{PROMPT}}", "clip": ["38", 0] }
+    },
+    "7": {
+      "class_type": "CLIPTextEncode",
+      "inputs": { "text": "{{NEGATIVE}}", "clip": ["38", 0] }
+    },
+    "90": {
+      "class_type": "LoadImage",
+      "inputs": { "image": "{{REF_IMAGE}}" }
+    },
+    "69": {
+      "class_type": "LTXVConditioning",
+      "inputs": { "frame_rate": 25, "positive": ["6", 0], "negative": ["7", 0] }
+    },
+    "70": {
+      "class_type": "EmptyLTXVLatentVideo",
+      "inputs": { "width": "{{WIDTH}}", "height": "{{HEIGHT}}", "length": "{{FRAMES}}", "batch_size": 1 }
+    },
+    "71": {
+      "class_type": "LTXVScheduler",
+      "inputs": { "steps": 30, "max_shift": 2.05, "base_shift": 0.95, "stretch": true, "terminal": 0.1, "latent": ["70", 0] }
+    },
+    "3": {
+      "class_type": "KSampler",
+      "inputs": {
+        "seed": "{{SEED}}",
+        "steps": 30,
+        "cfg": 3,
+        "sampler_name": "euler",
+        "scheduler": "simple",
+        "denoise": 1,
+        "model": ["37", 0],
+        "positive": ["69", 0],
+        "negative": ["69", 1],
+        "latent_image": ["70", 0]
+      }
+    },
+    "8": {
+      "class_type": "VAEDecode",
+      "inputs": { "samples": ["3", 0], "vae": ["39", 0] }
+    },
+    "57": {
+      "class_type": "CreateVideo",
+      "inputs": { "fps": 25, "images": ["8", 0] }
+    },
+    "58": {
+      "class_type": "SaveVideo",
+      "inputs": { "filename_prefix": "video/aiv", "format": "mp4", "codec": "h264", "video": ["57", 0] }
+    }
+  }
+}

package/src/scripts/ai-video/lib/comfyui-templates/wan22-ti2v-5b.json

@@ -0,0 +1,78 @@
+{
+  "_meta": {
+    "schema": 1,
+    "model": "wan22-ti2v-5b",
+    "verified": false,
+    "fps": 24,
+    "comment": "Package-shipped Wan2.2 TI2V-5B workflow template (ADR-060 §3 — operator workflows are rejected; this is the only executable shape for the model). Graph is documented-best-effort, captured from the public ComfyUI Wan2.2 example layout — re-export from a live ComfyUI and re-pin BEFORE the first live render (the adapter ships dry-run-first). Substitution slots ({{PROMPT}}, {{NEGATIVE}}, {{SEED}}, {{WIDTH}}, {{HEIGHT}}, {{FRAMES}}, {{REF_IMAGE}}) are filled via jq --arg (JSON-safe, never string-spliced); numeric slots are charset-validated upstream. The LoadImage node (id 90) is REMOVED by the adapter when no ref image is supplied.",
+    "aspect_map": {
+      "16:9": { "width": 1280, "height": 704 },
+      "9:16": { "width": 704, "height": 1280 },
+      "1:1": { "width": 960, "height": 960 }
+    }
+  },
+  "prompt": {
+    "37": {
+      "class_type": "UNETLoader",
+      "inputs": { "unet_name": "wan2.2_ti2v_5B_fp16.safetensors", "weight_dtype": "default" }
+    },
+    "38": {
+      "class_type": "CLIPLoader",
+      "inputs": { "clip_name": "umt5_xxl_fp8_e4m3fn_scaled.safetensors", "type": "wan", "device": "default" }
+    },
+    "39": {
+      "class_type": "VAELoader",
+      "inputs": { "vae_name": "wan2.2_vae.safetensors" }
+    },
+    "6": {
+      "class_type": "CLIPTextEncode",
+      "inputs": { "text": "{{PROMPT}}", "clip": ["38", 0] }
+    },
+    "7": {
+      "class_type": "CLIPTextEncode",
+      "inputs": { "text": "{{NEGATIVE}}", "clip": ["38", 0] }
+    },
+    "90": {
+      "class_type": "LoadImage",
+      "inputs": { "image": "{{REF_IMAGE}}" }
+    },
+    "55": {
+      "class_type": "Wan22ImageToVideoLatent",
+      "inputs": {
+        "width": "{{WIDTH}}",
+        "height": "{{HEIGHT}}",
+        "length": "{{FRAMES}}",
+        "batch_size": 1,
+        "vae": ["39", 0],
+        "start_image": ["90", 0]
+      }
+    },
+    "3": {
+      "class_type": "KSampler",
+      "inputs": {
+        "seed": "{{SEED}}",
+        "steps": 20,
+        "cfg": 5,
+        "sampler_name": "uni_pc",
+        "scheduler": "simple",
+        "denoise": 1,
+        "model": ["37", 0],
+        "positive": ["6", 0],
+        "negative": ["7", 0],
+        "latent_image": ["55", 0]
+      }
+    },
+    "8": {
+      "class_type": "VAEDecode",
+      "inputs": { "samples": ["3", 0], "vae": ["39", 0] }
+    },
+    "57": {
+      "class_type": "CreateVideo",
+      "inputs": { "fps": 24, "images": ["8", 0] }
+    },
+    "58": {
+      "class_type": "SaveVideo",
+      "inputs": { "filename_prefix": "video/aiv", "format": "mp4", "codec": "h264", "video": ["57", 0] }
+    }
+  }
+}

package/src/scripts/ai-video/lib/embed-provenance.sh

@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+# embed-provenance.sh — machine-readable provenance for AI-generated
+# artifacts, enforcing agents/settings/policies/media/transparency.md in
+# code instead of prose.
+#
+# Layered surface (best tool available, sidecar always):
+#   1. Sidecar `<artifact>.provenance.json` — ALWAYS written. The
+#      zero-dependency floor the policy names for providers without
+#      native C2PA support.
+#   2. Container metadata tag — when ffmpeg is installed and the
+#      artifact is an mp4/mov/m4v: a human-readable AI-generation
+#      disclosure comment is embedded into the container (stream copy,
+#      no re-encode), satisfying the non-removable disclosure step of
+#      /video:from-song Step 9.4 (disclosure.md).
+#   3. C2PA manifest — when the OPERATOR has installed `c2patool`
+#      (https://github.com/contentauth/c2pa-rs) and signing is
+#      configured (C2PATOOL_SIGN_ARGS), a real C2PA manifest is
+#      embedded. The suite ships only this wrapper, never the signing
+#      keys ("skill suite, not an app"). Missing tool → sidecar-only,
+#      reported, never an error.
+#
+# This script only ADDS provenance. It has no strip/remove path by
+# design — transparency.md forbids stripping or forging; refusal is the
+# agent's job, absence of the capability is this script's contribution.
+#
+# Usage:
+#   echo '{"artifact_path":"/abs/final.mp4","provider":"gemini-veo",
+#          "model":"veo-3.0","prompt_sha256":"<hex>",
+#          "assertion":"ai_generated"}' \
+#     | scripts/ai-video/lib/embed-provenance.sh embed
+#
+# Stdin JSON (embed):
+#   artifact_path  mandatory — absolute path to the artifact (mp4/mov/
+#                  m4v/png/jpg/wav). Validated against AIV_PROJECT_DIR
+#                  when set (trust boundary), else against its parent.
+#   provider       mandatory — adapter id that produced the artifact.
+#   model          mandatory — model identifier (e.g. veo-3.0).
+#   assertion      optional — ai_generated (default) | ai_edited.
+#   prompt_sha256  optional — SHA-256 of the REDACTED prompt (the
+#                  caller hashes after lib/redact.sh; raw prompts never
+#                  enter the manifest).
+#   extra          optional object — additional non-conflicting fields
+#                  (transparency.md § Allowed), merged verbatim.
+#
+# Stdout JSON:
+#   {"provenance_path": "...", "container_tagged": true|false,
+#    "c2pa": "c2patool" | "sidecar-only", "assertion": "..."}
+#
+# Determinism for tests: AIV_PROVENANCE_NOW overrides the timestamp.
+#
+# Exit codes (aligned with adapter-contract v2):
+#   2 usage · 3 required tool missing (jq) · 7 invalid input ·
+#   10 trust-boundary violation (path escapes scope).
+
+set -euo pipefail
+
+# shellcheck source=adapter-common.sh
+. "$(dirname "$0")/adapter-common.sh"
+
+PROV_SCHEMA=1
+PROV_GENERATOR="event4u/agent-config ai-video"
+
+_prov_now() {
+  if [ -n "${AIV_PROVENANCE_NOW:-}" ]; then
+    printf '%s' "${AIV_PROVENANCE_NOW}"
+  else
+    date -u +%Y-%m-%dT%H:%M:%SZ
+  fi
+}
+
+_prov_embed() {
+  aiv_require_cmd jq
+
+  local stdin_json artifact provider model assertion prompt_hash extra
+  stdin_json="$(cat)"
+  artifact="$(printf '%s' "${stdin_json}" | jq -r '.artifact_path // empty' 2>/dev/null)" \
+    || aiv_die 7 "embed-provenance: malformed stdin JSON"
+  provider="$(printf '%s' "${stdin_json}" | jq -r '.provider // empty')"
+  model="$(printf '%s' "${stdin_json}" | jq -r '.model // empty')"
+  assertion="$(printf '%s' "${stdin_json}" | jq -r '.assertion // "ai_generated"')"
+  prompt_hash="$(printf '%s' "${stdin_json}" | jq -r '.prompt_sha256 // empty')"
+  extra="$(printf '%s' "${stdin_json}" | jq -c '.extra // {}')"
+
+  [ -n "${artifact}" ] || aiv_die 7 "embed-provenance: artifact_path required"
+  [ -n "${provider}" ] || aiv_die 7 "embed-provenance: provider required"
+  [ -n "${model}" ]    || aiv_die 7 "embed-provenance: model required"
+  case "${assertion}" in
+    ai_generated|ai_edited) : ;;
+    *) aiv_die 7 "embed-provenance: assertion must be ai_generated|ai_edited (got: ${assertion})" ;;
+  esac
+  if [ -n "${prompt_hash}" ]; then
+    printf '%s' "${prompt_hash}" | grep -Eq '^[0-9a-f]{64}$' \
+      || aiv_die 7 "embed-provenance: prompt_sha256 must be a 64-char hex SHA-256 of the REDACTED prompt"
+  fi
+
+  # Trust boundary: the artifact path is orchestrator-supplied but the
+  # same project-scope rule applies — scope to AIV_PROJECT_DIR when the
+  # orchestrator set it, else to the artifact's own parent directory.
+  local scope_root
+  scope_root="${AIV_PROJECT_DIR:-$(dirname "${artifact}")}"
+  artifact="$(aiv_validate_artifact_path "${scope_root}" "${artifact}")"
+  [ -f "${artifact}" ] || aiv_die 7 "embed-provenance: artifact not found: ${artifact}"
+
+  local created sidecar
+  created="$(_prov_now)"
+  sidecar="${artifact}.provenance.json"
+
+  # 1. Sidecar — the always-on floor (transparency.md § Required).
+  jq -n \
+    --argjson schema "${PROV_SCHEMA}" \
+    --arg assertion "c2pa.${assertion}" \
+    --arg provider "${provider}" \
+    --arg model "${model}" \
+    --arg created "${created}" \
+    --arg prompt_sha256 "${prompt_hash}" \
+    --arg generator "${PROV_GENERATOR}" \
+    --argjson extra "${extra}" \
+    '{
+      schema: $schema,
+      assertion: $assertion,
+      provider: $provider,
+      model: $model,
+      created: $created,
+      generator: $generator
+    }
+    + (if $prompt_sha256 == "" then {} else {prompt_sha256: $prompt_sha256} end)
+    + $extra' > "${sidecar}" \
+    || aiv_die 7 "embed-provenance: failed to write sidecar ${sidecar}"
+
+  # 2. Container disclosure tag — mp4-family only, stream copy, written
+  #    to a temp file then atomically swapped so a failed ffmpeg never
+  #    corrupts the artifact.
+  local container_tagged=false tmp
+  case "${artifact}" in
+    *.mp4|*.mov|*.m4v)
+      if command -v ffmpeg >/dev/null 2>&1; then
+        tmp="${artifact}.provtag.tmp.${artifact##*.}"
+        if ffmpeg -loglevel error -y -i "${artifact}" -c copy \
+             -metadata comment="AI-generated content — ${model} via ${provider}; provenance sidecar: $(basename "${sidecar}")" \
+             -metadata ai_generated=true \
+             "${tmp}" >/dev/null 2>&1; then
+          mv "${tmp}" "${artifact}"
+          container_tagged=true
+        else
+          rm -f "${tmp}"
+          printf 'embed-provenance: ffmpeg metadata tag failed — sidecar remains the provenance surface\n' >&2
+        fi
+      else
+        printf 'embed-provenance: ffmpeg not installed — container tag skipped, sidecar written\n' >&2
+      fi
+      ;;
+  esac
+
+  # 3. C2PA manifest — operator-installed c2patool, best-effort. The
+  #    manifest mirrors the sidecar fields; signing args (cert/key) are
+  #    the operator's (C2PATOOL_SIGN_ARGS) — the suite never ships keys.
+  local c2pa_surface="sidecar-only" manifest out
+  if command -v c2patool >/dev/null 2>&1; then
+    manifest="$(mktemp -t aiv-c2pa-XXXXXX.json)"
+    jq '{
+      claim_generator: .generator,
+      assertions: [
+        {label: "c2pa.actions", data: {actions: [{action: "c2pa.created",
+          digitalSourceType: "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia"}]}},
+        {label: "ai.provenance", data: (del(.schema))}
+      ]
+    }' "${sidecar}" > "${manifest}"
+    out="${artifact}.c2pa.tmp.${artifact##*.}"
+    # Operator-supplied signing args are intentionally word-split.
+    # shellcheck disable=SC2086
+    if c2patool "${artifact}" -m "${manifest}" -o "${out}" ${C2PATOOL_SIGN_ARGS:-} >/dev/null 2>&1; then
+      mv "${out}" "${artifact}"
+      c2pa_surface="c2patool"
+    else
+      rm -f "${out}"
+      printf 'embed-provenance: c2patool embed failed (signing unconfigured?) — sidecar remains the provenance surface\n' >&2
+    fi
+    rm -f "${manifest}"
+  fi
+
+  jq -n \
+    --arg p "${sidecar}" \
+    --argjson tagged "${container_tagged}" \
+    --arg c2pa "${c2pa_surface}" \
+    --arg assertion "c2pa.${assertion}" \
+    '{provenance_path: $p, container_tagged: $tagged, c2pa: $c2pa, assertion: $assertion}'
+}
+
+sub="${1:-}"
+case "${sub}" in
+  embed) shift; _prov_embed "$@" ;;
+  "")    aiv_die 2 "embed-provenance: subcommand required (embed)" ;;
+  *)     aiv_die 2 "embed-provenance: unknown subcommand: ${sub}" ;;
+esac

package/src/scripts/ai-video/lib/fixtures/allin1/analysis.json

@@ -0,0 +1,13 @@
+{
+  "schema": 1,
+  "source": "allin1",
+  "bpm": 120.0,
+  "beats": [0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0, 5.5, 6.0, 6.5, 7.0, 7.5, 8.0],
+  "downbeats": [0.5, 2.5, 4.5, 6.5],
+  "sections": [
+    {"start": 0.0, "end": 8.0, "label": "intro", "energy": 0.35},
+    {"start": 8.0, "end": 24.0, "label": "verse", "energy": 0.55},
+    {"start": 24.0, "end": 40.0, "label": "chorus", "energy": 0.85},
+    {"start": 40.0, "end": 48.0, "label": "outro", "energy": 0.30}
+  ]
+}

package/src/scripts/ai-video/lib/fixtures/comfyui/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/comfyui/scene-0001.mp4","audio_embedded":false,"cost_estimate":0.0}

package/src/scripts/ai-video/lib/fixtures/fal/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/fal/scene-0001.mp4","audio_embedded":false,"cost_estimate":0.4}

package/src/scripts/ai-video/lib/fixtures/fal/scene-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-fal-mp4

package/src/scripts/ai-video/lib/fixtures/gemini-veo/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/gemini-veo/scene-0001.mp4","audio_embedded":true,"cost_estimate":0.5}

package/src/scripts/ai-video/lib/fixtures/higgsfield/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/higgsfield/scene-0001.mp4","audio_embedded":false,"cost_estimate":0.1}

package/src/scripts/ai-video/lib/fixtures/kling/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/kling/scene-0001.mp4","audio_embedded":false,"cost_estimate":0.14}

package/src/scripts/ai-video/lib/fixtures/kling/scene-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-kling-mp4

package/src/scripts/ai-video/lib/fixtures/musetalk/lipsync-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-fal-mp4

package/src/scripts/ai-video/lib/fixtures/musetalk/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/musetalk/lipsync-0001.mp4","audio_embedded":true,"cost_estimate":0.0}

package/src/scripts/ai-video/lib/fixtures/openai-images/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/openai-images/scene-0001.png","audio_embedded":false,"cost_estimate":0.04}

package/src/scripts/ai-video/lib/fixtures/replicate/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/replicate/scene-0001.mp4","audio_embedded":false,"cost_estimate":0.35}

package/src/scripts/ai-video/lib/fixtures/replicate/scene-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-replicate-mp4

package/src/scripts/ai-video/lib/fixtures/sora/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/sora/scene-0001.mp4","audio_embedded":true,"cost_estimate":0.5}

package/src/scripts/ai-video/lib/fixtures/syncso/lipsync-0001.mp4

@@ -0,0 +1 @@
+FIXTURE-fal-mp4

package/src/scripts/ai-video/lib/fixtures/syncso/result.json

@@ -0,0 +1 @@
+{"video_path":"src/scripts/ai-video/lib/fixtures/syncso/lipsync-0001.mp4","audio_embedded":true,"cost_estimate":0.5}