@ttt-productions/media-processing-core 0.8.3 → 0.8.5

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export * from "./audio/index.js";
 export * from "./audio/audio-processor.js";
 export * from "./io/types.js";
 export * from "./run-pipeline.js";
+export * from "./inspection/inspect-media.js";
 export * from "./io/fs.js";
 export * from "./moderation/types.js";
 export * from "./moderation/merge.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAElC,cAAc,YAAY,CAAC;AAE3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAE3C,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAElC,cAAc,+BAA+B,CAAC;AAE9C,cAAc,YAAY,CAAC;AAE3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -8,6 +8,7 @@ export * from "./audio/index.js"; // Not ./audio.js
 export * from "./audio/audio-processor.js";
 export * from "./io/types.js";
 export * from "./run-pipeline.js";
+export * from "./inspection/inspect-media.js";
 export * from "./io/fs.js";
 export * from "./moderation/types.js";
 export * from "./moderation/merge.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC,CAAW,iBAAiB;AAC7D,cAAc,4BAA4B,CAAC;AAE3C,cAAc,kBAAkB,CAAC,CAAW,iBAAiB;AAC7D,cAAc,4BAA4B,CAAC;AAE3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,kBAAkB,CAAC,CAAW,iBAAiB;AAC7D,cAAc,4BAA4B,CAAC;AAE3C,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAElC,cAAc,YAAY,CAAC;AAE3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC","sourcesContent":["export * from \"./image/index.js\";           // Not ./image.js\nexport * from \"./image/image-processor.js\";\n\nexport * from \"./video/index.js\";           // Not ./video.js\nexport * from \"./video/video-processor.js\";\n\nexport * from \"./process-media.js\";\nexport * from \"./workspace/temp.js\";\n\nexport * from \"./audio/index.js\";           // Not ./audio.js\nexport * from \"./audio/audio-processor.js\";\n\nexport * from \"./io/types.js\";\nexport * from \"./run-pipeline.js\";\n\nexport * from \"./io/fs.js\";\n\nexport * from \"./moderation/types.js\";\nexport * from \"./moderation/merge.js\";"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC,CAAW,iBAAiB;AAC7D,cAAc,4BAA4B,CAAC;AAE3C,cAAc,kBAAkB,CAAC,CAAW,iBAAiB;AAC7D,cAAc,4BAA4B,CAAC;AAE3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,kBAAkB,CAAC,CAAW,iBAAiB;AAC7D,cAAc,4BAA4B,CAAC;AAE3C,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAElC,cAAc,+BAA+B,CAAC;AAE9C,cAAc,YAAY,CAAC;AAE3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC","sourcesContent":["export * from \"./image/index.js\";           // Not ./image.js\nexport * from \"./image/image-processor.js\";\n\nexport * from \"./video/index.js\";           // Not ./video.js\nexport * from \"./video/video-processor.js\";\n\nexport * from \"./process-media.js\";\nexport * from \"./workspace/temp.js\";\n\nexport * from \"./audio/index.js\";           // Not ./audio.js\nexport * from \"./audio/audio-processor.js\";\n\nexport * from \"./io/types.js\";\nexport * from \"./run-pipeline.js\";\n\nexport * from \"./inspection/inspect-media.js\";\n\nexport * from \"./io/fs.js\";\n\nexport * from \"./moderation/types.js\";\nexport * from \"./moderation/merge.js\";"]}

package/dist/inspection/inspect-media.d.ts

@@ -0,0 +1,57 @@
+import { type MediaInspectionResult, type MediaFormatId } from "@ttt-productions/media-schemas";
+/** Bump on any classification-rule change (rides every decision event). */
+export declare const INSPECTOR_VERSION = "mpc-inspect-1";
+type SignatureFamily = {
+    family: "image";
+    formatId: MediaFormatId;
+    container: string;
+} | {
+    family: "svg";
+} | {
+    family: "ebml";
+} | {
+    family: "isobmff";
+    brand: string;
+} | {
+    family: "ogg";
+} | {
+    family: "avi";
+} | {
+    family: "wav";
+} | {
+    family: "mp3";
+} | {
+    family: "flac";
+} | {
+    family: "unknown";
+};
+export declare function detectSignatureFamily(b: Uint8Array): SignatureFamily;
+export interface InspectMediaDeps {
+    /** Probe the local file; default shells to the hardened `ffprobe`. */
+    probe?: (localPath: string, opts: {
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }) => Promise<{
+        ok: true;
+        json: unknown;
+    } | {
+        ok: false;
+        reason: "timeout" | "truncated" | "failed" | "bad_json";
+    }>;
+    /** Decode-prove an image; default uses sharp metadata. Returns frame count
+     *  (pages) on success, null on decode failure. */
+    decodeImage?: (localPath: string) => Promise<{
+        frames: number;
+    } | null>;
+    /** Injected ffprobe version (default: cached `ffprobe -version` first line). */
+    ffprobeVersion?: string;
+}
+export interface InspectMediaArgs {
+    localPath: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    deps?: InspectMediaDeps;
+}
+export declare function inspectMedia(args: InspectMediaArgs): Promise<MediaInspectionResult>;
+export {};
+//# sourceMappingURL=inspect-media.d.ts.map

package/dist/inspection/inspect-media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-media.d.ts","sourceRoot":"","sources":["../../src/inspection/inspect-media.ts"],"names":[],"mappings":"AA8BA,OAAO,EAEL,KAAK,qBAAqB,EAG1B,KAAK,aAAa,EACnB,MAAM,gCAAgC,CAAC;AAGxC,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AA2DjD,KAAK,eAAe,GAChB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAY1B,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,UAAU,GAAG,eAAe,CAiCpE;AAID,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CACrF;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,GAC3B;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAA;KAAE,CACzE,CAAC;IACF;sDACkD;IAClD,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IACxE,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAyGD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA0HzF"}

package/dist/inspection/inspect-media.js

@@ -0,0 +1,412 @@
+// =============================================================================
+// Canonical media content inspection (canonical-upload-content-classification)
+// =============================================================================
+//
+// The ONE server-side classification authority. Consumes a LOCAL file (the
+// pipeline's generation-pinned temp download), establishes what the bytes
+// actually contain, and returns the bounded `MediaInspectionResult` contract
+// from @ttt-productions/media-schemas. Everything downstream — origin/kind
+// validation, processing-spec selection, the persisted asset kind, and the
+// safety (PhotoDNA) routing — derives from this one result. Client MIME,
+// filename, extension, container brand, and payload-byte heuristics are never
+// consulted.
+//
+// Design (reviewed 2026-07-31; see the consuming app's
+// CODE_CHANGE_canonical_upload_content_classification.md):
+//   - family selection by a bounded 64 KiB SIGNATURE read (header only —
+//     semantic elements are NEVER searched for in arbitrary payload; that
+//     flat-scan heuristic caused the WebM audio misclassification twice);
+//   - shared A/V containers (EBML/ISO-BMFF/Ogg/AVI) classified by a hardened
+//     `ffprobe` stream table (libavformat's structural parsers), with timeout,
+//     kill-on-abort, output cap, and strict schema validation;
+//   - image-family proof by DECODER (sharp) — a signature or `ftyp` brand is a
+//     candidate, not proof, and image-family ISO-BMFF (AVIF/HEIC) is resolved
+//     BEFORE the ordinary "any timed video stream wins" rule (a valid AVIF
+//     probes as a one-frame AV1 `video` stream);
+//   - FAIL-CLOSED: anything unproven is `indeterminate` with the
+//     `strict-video-fallback` safety plan — never audio, never publishable.
+import { open } from "node:fs/promises";
+import { z } from "zod";
+import { MediaInspectionResultSchema, } from "@ttt-productions/media-schemas";
+import { runCmd } from "../video/ffmpeg.js";
+/** Bump on any classification-rule change (rides every decision event). */
+export const INSPECTOR_VERSION = "mpc-inspect-1";
+const SIGNATURE_READ_BYTES = 64 * 1024;
+const DEFAULT_PROBE_TIMEOUT_MS = 20_000;
+const PROBE_SIZE_BYTES = 4 * 1024 * 1024; // -probesize: metadata, not playback
+const ANALYZE_DURATION_US = 10 * 1000 * 1000;
+// ---- ffprobe JSON boundary (strict; anything else is malformed) ----
+const ProbeStreamSchema = z
+    .object({
+    codec_type: z.string().max(32).optional(),
+    codec_name: z.string().max(64).optional(),
+    disposition: z
+        .object({ attached_pic: z.number().int().min(0).max(1).optional() })
+        .loose()
+        .optional(),
+    nb_frames: z.string().max(20).optional(),
+    duration: z.string().max(32).optional(),
+})
+    .loose();
+const ProbeJsonSchema = z
+    .object({
+    format: z.object({ format_name: z.string().max(200).optional() }).loose().optional(),
+    streams: z.array(ProbeStreamSchema).max(256).optional(),
+})
+    .loose();
+// ---- codec normalization (bounded — raw strings never escape) ----
+const CODEC_MAP = {
+    h264: "h264",
+    hevc: "hevc",
+    vp8: "vp8",
+    vp9: "vp9",
+    av1: "av1",
+    theora: "theora",
+    mpeg4: "mpeg4",
+    mjpeg: "mjpeg",
+    aac: "aac",
+    alac: "alac",
+    opus: "opus",
+    vorbis: "vorbis",
+    mp3: "mp3",
+    flac: "flac",
+};
+function normalizeCodec(name) {
+    if (!name)
+        return "other";
+    const n = name.toLowerCase();
+    if (CODEC_MAP[n])
+        return CODEC_MAP[n];
+    if (n.startsWith("pcm_"))
+        return "pcm";
+    if (n.startsWith("amr"))
+        return "amr";
+    return "other";
+}
+/** ISO-BMFF brands that declare an IMAGE-item file (HEIF family). Resolved via
+ *  decoder proof BEFORE the timed-video rule — see the AVIF note above. */
+const ISOBMFF_IMAGE_BRANDS = new Set(["avif", "avis", "heic", "heix", "heim", "heis", "hevc", "hevx", "mif1", "msf1"]);
+function ascii(b, off, s) {
+    if (off + s.length > b.length)
+        return false;
+    for (let i = 0; i < s.length; i++)
+        if (b[off + i] !== s.charCodeAt(i))
+            return false;
+    return true;
+}
+export function detectSignatureFamily(b) {
+    if (b.length < 12)
+        return { family: "unknown" };
+    // images (single-format signatures)
+    if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+        return { family: "image", formatId: "jpeg", container: "jpeg" };
+    if (b[0] === 0x89 && ascii(b, 1, "PNG"))
+        return { family: "image", formatId: "png", container: "png" };
+    if (ascii(b, 0, "GIF8"))
+        return { family: "image", formatId: "gif", container: "gif" };
+    if (ascii(b, 0, "RIFF") && ascii(b, 8, "WEBP"))
+        return { family: "image", formatId: "webp", container: "webp" };
+    if (b[0] === 0x42 && b[1] === 0x4d)
+        return { family: "image", formatId: "bmp", container: "bmp" };
+    if ((b[0] === 0x49 && b[1] === 0x49 && b[2] === 0x2a) || (b[0] === 0x4d && b[1] === 0x4d && b[3] === 0x2a)) {
+        return { family: "image", formatId: "tiff", container: "tiff" };
+    }
+    // SVG: XML text — scan a short prefix for '<svg' (bounded; case-insensitive).
+    {
+        const prefix = Buffer.from(b.slice(0, Math.min(b.length, 4096)))
+            .toString("latin1")
+            .toLowerCase();
+        if (prefix.includes("<svg") && (prefix.trimStart().startsWith("<?xml") || prefix.trimStart().startsWith("<svg") || prefix.includes("<!doctype svg"))) {
+            return { family: "svg" };
+        }
+    }
+    // containers
+    if (b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3)
+        return { family: "ebml" };
+    if (ascii(b, 4, "ftyp")) {
+        const brand = String.fromCharCode(b[8], b[9], b[10], b[11]).trim().toLowerCase();
+        return { family: "isobmff", brand };
+    }
+    if (ascii(b, 0, "OggS"))
+        return { family: "ogg" };
+    if (ascii(b, 0, "RIFF") && ascii(b, 8, "AVI "))
+        return { family: "avi" };
+    if (ascii(b, 0, "RIFF") && ascii(b, 8, "WAVE"))
+        return { family: "wav" };
+    if (ascii(b, 0, "ID3"))
+        return { family: "mp3" };
+    if (b[0] === 0xff && (b[1] & 0xe0) === 0xe0)
+        return { family: "mp3" };
+    if (ascii(b, 0, "fLaC"))
+        return { family: "flac" };
+    return { family: "unknown" };
+}
+let cachedFfprobeVersion;
+async function getFfprobeVersion() {
+    if (cachedFfprobeVersion !== undefined)
+        return cachedFfprobeVersion ?? undefined;
+    try {
+        const r = await runCmd("ffprobe", ["-version"], { timeoutMs: 5_000 });
+        const first = (r.stdout || r.stderr).split(/\r?\n/)[0]?.trim() ?? "";
+        cachedFfprobeVersion = first ? first.slice(0, 120) : null;
+    }
+    catch {
+        cachedFfprobeVersion = null;
+    }
+    return cachedFfprobeVersion ?? undefined;
+}
+async function defaultProbe(localPath, opts) {
+    let r;
+    try {
+        r = await runCmd("ffprobe", [
+            "-v",
+            "error",
+            "-print_format",
+            "json",
+            "-show_format",
+            "-show_streams",
+            "-probesize",
+            String(PROBE_SIZE_BYTES),
+            "-analyzeduration",
+            String(ANALYZE_DURATION_US),
+            localPath,
+        ], { timeoutMs: opts.timeoutMs, signal: opts.signal });
+    }
+    catch {
+        return { ok: false, reason: "failed" }; // spawn failure (ffprobe missing) — fail closed
+    }
+    if (r.timedOut)
+        return { ok: false, reason: "timeout" };
+    if (r.truncated)
+        return { ok: false, reason: "truncated" };
+    if (r.code !== 0)
+        return { ok: false, reason: "failed" };
+    try {
+        return { ok: true, json: JSON.parse(r.stdout || "{}") };
+    }
+    catch {
+        return { ok: false, reason: "bad_json" };
+    }
+}
+async function defaultDecodeImage(localPath) {
+    try {
+        const sharp = (await import("sharp")).default;
+        const meta = await sharp(localPath, { limitInputPixels: 268402689 /* sharp default ~16k x 16k */ }).metadata();
+        if (!meta.width || !meta.height)
+            return null;
+        return { frames: Math.max(1, meta.pages ?? 1) };
+    }
+    catch {
+        return null;
+    }
+}
+// ---- result builders ----
+function baseResult(partial, ffprobeVersion) {
+    const result = {
+        inspectorVersion: INSPECTOR_VERSION,
+        ...(ffprobeVersion ? { ffprobeVersion } : {}),
+        streams: partial.streams ?? { audio: 0, timedVideo: 0, attachedPictures: 0, imageFrames: 0, auxiliary: 0 },
+        codecs: partial.codecs ?? { audio: [], video: [] },
+        status: partial.status,
+        container: partial.container,
+        safetyPlan: partial.safetyPlan,
+        reasonCode: partial.reasonCode,
+        ...(partial.canonicalKind ? { canonicalKind: partial.canonicalKind } : {}),
+        ...(partial.formatId ? { formatId: partial.formatId } : {}),
+    };
+    return MediaInspectionResultSchema.parse(result);
+}
+function indeterminate(container, reasonCode, ffprobeVersion, formatId) {
+    return baseResult({
+        status: "indeterminate",
+        container,
+        safetyPlan: "strict-video-fallback",
+        reasonCode,
+        ...(formatId ? { formatId } : {}),
+    }, ffprobeVersion);
+}
+export async function inspectMedia(args) {
+    const timeoutMs = args.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const probe = args.deps?.probe ?? defaultProbe;
+    const decodeImage = args.deps?.decodeImage ?? defaultDecodeImage;
+    const ffprobeVersion = args.deps?.ffprobeVersion ?? (await getFfprobeVersion());
+    // 1) bounded signature read (header only)
+    let head;
+    try {
+        const fh = await open(args.localPath, "r");
+        try {
+            const buf = Buffer.alloc(SIGNATURE_READ_BYTES);
+            const { bytesRead } = await fh.read(buf, 0, SIGNATURE_READ_BYTES, 0);
+            head = buf.subarray(0, bytesRead);
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    catch {
+        return indeterminate("unknown", "read_failed", ffprobeVersion);
+    }
+    const sig = detectSignatureFamily(head);
+    // 2) family routing
+    switch (sig.family) {
+        case "unknown":
+            return indeterminate("unknown", "unrecognized_signature", ffprobeVersion);
+        case "svg":
+            // Scriptable XML "image" — structurally recognized, deliberately NOT a
+            // processable format until a sanitize/rasterize design exists (launch
+            // policy 2026-07-31). Never classified by decoder capability alone.
+            return baseResult({
+                status: "unsupported",
+                container: "svg",
+                formatId: "svg",
+                safetyPlan: "strict-video-fallback",
+                reasonCode: "unsupported_format:svg",
+            }, ffprobeVersion);
+        case "image": {
+            // Single-format image signature: decoder proof required — a signature is
+            // a candidate, not a classification.
+            const decoded = await decodeImage(args.localPath);
+            if (!decoded)
+                return baseResult({ status: "malformed", container: sig.container, formatId: sig.formatId, safetyPlan: "strict-video-fallback", reasonCode: "image_decode_failed" }, ffprobeVersion);
+            const frames = decoded.frames;
+            return baseResult({
+                status: "definitive",
+                canonicalKind: "image",
+                container: sig.container,
+                formatId: sig.formatId,
+                streams: { audio: 0, timedVideo: 0, attachedPictures: 0, imageFrames: frames, auxiliary: 0 },
+                safetyPlan: frames > 1 ? "animated-image-frames" : "still-image",
+                reasonCode: "ok",
+            }, ffprobeVersion);
+        }
+        case "isobmff":
+            if (ISOBMFF_IMAGE_BRANDS.has(sig.brand)) {
+                // IMAGE-FAMILY ISO-BMFF resolves BEFORE the timed-video rule: a valid
+                // AVIF probes as a one-frame AV1 `video` stream. Proof = image brand +
+                // successful bounded decode + no ordinary timed A/V presentation.
+                const probed = await probe(args.localPath, { timeoutMs, signal: args.signal });
+                const parsed = probed.ok ? ProbeJsonSchema.safeParse(probed.json) : null;
+                const streams = parsed?.success ? parsed.data.streams ?? [] : null;
+                const hasAudio = streams ? streams.some((s) => s.codec_type === "audio") : true; // unknown ⇒ assume worst
+                const formatId = sig.brand.startsWith("avi") ? "avif" : "heic";
+                const decoded = await decodeImage(args.localPath);
+                if (!decoded || hasAudio) {
+                    if (formatId === "heic" && !decoded && !hasAudio) {
+                        // Recognized HEIC-family that the runtime cannot decode: explicit
+                        // unsupported-image (launch policy) — NEVER relabeled video.
+                        return baseResult({ status: "unsupported", container: "heif", formatId, safetyPlan: "strict-video-fallback", reasonCode: "unsupported_format:heic" }, ffprobeVersion);
+                    }
+                    // Undecodable/ambiguous image-brand file, or one carrying audio (a
+                    // real timed presentation wearing an image brand): fail toward the
+                    // stricter visual path.
+                    return indeterminate("heif", decoded ? "image_brand_with_audio" : "image_decode_failed", ffprobeVersion, formatId);
+                }
+                const frames = decoded.frames;
+                return baseResult({
+                    status: "definitive",
+                    canonicalKind: "image",
+                    container: "heif",
+                    formatId,
+                    streams: { audio: 0, timedVideo: 0, attachedPictures: 0, imageFrames: frames, auxiliary: 0 },
+                    safetyPlan: frames > 1 ? "animated-image-frames" : "still-image",
+                    reasonCode: "ok",
+                }, ffprobeVersion);
+            }
+            return classifyAvContainer(args, "isobmff", "isobmff", probe, timeoutMs, ffprobeVersion);
+        case "ebml":
+            return classifyAvContainer(args, "webm", "webm", probe, timeoutMs, ffprobeVersion);
+        case "ogg":
+            return classifyAvContainer(args, "ogg", "ogg", probe, timeoutMs, ffprobeVersion);
+        case "avi":
+            // Real container ffprobe parses; no registry entry (no origin enables it
+            // today) — the stream truth still classifies it, policy rejects by format.
+            return classifyAvContainer(args, "avi", undefined, probe, timeoutMs, ffprobeVersion);
+        case "wav":
+            return classifyAvContainer(args, "wav", "wav", probe, timeoutMs, ffprobeVersion);
+        case "mp3":
+            return classifyAvContainer(args, "mp3", "mp3", probe, timeoutMs, ffprobeVersion);
+        case "flac":
+            return classifyAvContainer(args, "flac", "flac", probe, timeoutMs, ffprobeVersion);
+    }
+}
+async function classifyAvContainer(args, container, formatId, probe, timeoutMs, ffprobeVersion) {
+    const probed = await probe(args.localPath, { timeoutMs, signal: args.signal });
+    if (!probed.ok) {
+        return indeterminate(container, `probe_${probed.reason}`, ffprobeVersion, formatId);
+    }
+    const parsed = ProbeJsonSchema.safeParse(probed.json);
+    if (!parsed.success)
+        return indeterminate(container, "probe_schema_invalid", ffprobeVersion, formatId);
+    const rawStreams = parsed.data.streams ?? [];
+    if (rawStreams.length === 0)
+        return indeterminate(container, "no_streams", ffprobeVersion, formatId);
+    const counts = { audio: 0, timedVideo: 0, attachedPictures: 0, imageFrames: 0, auxiliary: 0 };
+    const audioCodecs = new Set();
+    const videoCodecs = new Set();
+    let sawUnknownType = false;
+    for (const s of rawStreams) {
+        const type = s.codec_type ?? "";
+        if (type === "audio") {
+            counts.audio++;
+            audioCodecs.add(normalizeCodec(s.codec_name));
+        }
+        else if (type === "video") {
+            // An attached picture (cover art) is NOT a timed presentation — but the
+            // disposition flag is untrusted container data, so it is COUNTED and the
+            // safety plan forces every such picture through the image hash path
+            // before the audio guard may return clean.
+            if (s.disposition?.attached_pic === 1) {
+                counts.attachedPictures++;
+            }
+            else {
+                counts.timedVideo++;
+                videoCodecs.add(normalizeCodec(s.codec_name));
+            }
+        }
+        else if (type === "subtitle" || type === "data" || type === "attachment") {
+            counts.auxiliary++;
+        }
+        else {
+            counts.auxiliary++;
+            sawUnknownType = true;
+        }
+    }
+    const codecs = { audio: [...audioCodecs], video: [...videoCodecs] };
+    // classification table (fail-closed)
+    if (counts.timedVideo > 0) {
+        return baseResult({
+            status: "definitive",
+            canonicalKind: "video",
+            container,
+            ...(formatId ? { formatId } : {}),
+            streams: counts,
+            codecs,
+            safetyPlan: "video-frames",
+            reasonCode: "ok",
+        }, ffprobeVersion);
+    }
+    if (counts.audio > 0 && !sawUnknownType) {
+        return baseResult({
+            status: "definitive",
+            canonicalKind: "audio",
+            container,
+            ...(formatId ? { formatId } : {}),
+            streams: counts,
+            codecs,
+            safetyPlan: counts.attachedPictures > 0 ? "audio-plus-artwork" : "audio-only",
+            reasonCode: "ok",
+        }, ffprobeVersion);
+    }
+    // auxiliary-only, unknown stream types alongside audio, or nothing usable:
+    // never audio — the strict visual fallback owns it.
+    return baseResult({
+        status: "indeterminate",
+        container,
+        ...(formatId ? { formatId } : {}),
+        streams: counts,
+        codecs,
+        safetyPlan: "strict-video-fallback",
+        reasonCode: sawUnknownType ? "unknown_stream_type" : "auxiliary_only",
+    }, ffprobeVersion);
+}
+//# sourceMappingURL=inspect-media.js.map

package/dist/inspection/inspect-media.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-media.js","sourceRoot":"","sources":["../../src/inspection/inspect-media.ts"],"names":[],"mappings":"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","sourcesContent":["// =============================================================================\n// Canonical media content inspection (canonical-upload-content-classification)\n// =============================================================================\n//\n// The ONE server-side classification authority. Consumes a LOCAL file (the\n// pipeline's generation-pinned temp download), establishes what the bytes\n// actually contain, and returns the bounded `MediaInspectionResult` contract\n// from @ttt-productions/media-schemas. Everything downstream — origin/kind\n// validation, processing-spec selection, the persisted asset kind, and the\n// safety (PhotoDNA) routing — derives from this one result. Client MIME,\n// filename, extension, container brand, and payload-byte heuristics are never\n// consulted.\n//\n// Design (reviewed 2026-07-31; see the consuming app's\n// CODE_CHANGE_canonical_upload_content_classification.md):\n//   - family selection by a bounded 64 KiB SIGNATURE read (header only —\n//     semantic elements are NEVER searched for in arbitrary payload; that\n//     flat-scan heuristic caused the WebM audio misclassification twice);\n//   - shared A/V containers (EBML/ISO-BMFF/Ogg/AVI) classified by a hardened\n//     `ffprobe` stream table (libavformat's structural parsers), with timeout,\n//     kill-on-abort, output cap, and strict schema validation;\n//   - image-family proof by DECODER (sharp) — a signature or `ftyp` brand is a\n//     candidate, not proof, and image-family ISO-BMFF (AVIF/HEIC) is resolved\n//     BEFORE the ordinary \"any timed video stream wins\" rule (a valid AVIF\n//     probes as a one-frame AV1 `video` stream);\n//   - FAIL-CLOSED: anything unproven is `indeterminate` with the\n//     `strict-video-fallback` safety plan — never audio, never publishable.\n\nimport { open } from \"node:fs/promises\";\nimport { z } from \"zod\";\nimport {\n  MediaInspectionResultSchema,\n  type MediaInspectionResult,\n  type MediaInspectionStreams,\n  type NormalizedCodecId,\n  type MediaFormatId,\n} from \"@ttt-productions/media-schemas\";\nimport { runCmd } from \"../video/ffmpeg.js\";\n\n/** Bump on any classification-rule change (rides every decision event). */\nexport const INSPECTOR_VERSION = \"mpc-inspect-1\";\n\nconst SIGNATURE_READ_BYTES = 64 * 1024;\nconst DEFAULT_PROBE_TIMEOUT_MS = 20_000;\nconst PROBE_SIZE_BYTES = 4 * 1024 * 1024; // -probesize: metadata, not playback\nconst ANALYZE_DURATION_US = 10 * 1000 * 1000;\n\n// ---- ffprobe JSON boundary (strict; anything else is malformed) ----\n\nconst ProbeStreamSchema = z\n  .object({\n    codec_type: z.string().max(32).optional(),\n    codec_name: z.string().max(64).optional(),\n    disposition: z\n      .object({ attached_pic: z.number().int().min(0).max(1).optional() })\n      .loose()\n      .optional(),\n    nb_frames: z.string().max(20).optional(),\n    duration: z.string().max(32).optional(),\n  })\n  .loose();\n\nconst ProbeJsonSchema = z\n  .object({\n    format: z.object({ format_name: z.string().max(200).optional() }).loose().optional(),\n    streams: z.array(ProbeStreamSchema).max(256).optional(),\n  })\n  .loose();\n\n// ---- codec normalization (bounded — raw strings never escape) ----\n\nconst CODEC_MAP: Record<string, NormalizedCodecId> = {\n  h264: \"h264\",\n  hevc: \"hevc\",\n  vp8: \"vp8\",\n  vp9: \"vp9\",\n  av1: \"av1\",\n  theora: \"theora\",\n  mpeg4: \"mpeg4\",\n  mjpeg: \"mjpeg\",\n  aac: \"aac\",\n  alac: \"alac\",\n  opus: \"opus\",\n  vorbis: \"vorbis\",\n  mp3: \"mp3\",\n  flac: \"flac\",\n};\n\nfunction normalizeCodec(name: string | undefined): NormalizedCodecId {\n  if (!name) return \"other\";\n  const n = name.toLowerCase();\n  if (CODEC_MAP[n]) return CODEC_MAP[n];\n  if (n.startsWith(\"pcm_\")) return \"pcm\";\n  if (n.startsWith(\"amr\")) return \"amr\";\n  return \"other\";\n}\n\n// ---- signature families ----\n\ntype SignatureFamily =\n  | { family: \"image\"; formatId: MediaFormatId; container: string }\n  | { family: \"svg\" }\n  | { family: \"ebml\" }\n  | { family: \"isobmff\"; brand: string }\n  | { family: \"ogg\" }\n  | { family: \"avi\" }\n  | { family: \"wav\" }\n  | { family: \"mp3\" }\n  | { family: \"flac\" }\n  | { family: \"unknown\" };\n\n/** ISO-BMFF brands that declare an IMAGE-item file (HEIF family). Resolved via\n *  decoder proof BEFORE the timed-video rule — see the AVIF note above. */\nconst ISOBMFF_IMAGE_BRANDS = new Set([\"avif\", \"avis\", \"heic\", \"heix\", \"heim\", \"heis\", \"hevc\", \"hevx\", \"mif1\", \"msf1\"]);\n\nfunction ascii(b: Uint8Array, off: number, s: string): boolean {\n  if (off + s.length > b.length) return false;\n  for (let i = 0; i < s.length; i++) if (b[off + i] !== s.charCodeAt(i)) return false;\n  return true;\n}\n\nexport function detectSignatureFamily(b: Uint8Array): SignatureFamily {\n  if (b.length < 12) return { family: \"unknown\" };\n  // images (single-format signatures)\n  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return { family: \"image\", formatId: \"jpeg\", container: \"jpeg\" };\n  if (b[0] === 0x89 && ascii(b, 1, \"PNG\")) return { family: \"image\", formatId: \"png\", container: \"png\" };\n  if (ascii(b, 0, \"GIF8\")) return { family: \"image\", formatId: \"gif\", container: \"gif\" };\n  if (ascii(b, 0, \"RIFF\") && ascii(b, 8, \"WEBP\")) return { family: \"image\", formatId: \"webp\", container: \"webp\" };\n  if (b[0] === 0x42 && b[1] === 0x4d) return { family: \"image\", formatId: \"bmp\", container: \"bmp\" };\n  if ((b[0] === 0x49 && b[1] === 0x49 && b[2] === 0x2a) || (b[0] === 0x4d && b[1] === 0x4d && b[3] === 0x2a)) {\n    return { family: \"image\", formatId: \"tiff\", container: \"tiff\" };\n  }\n  // SVG: XML text — scan a short prefix for '<svg' (bounded; case-insensitive).\n  {\n    const prefix = Buffer.from(b.slice(0, Math.min(b.length, 4096)))\n      .toString(\"latin1\")\n      .toLowerCase();\n    if (prefix.includes(\"<svg\") && (prefix.trimStart().startsWith(\"<?xml\") || prefix.trimStart().startsWith(\"<svg\") || prefix.includes(\"<!doctype svg\"))) {\n      return { family: \"svg\" };\n    }\n  }\n  // containers\n  if (b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3) return { family: \"ebml\" };\n  if (ascii(b, 4, \"ftyp\")) {\n    const brand = String.fromCharCode(b[8], b[9], b[10], b[11]).trim().toLowerCase();\n    return { family: \"isobmff\", brand };\n  }\n  if (ascii(b, 0, \"OggS\")) return { family: \"ogg\" };\n  if (ascii(b, 0, \"RIFF\") && ascii(b, 8, \"AVI \")) return { family: \"avi\" };\n  if (ascii(b, 0, \"RIFF\") && ascii(b, 8, \"WAVE\")) return { family: \"wav\" };\n  if (ascii(b, 0, \"ID3\")) return { family: \"mp3\" };\n  if (b[0] === 0xff && (b[1] & 0xe0) === 0xe0) return { family: \"mp3\" };\n  if (ascii(b, 0, \"fLaC\")) return { family: \"flac\" };\n  return { family: \"unknown\" };\n}\n\n// ---- dependency seams (tests inject; production uses the real tools) ----\n\nexport interface InspectMediaDeps {\n  /** Probe the local file; default shells to the hardened `ffprobe`. */\n  probe?: (localPath: string, opts: { timeoutMs: number; signal?: AbortSignal }) => Promise<\n    | { ok: true; json: unknown }\n    | { ok: false; reason: \"timeout\" | \"truncated\" | \"failed\" | \"bad_json\" }\n  >;\n  /** Decode-prove an image; default uses sharp metadata. Returns frame count\n   *  (pages) on success, null on decode failure. */\n  decodeImage?: (localPath: string) => Promise<{ frames: number } | null>;\n  /** Injected ffprobe version (default: cached `ffprobe -version` first line). */\n  ffprobeVersion?: string;\n}\n\nlet cachedFfprobeVersion: string | null | undefined;\n\nasync function getFfprobeVersion(): Promise<string | undefined> {\n  if (cachedFfprobeVersion !== undefined) return cachedFfprobeVersion ?? undefined;\n  try {\n    const r = await runCmd(\"ffprobe\", [\"-version\"], { timeoutMs: 5_000 });\n    const first = (r.stdout || r.stderr).split(/\\r?\\n/)[0]?.trim() ?? \"\";\n    cachedFfprobeVersion = first ? first.slice(0, 120) : null;\n  } catch {\n    cachedFfprobeVersion = null;\n  }\n  return cachedFfprobeVersion ?? undefined;\n}\n\nasync function defaultProbe(\n  localPath: string,\n  opts: { timeoutMs: number; signal?: AbortSignal },\n): Promise<{ ok: true; json: unknown } | { ok: false; reason: \"timeout\" | \"truncated\" | \"failed\" | \"bad_json\" }> {\n  let r;\n  try {\n    r = await runCmd(\n      \"ffprobe\",\n      [\n        \"-v\",\n        \"error\",\n        \"-print_format\",\n        \"json\",\n        \"-show_format\",\n        \"-show_streams\",\n        \"-probesize\",\n        String(PROBE_SIZE_BYTES),\n        \"-analyzeduration\",\n        String(ANALYZE_DURATION_US),\n        localPath,\n      ],\n      { timeoutMs: opts.timeoutMs, signal: opts.signal },\n    );\n  } catch {\n    return { ok: false, reason: \"failed\" }; // spawn failure (ffprobe missing) — fail closed\n  }\n  if (r.timedOut) return { ok: false, reason: \"timeout\" };\n  if (r.truncated) return { ok: false, reason: \"truncated\" };\n  if (r.code !== 0) return { ok: false, reason: \"failed\" };\n  try {\n    return { ok: true, json: JSON.parse(r.stdout || \"{}\") };\n  } catch {\n    return { ok: false, reason: \"bad_json\" };\n  }\n}\n\nasync function defaultDecodeImage(localPath: string): Promise<{ frames: number } | null> {\n  try {\n    const sharp = (await import(\"sharp\")).default;\n    const meta = await sharp(localPath, { limitInputPixels: 268402689 /* sharp default ~16k x 16k */ }).metadata();\n    if (!meta.width || !meta.height) return null;\n    return { frames: Math.max(1, meta.pages ?? 1) };\n  } catch {\n    return null;\n  }\n}\n\n// ---- result builders ----\n\nfunction baseResult(\n  partial: Omit<MediaInspectionResult, \"inspectorVersion\" | \"streams\" | \"codecs\"> &\n    Partial<Pick<MediaInspectionResult, \"streams\" | \"codecs\">>,\n  ffprobeVersion: string | undefined,\n): MediaInspectionResult {\n  const result: MediaInspectionResult = {\n    inspectorVersion: INSPECTOR_VERSION,\n    ...(ffprobeVersion ? { ffprobeVersion } : {}),\n    streams: partial.streams ?? { audio: 0, timedVideo: 0, attachedPictures: 0, imageFrames: 0, auxiliary: 0 },\n    codecs: partial.codecs ?? { audio: [], video: [] },\n    status: partial.status,\n    container: partial.container,\n    safetyPlan: partial.safetyPlan,\n    reasonCode: partial.reasonCode,\n    ...(partial.canonicalKind ? { canonicalKind: partial.canonicalKind } : {}),\n    ...(partial.formatId ? { formatId: partial.formatId } : {}),\n  };\n  return MediaInspectionResultSchema.parse(result);\n}\n\nfunction indeterminate(\n  container: string,\n  reasonCode: string,\n  ffprobeVersion: string | undefined,\n  formatId?: MediaFormatId,\n): MediaInspectionResult {\n  return baseResult(\n    {\n      status: \"indeterminate\",\n      container,\n      safetyPlan: \"strict-video-fallback\",\n      reasonCode,\n      ...(formatId ? { formatId } : {}),\n    },\n    ffprobeVersion,\n  );\n}\n\n// ---- the inspector ----\n\nexport interface InspectMediaArgs {\n  localPath: string;\n  timeoutMs?: number;\n  signal?: AbortSignal;\n  deps?: InspectMediaDeps;\n}\n\nexport async function inspectMedia(args: InspectMediaArgs): Promise<MediaInspectionResult> {\n  const timeoutMs = args.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;\n  const probe = args.deps?.probe ?? defaultProbe;\n  const decodeImage = args.deps?.decodeImage ?? defaultDecodeImage;\n  const ffprobeVersion = args.deps?.ffprobeVersion ?? (await getFfprobeVersion());\n\n  // 1) bounded signature read (header only)\n  let head: Uint8Array;\n  try {\n    const fh = await open(args.localPath, \"r\");\n    try {\n      const buf = Buffer.alloc(SIGNATURE_READ_BYTES);\n      const { bytesRead } = await fh.read(buf, 0, SIGNATURE_READ_BYTES, 0);\n      head = buf.subarray(0, bytesRead);\n    } finally {\n      await fh.close();\n    }\n  } catch {\n    return indeterminate(\"unknown\", \"read_failed\", ffprobeVersion);\n  }\n\n  const sig = detectSignatureFamily(head);\n\n  // 2) family routing\n  switch (sig.family) {\n    case \"unknown\":\n      return indeterminate(\"unknown\", \"unrecognized_signature\", ffprobeVersion);\n\n    case \"svg\":\n      // Scriptable XML \"image\" — structurally recognized, deliberately NOT a\n      // processable format until a sanitize/rasterize design exists (launch\n      // policy 2026-07-31). Never classified by decoder capability alone.\n      return baseResult(\n        {\n          status: \"unsupported\",\n          container: \"svg\",\n          formatId: \"svg\",\n          safetyPlan: \"strict-video-fallback\",\n          reasonCode: \"unsupported_format:svg\",\n        },\n        ffprobeVersion,\n      );\n\n    case \"image\": {\n      // Single-format image signature: decoder proof required — a signature is\n      // a candidate, not a classification.\n      const decoded = await decodeImage(args.localPath);\n      if (!decoded) return baseResult(\n        { status: \"malformed\", container: sig.container, formatId: sig.formatId, safetyPlan: \"strict-video-fallback\", reasonCode: \"image_decode_failed\" },\n        ffprobeVersion,\n      );\n      const frames = decoded.frames;\n      return baseResult(\n        {\n          status: \"definitive\",\n          canonicalKind: \"image\",\n          container: sig.container,\n          formatId: sig.formatId,\n          streams: { audio: 0, timedVideo: 0, attachedPictures: 0, imageFrames: frames, auxiliary: 0 },\n          safetyPlan: frames > 1 ? \"animated-image-frames\" : \"still-image\",\n          reasonCode: \"ok\",\n        },\n        ffprobeVersion,\n      );\n    }\n\n    case \"isobmff\":\n      if (ISOBMFF_IMAGE_BRANDS.has(sig.brand)) {\n        // IMAGE-FAMILY ISO-BMFF resolves BEFORE the timed-video rule: a valid\n        // AVIF probes as a one-frame AV1 `video` stream. Proof = image brand +\n        // successful bounded decode + no ordinary timed A/V presentation.\n        const probed = await probe(args.localPath, { timeoutMs, signal: args.signal });\n        const parsed = probed.ok ? ProbeJsonSchema.safeParse(probed.json) : null;\n        const streams = parsed?.success ? parsed.data.streams ?? [] : null;\n        const hasAudio = streams ? streams.some((s) => s.codec_type === \"audio\") : true; // unknown ⇒ assume worst\n        const formatId: MediaFormatId | undefined = sig.brand.startsWith(\"avi\") ? \"avif\" : \"heic\";\n        const decoded = await decodeImage(args.localPath);\n        if (!decoded || hasAudio) {\n          if (formatId === \"heic\" && !decoded && !hasAudio) {\n            // Recognized HEIC-family that the runtime cannot decode: explicit\n            // unsupported-image (launch policy) — NEVER relabeled video.\n            return baseResult(\n              { status: \"unsupported\", container: \"heif\", formatId, safetyPlan: \"strict-video-fallback\", reasonCode: \"unsupported_format:heic\" },\n              ffprobeVersion,\n            );\n          }\n          // Undecodable/ambiguous image-brand file, or one carrying audio (a\n          // real timed presentation wearing an image brand): fail toward the\n          // stricter visual path.\n          return indeterminate(\"heif\", decoded ? \"image_brand_with_audio\" : \"image_decode_failed\", ffprobeVersion, formatId);\n        }\n        const frames = decoded.frames;\n        return baseResult(\n          {\n            status: \"definitive\",\n            canonicalKind: \"image\",\n            container: \"heif\",\n            formatId,\n            streams: { audio: 0, timedVideo: 0, attachedPictures: 0, imageFrames: frames, auxiliary: 0 },\n            safetyPlan: frames > 1 ? \"animated-image-frames\" : \"still-image\",\n            reasonCode: \"ok\",\n          },\n          ffprobeVersion,\n        );\n      }\n      return classifyAvContainer(args, \"isobmff\", \"isobmff\", probe, timeoutMs, ffprobeVersion);\n\n    case \"ebml\":\n      return classifyAvContainer(args, \"webm\", \"webm\", probe, timeoutMs, ffprobeVersion);\n    case \"ogg\":\n      return classifyAvContainer(args, \"ogg\", \"ogg\", probe, timeoutMs, ffprobeVersion);\n    case \"avi\":\n      // Real container ffprobe parses; no registry entry (no origin enables it\n      // today) — the stream truth still classifies it, policy rejects by format.\n      return classifyAvContainer(args, \"avi\", undefined, probe, timeoutMs, ffprobeVersion);\n    case \"wav\":\n      return classifyAvContainer(args, \"wav\", \"wav\", probe, timeoutMs, ffprobeVersion);\n    case \"mp3\":\n      return classifyAvContainer(args, \"mp3\", \"mp3\", probe, timeoutMs, ffprobeVersion);\n    case \"flac\":\n      return classifyAvContainer(args, \"flac\", \"flac\", probe, timeoutMs, ffprobeVersion);\n  }\n}\n\nasync function classifyAvContainer(\n  args: InspectMediaArgs,\n  container: string,\n  formatId: MediaFormatId | undefined,\n  probe: NonNullable<InspectMediaDeps[\"probe\"]>,\n  timeoutMs: number,\n  ffprobeVersion: string | undefined,\n): Promise<MediaInspectionResult> {\n  const probed = await probe(args.localPath, { timeoutMs, signal: args.signal });\n  if (!probed.ok) {\n    return indeterminate(container, `probe_${probed.reason}`, ffprobeVersion, formatId);\n  }\n  const parsed = ProbeJsonSchema.safeParse(probed.json);\n  if (!parsed.success) return indeterminate(container, \"probe_schema_invalid\", ffprobeVersion, formatId);\n\n  const rawStreams = parsed.data.streams ?? [];\n  if (rawStreams.length === 0) return indeterminate(container, \"no_streams\", ffprobeVersion, formatId);\n\n  const counts: MediaInspectionStreams = { audio: 0, timedVideo: 0, attachedPictures: 0, imageFrames: 0, auxiliary: 0 };\n  const audioCodecs = new Set<NormalizedCodecId>();\n  const videoCodecs = new Set<NormalizedCodecId>();\n  let sawUnknownType = false;\n\n  for (const s of rawStreams) {\n    const type = s.codec_type ?? \"\";\n    if (type === \"audio\") {\n      counts.audio++;\n      audioCodecs.add(normalizeCodec(s.codec_name));\n    } else if (type === \"video\") {\n      // An attached picture (cover art) is NOT a timed presentation — but the\n      // disposition flag is untrusted container data, so it is COUNTED and the\n      // safety plan forces every such picture through the image hash path\n      // before the audio guard may return clean.\n      if (s.disposition?.attached_pic === 1) {\n        counts.attachedPictures++;\n      } else {\n        counts.timedVideo++;\n        videoCodecs.add(normalizeCodec(s.codec_name));\n      }\n    } else if (type === \"subtitle\" || type === \"data\" || type === \"attachment\") {\n      counts.auxiliary++;\n    } else {\n      counts.auxiliary++;\n      sawUnknownType = true;\n    }\n  }\n\n  const codecs = { audio: [...audioCodecs], video: [...videoCodecs] };\n\n  // classification table (fail-closed)\n  if (counts.timedVideo > 0) {\n    return baseResult(\n      {\n        status: \"definitive\",\n        canonicalKind: \"video\",\n        container,\n        ...(formatId ? { formatId } : {}),\n        streams: counts,\n        codecs,\n        safetyPlan: \"video-frames\",\n        reasonCode: \"ok\",\n      },\n      ffprobeVersion,\n    );\n  }\n  if (counts.audio > 0 && !sawUnknownType) {\n    return baseResult(\n      {\n        status: \"definitive\",\n        canonicalKind: \"audio\",\n        container,\n        ...(formatId ? { formatId } : {}),\n        streams: counts,\n        codecs,\n        safetyPlan: counts.attachedPictures > 0 ? \"audio-plus-artwork\" : \"audio-only\",\n        reasonCode: \"ok\",\n      },\n      ffprobeVersion,\n    );\n  }\n  // auxiliary-only, unknown stream types alongside audio, or nothing usable:\n  // never audio — the strict visual fallback owns it.\n  return baseResult(\n    {\n      status: \"indeterminate\",\n      container,\n      ...(formatId ? { formatId } : {}),\n      streams: counts,\n      codecs,\n      safetyPlan: \"strict-video-fallback\",\n      reasonCode: sawUnknownType ? \"unknown_stream_type\" : \"auxiliary_only\",\n    },\n    ffprobeVersion,\n  );\n}\n"]}

package/dist/run-pipeline.d.ts

@@ -1,4 +1,5 @@
-import type { MediaProcessingResult, MediaProcessingSpec } from "@ttt-productions/media-schemas";
+import type { MediaProcessingResult, MediaProcessingSpec, MediaInspectionResult, MediaProcessingError } from "@ttt-productions/media-schemas";
+import { type InspectMediaDeps } from "./inspection/inspect-media.js";
 import type { MediaIO } from "./io/types.js";
 import type { ModerationAdapter } from "./moderation/types.js";
 export interface RunPipelineArgs {
@@ -8,6 +9,33 @@ export interface RunPipelineArgs {
     moderation?: ModerationAdapter;
     signal?: AbortSignal;
     onProgress?: (p: import("./types.js").MediaPipelineProgress) => void;
+    /**
+     * CANONICAL INSPECTION SEAM (canonical-upload-content-classification).
+     * When present, the pipeline runs `inspectMedia` on the just-downloaded temp
+     * input — BEFORE moderation and processing — and calls this policy hook with
+     * the bounded result. The hook either:
+     *   - returns `{ spec }` — the caller's policy adapter selected the
+     *     processing spec FROM the inspection (the byte-derived kind, never the
+     *     client MIME); the pipeline continues with that spec; or
+     *   - returns `{ reject }` — a typed terminal (`kind_mismatch`,
+     *     `unsupported_format`, `unsupported_codec`, …); the pipeline stops
+     *     before any transcode/moderation work.
+     * The inspection result rides the returned `MediaProcessingResult.inspection`
+     * either way, so the finalizer hands the SAME object to the safety gate —
+     * one authority, no re-detection. Callers that omit the hook get the
+     * pre-existing behavior unchanged.
+     */
+    resolveAfterInspection?: (inspection: MediaInspectionResult) => Promise<{
+        spec: MediaProcessingSpec;
+    } | {
+        reject: MediaProcessingError;
+    }> | ({
+        spec: MediaProcessingSpec;
+    } | {
+        reject: MediaProcessingError;
+    });
+    /** Inspection tool overrides (tests). */
+    inspectionDeps?: InspectMediaDeps;
 }
 export declare function runMediaPipeline(args: RunPipelineArgs): Promise<MediaProcessingResult>;
 //# sourceMappingURL=run-pipeline.d.ts.map

package/dist/run-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-pipeline.d.ts","sourceRoot":"","sources":["../src/run-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,qBAAqB,EACrB,mBAAmB,EAEpB,MAAM,gCAAgC,CAAC;AAIxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAK/D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,YAAY,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACpE;AAiBD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA2M5F"}
+{"version":3,"file":"run-pipeline.d.ts","sourceRoot":"","sources":["../src/run-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,qBAAqB,EACrB,mBAAmB,EAEnB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACpF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAK/D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,iBAAiB,CAAC;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,YAAY,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACrE;;;;;;;;;;;;;;;OAeG;IACH,sBAAsB,CAAC,EAAE,CACvB,UAAU,EAAE,qBAAqB,KAC9B,OAAO,CAAC;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,oBAAoB,CAAA;KAAE,CAAC,GAAG,CAAC;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,GAAG;QAAE,MAAM,EAAE,oBAAoB,CAAA;KAAE,CAAC,CAAC;IACpJ,yCAAyC;IACzC,cAAc,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAiBD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgP5F"}