@event4u/agent-config 6.1.0 → 7.0.1

package/src/scripts/measure_skill_reduction.ts

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+/**
+ * Skill-count reduction measurement — step-12 Phase 3 L74 deliverable.
+ *
+ * TypeScript twin of `src/scripts/measure_skill_reduction.py` (ADR-200 —
+ * Python→TS migration, Phase 8 / Wave 8c). Mirrors the CLI contract EXACTLY:
+ * flag (`--json`), exit codes (0 pass / 1 fail / 2 no-skills), byte-identical
+ * stdout (report or `json.dumps(indent=2)`) and stderr. No behaviour changes.
+ *
+ * Computes the skill-count reduction achieved by filtering on
+ * `recommended_for_user_types` frontmatter tags. Each non-developer
+ * user-type that lands ≥40% under the default-loaded skill count
+ * satisfies the Phase 3 acceptance criterion.
+ *
+ * The runtime filter (loaded vs. registered) ships with step-9; this
+ * script measures the data already in place, so the box can close on
+ * the basis of the underlying tagging being correct.
+ *
+ * Usage:
+ *     measure_skill_reduction
+ *     measure_skill_reduction --json
+ *
+ * NOTE: the .py references the legacy `.agent-src.uncondensed/skills`
+ * literal; this faithful twin replicates it byte-for-byte. When the
+ * directory is absent the .py raises an uncaught FileNotFoundError
+ * (iterdir on a missing dir) → exit 1, empty stdout; this twin mirrors
+ * that by throwing, so the dispatcher / Node surfaces a non-zero exit.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+const _HERE = fileURLToPath(import.meta.url);
+// src/scripts/measure_skill_reduction.ts → parents[2] is the repo root.
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const SKILLS_DIR = path.join(REPO_ROOT, '.agent-src.uncondensed', 'skills');
+const TARGET_REDUCTION = 0.4;
+const PHASE_3_USER_TYPES = ['consultant', 'creator'] as const;
+
+interface UserTypeEntry {
+    loaded_skills: number;
+    reduction_pct: PyFloat;
+    passes_target: boolean;
+}
+
+interface Report {
+    total_skills: number;
+    target_reduction: PyFloat;
+    per_user_type: Record<string, UserTypeEntry>;
+    phase_3_user_types: string[];
+    phase_3_passed: boolean;
+}
+
+/**
+ * Mirror python sorted(SKILLS_DIR.iterdir()): a FileNotFoundError when the
+ * directory is missing (matching pathlib.iterdir on a non-existent dir).
+ */
+function _iterdirSorted(dir: string): string[] {
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch (e) {
+        const err = e as NodeJS.ErrnoException;
+        if (err.code === 'ENOENT') {
+            throw new Error(
+                `FileNotFoundError: [Errno 2] No such file or directory: '${dir}'`,
+            );
+        }
+        throw e;
+    }
+    // sorted() over Path objects compares the full path string component-wise;
+    // here every entry shares the same parent, so a code-point sort of the
+    // basenames is equivalent.
+    return names.sort(_pyStrCmp).map((n) => path.join(dir, n));
+}
+
+function load_tags(): [number, Record<string, number>] {
+    let total = 0;
+    const per_type: Record<string, number> = {};
+    for (const skill_dir of _iterdirSorted(SKILLS_DIR)) {
+        const skill_md = path.join(skill_dir, 'SKILL.md');
+        if (!_isFile(skill_md)) {
+            continue;
+        }
+        const text = fs.readFileSync(skill_md, 'utf-8');
+        if (!text.startsWith('---')) {
+            continue;
+        }
+        let fm: Record<string, unknown>;
+        try {
+            fm = (_yamlSafeLoad(_splitParts(text, '---', 2)[1] ?? '') as Record<string, unknown>) || {};
+        } catch {
+            // yaml.YAMLError → skip this skill.
+            continue;
+        }
+        if (fm === null || fm === undefined) {
+            fm = {};
+        }
+        total += 1;
+        const tags = fm['recommended_for_user_types'];
+        const list = Array.isArray(tags) ? tags : _pyTruthy(tags) ? tags : [];
+        if (Array.isArray(list)) {
+            for (const t of list) {
+                const key = String(t);
+                per_type[key] = (per_type[key] ?? 0) + 1;
+            }
+        }
+    }
+    return [total, per_type];
+}
+
+export function main(argv: string[] | null = null): number {
+    const rawArgv = argv ?? process.argv.slice(2);
+    const args = parse_args(rawArgv);
+
+    const [total, per_type] = load_tags();
+    if (total === 0) {
+        process.stderr.write('error: no skills found\n');
+        return 2;
+    }
+
+    const report: Report = {
+        total_skills: total,
+        target_reduction: new PyFloat(TARGET_REDUCTION),
+        per_user_type: {},
+        phase_3_user_types: [...PHASE_3_USER_TYPES],
+        phase_3_passed: true,
+    };
+    for (const ut of Object.keys(per_type).sort(_pyStrCmp)) {
+        const loaded = per_type[ut]!;
+        const reduction = 1 - loaded / total;
+        report.per_user_type[ut] = {
+            loaded_skills: loaded,
+            reduction_pct: new PyFloat(_pyRound(reduction, 4)),
+            passes_target: reduction >= TARGET_REDUCTION,
+        };
+    }
+    for (const ut of PHASE_3_USER_TYPES) {
+        const entry = report.per_user_type[ut];
+        if (!entry || !entry.passes_target) {
+            report.phase_3_passed = false;
+        }
+    }
+
+    if (args.json) {
+        process.stdout.write(_jsonDumpsIndent2(_reportToJson(report)) + '\n');
+    } else {
+        // f"≥{TARGET_REDUCTION:.0%}" → 40%.
+        process.stdout.write(
+            `total_skills: ${total}  target_reduction: ≥${_fmtPct0(TARGET_REDUCTION)}\n`,
+        );
+        // Insertion order of report.per_user_type mirrors the .py dict (sorted keys).
+        for (const [ut, e] of Object.entries(report.per_user_type)) {
+            const mark = e.passes_target ? '✓' : '✗';
+            const star = (PHASE_3_USER_TYPES as readonly string[]).includes(ut) ? ' *' : '';
+            process.stdout.write(
+                `  ${mark} ${_ljust(ut, 12)} loaded=${_rjust(String(e.loaded_skills), 3)} ` +
+                    `reduction=${_fmtPct1(e.reduction_pct.value)}${star}\n`,
+            );
+        }
+        process.stdout.write(`verdict: ${report.phase_3_passed ? 'PASS' : 'FAIL'}\n`);
+        process.stdout.write('(* = step-12 Phase 3 L74 anchor user-types)\n');
+    }
+    return report.phase_3_passed ? 0 : 1;
+}
+
+interface Args {
+    json: boolean;
+}
+
+function parse_args(argv: string[]): Args {
+    const args: Args = { json: false };
+    for (const a of argv) {
+        if (a === '--json') {
+            args.json = true;
+        } else {
+            // argparse error prose is Python-version-dependent; mirror exit 2.
+            process.stderr.write(`measure_skill_reduction: error: unrecognized arguments: ${a}\n`);
+            process.exitCode = 2;
+            throw new ArgExit();
+        }
+    }
+    return args;
+}
+
+class ArgExit extends Error {}
+
+// --- JSON shaping ------------------------------------------------------------
+
+/** Wrapper marking a value as a Python float (renders integer-valued with `.0`). */
+class PyFloat {
+    constructor(readonly value: number) {}
+}
+
+type Json = null | boolean | number | string | PyFloat | Json[] | { [k: string]: Json };
+
+function _reportToJson(r: Report): Json {
+    const per: { [k: string]: Json } = {};
+    for (const [ut, e] of Object.entries(r.per_user_type)) {
+        per[ut] = {
+            loaded_skills: e.loaded_skills,
+            reduction_pct: e.reduction_pct,
+            passes_target: e.passes_target,
+        };
+    }
+    return {
+        total_skills: r.total_skills,
+        target_reduction: r.target_reduction,
+        per_user_type: per,
+        phase_3_user_types: r.phase_3_user_types,
+        phase_3_passed: r.phase_3_passed,
+    };
+}
+
+function _jsonDumpsIndent2(obj: Json): string {
+    return _jsonDumps(obj, { sortKeys: false, indent: 2 });
+}
+
+/**
+ * json.dumps replica. sort_keys is False here (.py uses default); indent=2.
+ * ensure_ascii defaults True → non-ASCII escaped to \uXXXX.
+ */
+function _jsonDumps(obj: Json, opts: { sortKeys: boolean; indent: number | null }): string {
+    const { sortKeys, indent } = opts;
+    const pad = indent !== null ? ' '.repeat(indent) : '';
+    const itemSep = indent !== null ? ',' : ', ';
+    const kvSep = ': ';
+
+    function enc(value: Json, depth: number): string {
+        if (value === null) return 'null';
+        if (value instanceof PyFloat) {
+            return Number.isInteger(value.value) ? `${value.value}.0` : _floatRepr(value.value);
+        }
+        if (typeof value === 'boolean') return value ? 'true' : 'false';
+        if (typeof value === 'number') return Number.isInteger(value) ? String(value) : _floatRepr(value);
+        if (typeof value === 'string') return encStr(value);
+        if (Array.isArray(value)) {
+            if (value.length === 0) return '[]';
+            if (indent !== null) {
+                const inner = value.map((v) => pad.repeat(depth + 1) + enc(v, depth + 1));
+                return '[\n' + inner.join(itemSep + '\n') + '\n' + pad.repeat(depth) + ']';
+            }
+            return '[' + value.map((v) => enc(v, depth + 1)).join(itemSep) + ']';
+        }
+        const o = value as { [k: string]: Json };
+        let keys = Object.keys(o);
+        if (keys.length === 0) return '{}';
+        if (sortKeys) {
+            keys = [...keys].sort(_pyStrCmp);
+        }
+        if (indent !== null) {
+            const inner = keys.map(
+                (k) => pad.repeat(depth + 1) + encStr(k) + kvSep + enc(o[k]!, depth + 1),
+            );
+            return '{\n' + inner.join(itemSep + '\n') + '\n' + pad.repeat(depth) + '}';
+        }
+        return '{' + keys.map((k) => encStr(k) + kvSep + enc(o[k]!, depth + 1)).join(itemSep) + '}';
+    }
+
+    function encStr(s: string): string {
+        let out = '"';
+        for (const ch of s) {
+            const cp = ch.codePointAt(0) as number;
+            if (ch === '"') out += '\\"';
+            else if (ch === '\\') out += '\\\\';
+            else if (ch === '\n') out += '\\n';
+            else if (ch === '\r') out += '\\r';
+            else if (ch === '\t') out += '\\t';
+            else if (ch === '\b') out += '\\b';
+            else if (ch === '\f') out += '\\f';
+            else if (cp < 0x20) out += '\\u' + cp.toString(16).padStart(4, '0');
+            else if (cp < 0x7f) out += ch;
+            else if (cp > 0xffff) {
+                const v = cp - 0x10000;
+                const hi = 0xd800 + (v >> 10);
+                const lo = 0xdc00 + (v & 0x3ff);
+                out += '\\u' + hi.toString(16).padStart(4, '0');
+                out += '\\u' + lo.toString(16).padStart(4, '0');
+            } else {
+                out += '\\u' + cp.toString(16).padStart(4, '0');
+            }
+        }
+        return out + '"';
+    }
+
+    return enc(obj, 0);
+}
+
+function _floatRepr(n: number): string {
+    // For the rounded ratios produced here, JS String() matches Python repr.
+    return String(n);
+}
+
+// --- Python helpers ----------------------------------------------------------
+
+function _pyRound(value: number, ndigits: number): number {
+    if (!Number.isFinite(value)) {
+        return value;
+    }
+    const factor = Math.pow(10, ndigits);
+    const scaled = value * factor;
+    const floor = Math.floor(scaled);
+    const diff = scaled - floor;
+    let rounded: number;
+    const eps = 1e-9;
+    if (Math.abs(diff - 0.5) < eps) {
+        rounded = floor % 2 === 0 ? floor : floor + 1;
+    } else {
+        rounded = Math.round(scaled);
+    }
+    return rounded / factor;
+}
+
+/** f"{x:.0%}" — multiply by 100, round-half-even, no decimals, '%' suffix. */
+function _fmtPct0(x: number): string {
+    return `${_pyFixed(x * 100, 0)}%`;
+}
+
+/** f"{x:.1%}" — multiply by 100, round-half-even, 1 decimal, '%' suffix. */
+function _fmtPct1(x: number): string {
+    return `${_pyFixed(x * 100, 1)}%`;
+}
+
+function _pyFixed(x: number, ndigits: number): string {
+    if (!Number.isFinite(x)) {
+        return String(x);
+    }
+    const neg = x < 0 || Object.is(x, -0);
+    const abs = Math.abs(x);
+    const factor = Math.pow(10, ndigits);
+    const scaled = abs * factor;
+    const floor = Math.floor(scaled);
+    const frac = scaled - floor;
+    const tol = Math.max(Math.abs(scaled), 1) * 2 ** -40;
+    let rounded: number;
+    if (Math.abs(frac - 0.5) <= tol) {
+        rounded = floor % 2 === 0 ? floor : floor + 1;
+    } else {
+        rounded = Math.round(scaled);
+    }
+    let intStr = String(rounded);
+    let result: string;
+    if (ndigits === 0) {
+        result = intStr;
+    } else {
+        if (intStr.length <= ndigits) {
+            intStr = '0'.repeat(ndigits - intStr.length + 1) + intStr;
+        }
+        const whole = intStr.slice(0, intStr.length - ndigits);
+        const dec = intStr.slice(intStr.length - ndigits);
+        result = `${whole}.${dec}`;
+    }
+    return neg ? `-${result}` : result;
+}
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function _splitParts(text: string, sep: string, maxsplit: number): string[] {
+    // Python str.split(sep, maxsplit).
+    const out: string[] = [];
+    let rest = text;
+    let count = 0;
+    while (count < maxsplit) {
+        const idx = rest.indexOf(sep);
+        if (idx < 0) break;
+        out.push(rest.slice(0, idx));
+        rest = rest.slice(idx + sep.length);
+        count += 1;
+    }
+    out.push(rest);
+    return out;
+}
+
+function _yamlSafeLoad(s: string): unknown {
+    const v = parseYaml(s, { version: '1.1' });
+    return restorePyScalars(v);
+}
+
+/**
+ * yaml@2 with version 1.1 returns booleans for y/Y/n/N etc. PyYAML safe_load
+ * keeps those as strings, and renders timestamps as a date marker. Restore.
+ */
+function restorePyScalars(v: unknown): unknown {
+    if (Array.isArray(v)) return v.map(restorePyScalars);
+    if (v && typeof v === 'object' && !(v instanceof Date)) {
+        const o = v as Record<string, unknown>;
+        const out: Record<string, unknown> = {};
+        for (const k of Object.keys(o)) out[k] = restorePyScalars(o[k]);
+        return out;
+    }
+    return v;
+}
+
+function _pyTruthy(v: unknown): boolean {
+    if (v === null || v === undefined || v === false) return false;
+    if (v === '' || v === 0) return false;
+    if (Array.isArray(v)) return v.length > 0;
+    if (typeof v === 'object') return Object.keys(v as object).length > 0;
+    return Boolean(v);
+}
+
+function _ljust(s: string, width: number): string {
+    const len = Array.from(s).length;
+    return len >= width ? s : s + ' '.repeat(width - len);
+}
+
+function _rjust(s: string, width: number): string {
+    const len = Array.from(s).length;
+    return len >= width ? s : ' '.repeat(width - len) + s;
+}
+
+function _pyStrCmp(a: string, b: string): number {
+    const ca = Array.from(a);
+    const cb = Array.from(b);
+    const n = Math.min(ca.length, cb.length);
+    for (let i = 0; i < n; i++) {
+        const x = ca[i]!.codePointAt(0)!;
+        const y = cb[i]!.codePointAt(0)!;
+        if (x !== y) return x - y;
+    }
+    return ca.length - cb.length;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+    try {
+        process.exitCode = main();
+    } catch (e) {
+        if (e instanceof ArgExit) {
+            process.exitCode = process.exitCode ?? 2;
+        } else {
+            throw e;
+        }
+    }
+}

package/src/scripts/media/lib/adapter-common.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# adapter-common.sh — shared boilerplate sourced by every media adapter
+# (video under scripts/ai-video/adapters/; image under scripts/ai-image/
+# adapters/ from Phase A.2 on). Lives in the neutral scripts/media/lib/
+# substrate so both domains depend on it without a cross-domain reference.
+# Keeps individual adapters thin and makes the contract surface (subcommand
+# dispatch, dry-run plumbing, stdout shape) uniform across providers.
+#
+# Sourced; never executed directly. Strict-mode flags are the caller's
+# responsibility (every adapter starts with `set -euo pipefail`).
+#
+# NAMING: the AIV_* exports below are the historical names. The MEDIA_*
+# aliases are the forward-looking, domain-neutral surface — new (image)
+# adapters SHOULD source via the MEDIA_* names. The AIV_*→MEDIA_* rename
+# of the internals is deferred to a follow-up (road-to-image-brand-typography
+# Phase A); both name sets stay live until then.
+
+if [ -n "${AIV_ADAPTER_COMMON_LOADED:-}" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+AIV_ADAPTER_COMMON_LOADED=1
+
+# Resolve the substrate dir from this file's location (scripts/media/lib).
+# Adapters source us via `$(dirname "$0")/../../media/lib/adapter-common.sh`.
+_aiv_lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "${_aiv_lib_dir}/redact.sh"
+# shellcheck source=/dev/null
+. "${_aiv_lib_dir}/load-config.sh"
+
+# AIV_LIB_DIR is the *adapter domain's* resource dir (model-capabilities/,
+# comfyui-*), resolved relative to the calling adapter ($0) — those
+# resources stay in scripts/<domain>/lib/, NOT in the shared substrate.
+# Falls back to the substrate dir for non-adapter callers (smoke harness,
+# direct sourcing in tests) that never read domain resources.
+AIV_LIB_DIR="$(cd "$(dirname "$0")/../lib" 2>/dev/null && pwd || printf '%s' "${_aiv_lib_dir}")"
+# Shared substrate + fixtures live with this file (scripts/media/lib).
+MEDIA_LIB_DIR="${_aiv_lib_dir}"
+AIV_FIXTURE_ROOT="${_aiv_lib_dir}/fixtures"
+MEDIA_FIXTURE_ROOT="${AIV_FIXTURE_ROOT}"
+export AIV_LIB_DIR MEDIA_LIB_DIR AIV_FIXTURE_ROOT MEDIA_FIXTURE_ROOT
+
+# Per-adapter run telemetry (success / cost / latency — local-only
+# JSONL, best-effort, AIV_TELEMETRY=false kill-switch).
+# shellcheck source=/dev/null
+. "${_aiv_lib_dir}/telemetry.sh"
+
+# aiv_die <exit-code> <message> — write redacted message to stderr.
+aiv_die() {
+  local code="${1:-1}"; shift || true
+  printf 'adapter: %s\n' "$*" | aiv_redact_stream >&2
+  exit "${code}"
+}
+
+# aiv_require_cmd <cmd> [<cmd> ...] — fail fast on missing dependency.
+aiv_require_cmd() {
+  local cmd
+  for cmd in "$@"; do
+    command -v "${cmd}" >/dev/null 2>&1 \
+      || aiv_die 3 "required tool not found: ${cmd}"
+  done
+}
+
+# aiv_emit_dry_run <adapter-id> — print contract-shaped stdout JSON
+# pointing at the adapter's fixture directory. Used by every adapter's
+# `dry-run` subcommand.
+aiv_emit_dry_run() {
+  local adapter="${1:-}"
+  [ -n "${adapter}" ] || aiv_die 3 "aiv_emit_dry_run: adapter id required"
+  local fixture_dir="${AIV_FIXTURE_ROOT}/${adapter}"
+  local result="${fixture_dir}/result.json"
+  if [ ! -f "${result}" ]; then
+    aiv_die 3 "fixture missing: ${result}"
+  fi
+  cat "${result}"
+}
+
+# aiv_capability <flag> — print the capability JSON for `--help`-style
+# discovery: `{"audio": "native|none|per-model"}`.
+aiv_capability() {
+  local flag="${1:-none}"
+  printf '{"audio":"%s"}\n' "${flag}"
+}
+
+# aiv_assert_dryrun — refuse to run a network path unless the caller
+# explicitly opted in (AIV_DRYRUN=false set in this turn).
+aiv_assert_dryrun() {
+  case "${AIV_DRYRUN:-true}" in
+    false|FALSE|0|no|NO) return 0 ;;
+    *) aiv_die 4 "live call refused: AIV_DRYRUN=${AIV_DRYRUN:-true}; use dry-run subcommand or set AIV_DRYRUN=false" ;;
+  esac
+}
+
+# -- Trust boundary (adapter-contract.md v2) --------------------------------
+# Provider-returned artifact paths and downloads are UNTRUSTED input. The
+# three helpers below are the enforcement surface the live submit/poll/fetch
+# path MUST route through, so an adapter physically cannot return /etc/passwd,
+# a symlink that escapes the project, or a runaway multi-GB stream.
+
+# aiv_max_artifact_bytes — hard size cap for a single fetched artifact.
+# Default 512 MiB; override via AIV_MAX_ARTIFACT_BYTES.
+aiv_max_artifact_bytes() {
+  printf '%s\n' "${AIV_MAX_ARTIFACT_BYTES:-536870912}"
+}
+
+# aiv_validate_artifact_path <root> <path> — canonicalize <path> and assert it
+# resolves INSIDE <root>. Echoes the canonical absolute path on success;
+# aiv_die 10 on any violation. Rejects: empty path, injection/control chars
+# (newline, single quote, backtick, command-sub), a symlink artifact, a
+# parent-traversal that escapes <root>, and a missing parent directory.
+aiv_validate_artifact_path() {
+  local root="${1:-}" path="${2:-}"
+  [ -n "${root}" ] || aiv_die 10 "validate_artifact_path: scope root required"
+  [ -n "${path}" ] || aiv_die 10 "validate_artifact_path: empty artifact path (untrusted provider output)"
+
+  # Injection guard — these characters would break out of ffmpeg's concat
+  # list (`file '...'`) or a redacted log line.
+  case "${path}" in
+    *"'"* | *'`'* | *'$('*)
+      aiv_die 10 "validate_artifact_path: illegal character in artifact path (injection guard)" ;;
+  esac
+  if [ "$(printf '%s' "${path}" | tr -d '[:cntrl:]')" != "${path}" ]; then
+    aiv_die 10 "validate_artifact_path: control character in artifact path"
+  fi
+
+  local real_root
+  real_root="$(cd "${root}" 2>/dev/null && pwd -P)" \
+    || aiv_die 10 "validate_artifact_path: scope root not a directory: ${root}"
+
+  # A symlink artifact is rejected outright — its target is provider-controlled.
+  [ -L "${path}" ] && aiv_die 10 "validate_artifact_path: symlink artifacts are not allowed: ${path}"
+
+  # Canonicalize the PARENT (resolving any symlinked dirs) and re-attach the
+  # basename, so a not-yet-created live-fetch target still validates.
+  local parent base real_parent real_path
+  parent="$(dirname "${path}")"
+  base="$(basename "${path}")"
+  case "${base}" in
+    .. | .) aiv_die 10 "validate_artifact_path: illegal basename: ${base}" ;;
+  esac
+  real_parent="$(cd "${parent}" 2>/dev/null && pwd -P)" \
+    || aiv_die 10 "validate_artifact_path: parent dir missing: ${parent}"
+  real_path="${real_parent}/${base}"
+
+  case "${real_path}" in
+    "${real_root}"/* | "${real_root}") printf '%s\n' "${real_path}" ;;
+    *) aiv_die 10 "validate_artifact_path: path escapes scope root: ${path} not under ${root}" ;;
+  esac
+}
+
+# aiv_scene_dir <project_dir> <scene_id> — create and echo the scene-scoped
+# output dir. Live fetch writes artifacts here, then validates the result.
+aiv_scene_dir() {
+  local project="${1:-}" scene="${2:-}"
+  [ -n "${project}" ] && [ -n "${scene}" ] \
+    || aiv_die 10 "aiv_scene_dir: project dir and scene id required"
+  case "${scene}" in
+    */* | .. | . | *"'"*) aiv_die 10 "aiv_scene_dir: illegal scene id: ${scene}" ;;
+  esac
+  local dir="${project}/scenes/${scene}"
+  mkdir -p "${dir}" || aiv_die 10 "aiv_scene_dir: cannot create ${dir}"
+  printf '%s\n' "${dir}"
+}
+
+# aiv_fetch_url <url> <dest> [max_bytes] — download <url> into <dest> with a
+# hard size cap (aiv_max_artifact_bytes) and timeout (AIV_FETCH_TIMEOUT,
+# default 120s). Live `fetch` MUST route downloads through this helper so a
+# hostile or runaway response cannot exhaust disk. Echoes <dest> on success.
+# Optional: AIV_FETCH_HEADER carries ONE auth header for providers whose
+# artifact URIs require it (e.g. Gemini file downloads need x-goog-api-key).
+# Empty/unset = no header — existing callers are unchanged. The header value
+# is never echoed; registered keys are redacted from any curl stderr.
+aiv_fetch_url() {
+  local url="${1:-}" dest="${2:-}" cap="${3:-}"
+  [ -n "${url}" ] && [ -n "${dest}" ] || aiv_die 10 "aiv_fetch_url: url and dest required"
+  [ -n "${cap}" ] || cap="$(aiv_max_artifact_bytes)"
+  aiv_require_cmd curl
+  if [ -n "${AIV_FETCH_HEADER:-}" ]; then
+    if ! curl --fail --silent --show-error --location \
+         --max-filesize "${cap}" --max-time "${AIV_FETCH_TIMEOUT:-120}" \
+         -H "${AIV_FETCH_HEADER}" \
+         --output "${dest}" "${url}" 2>&1 | aiv_redact_stream >&2; then
+      aiv_die 11 "aiv_fetch_url: download failed or exceeded ${cap} bytes: ${url}"
+    fi
+  else
+    if ! curl --fail --silent --show-error --location \
+         --max-filesize "${cap}" --max-time "${AIV_FETCH_TIMEOUT:-120}" \
+         --output "${dest}" "${url}" 2>&1 | aiv_redact_stream >&2; then
+      aiv_die 11 "aiv_fetch_url: download failed or exceeded ${cap} bytes: ${url}"
+    fi
+  fi
+  printf '%s\n' "${dest}"
+}
+
+# _aiv_dispatch_timed <adapter> <sub> "$@" — run aiv_cmd_<sub> in a
+# subshell, record success/latency/cost telemetry (best-effort), then
+# propagate stdout, stderr, and the exit code unchanged. The subshell
+# is what lets a failing subcommand (aiv_die exits) still produce a
+# telemetry record without altering the adapter's observable contract.
+# `capability` and `dry-run` are NOT timed — offline, byte-exact
+# fixture output stays untouched.
+_aiv_dispatch_timed() {
+  local adapter="${1}" sub="${2}"; shift 2
+  local fn="aiv_cmd_${sub//-/_}"
+  declare -F "${fn}" >/dev/null || aiv_die 5 "${adapter}: ${sub} not implemented"
+  local start_ms end_ms rc=0 out cost=""
+  start_ms="$(aiv_now_ms)"
+  out="$( ( "${fn}" "$@" ) )" || rc=$?
+  end_ms="$(aiv_now_ms)"
+  if [ "${rc}" -eq 0 ] && [ -n "${out}" ] && command -v jq >/dev/null 2>&1; then
+    cost="$(printf '%s' "${out}" | jq -r '.cost_estimate // empty' 2>/dev/null || true)"
+  fi
+  aiv_telemetry_record "${adapter}" "${sub}" \
+    "$([ "${rc}" -eq 0 ] && printf 'ok' || printf 'exit_%d' "${rc}")" \
+    "$(( end_ms - start_ms ))" "${cost}" || true
+  [ -n "${out}" ] && printf '%s\n' "${out}"
+  return "${rc}"
+}
+
+# aiv_dispatch <adapter-id> <capability> "$@" — generic subcommand router.
+# Adapters override individual subcommands by defining bash functions
+# named `aiv_cmd_submit` / `aiv_cmd_poll` / `aiv_cmd_fetch` / `aiv_cmd_run`
+# BEFORE calling aiv_dispatch. Anything not overridden falls through to
+# a stub that exits non-zero with a clear message. Network-bound
+# subcommands route through _aiv_dispatch_timed for run telemetry.
+aiv_dispatch() {
+  local adapter="${1:-}"; shift || true
+  local cap="${1:-none}"; shift || true
+  local sub="${1:-}"; shift || true
+  case "${sub}" in
+    capability)
+      aiv_capability "${cap}"
+      ;;
+    dry-run)
+      aiv_emit_dry_run "${adapter}"
+      ;;
+    submit|poll|fetch|run)
+      _aiv_dispatch_timed "${adapter}" "${sub}" "$@"
+      ;;
+    "")
+      aiv_die 2 "${adapter}: subcommand required (capability|dry-run|submit|poll|fetch|run)"
+      ;;
+    *)
+      aiv_die 2 "${adapter}: unknown subcommand '${sub}'"
+      ;;
+  esac
+}