nixamp 0.17.0 → 0.18.0

package/dist/compression/benchmark.js

@@ -0,0 +1,241 @@
+/**
+ * The OpenStream benchmark: what a codec makes of a defined corpus, on this
+ * machine, with every number reproducible and nothing claimed that was not
+ * measured.
+ *
+ * It proves the honest things: that decompression restores every byte, that
+ * an incompressible sample costs only the envelope overhead and never more,
+ * that a compressible one saves what it says against the complete wire size,
+ * and how long each takes. It does not prove a production saving -- a
+ * synthetic padded stream compresses to almost nothing, which says more about
+ * the padding than the codec, and the report labels it so. Point it at real
+ * authorized samples with `--corpus` for numbers that mean something.
+ *
+ * The corpus is built from bytes alone by default, so anyone can run it with
+ * no ffmpeg and no media: random data, zeros, repetitive text, tiny and empty
+ * inputs, and hand-built transport-stream packets with a known share of null
+ * padding. ffmpeg, when present, adds real encoded media; a directory of your
+ * own files replaces the lot.
+ */
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { arch, cpus, platform, release, totalmem } from "node:os";
+import { join } from "node:path";
+import { benchmark } from "./analyze.js";
+import { toolVersions } from "./codec.js";
+import { ENVELOPE_VERSION, FRAME_HEADER_BYTES, MAGIC, STREAM_HEADER_BYTES } from "./envelope.js";
+import { DEFAULT_LOSSLESS } from "./policy.js";
+import { SYNC, TS_PACKET } from "./ts-transform.js";
+/** The report schema version, bumped when the shape below changes. */
+export const REPORT_SCHEMA = 1;
+/**
+ * A deterministic, genuinely incompressible fill: a SHA-256 keystream from a
+ * fixed seed. Reproducible byte-for-byte across runs (so two reports compare)
+ * and uncompressible (so the "floor" sample is really the floor, unlike a
+ * linear-congruential stream, whose periodicity a compressor crushes).
+ */
+function keystream(size, seed) {
+    const out = Buffer.alloc(size);
+    let block = createHash("sha256").update(seed).digest();
+    let at = 0;
+    while (at < size) {
+        const take = Math.min(block.length, size - at);
+        block.copy(out, at, 0, take);
+        at += take;
+        block = createHash("sha256").update(block).digest();
+    }
+    return out;
+}
+/** Transport-stream packets, a given share of them null padding, payloads incompressible. */
+function fakeTs(packets, nullEvery, seed = "ts") {
+    const out = Buffer.alloc(packets * TS_PACKET);
+    const fill = keystream(packets * TS_PACKET, seed);
+    for (let i = 0; i < packets; i += 1) {
+        const at = i * TS_PACKET;
+        const isNull = nullEvery > 0 && i % nullEvery === 0;
+        const pid = isNull ? 0x1fff : [0x100, 0x101, 0x102][i % 3];
+        out[at] = SYNC;
+        out[at + 1] = (pid >> 8) & 0x1f;
+        out[at + 2] = pid & 0xff;
+        out[at + 3] = 0x10 | (i & 0xf);
+        for (let j = at + 4; j < at + TS_PACKET; j += 1)
+            out[j] = isNull ? 0xff : fill[j];
+    }
+    return out;
+}
+/** The default corpus: bytes only, no ffmpeg, deterministic. */
+export function syntheticCorpus() {
+    return [
+        { name: "random-1mib", kind: "synthetic", bytes: keystream(1024 * 1024, "random"), notes: "incompressible: the floor, where a codec must not grow the data beyond envelope overhead" },
+        { name: "zeros-1mib", kind: "synthetic", bytes: Buffer.alloc(1024 * 1024, 0), notes: "maximally compressible: the ceiling" },
+        { name: "text-repeat-1mib", kind: "synthetic", bytes: Buffer.from("the quick brown fox jumps over the lazy dog\n".repeat(24000)).subarray(0, 1024 * 1024), notes: "repetitive text: ordinary redundancy" },
+        { name: "ts-padded-50pct", kind: "synthetic", bytes: fakeTs(4000, 2), notes: "transport stream, half null packets: padding a copy must keep and a codec removes; the synthetic case that flatters a codec" },
+        { name: "ts-unpadded", kind: "synthetic", bytes: fakeTs(4000, 0), notes: "transport stream, no padding: closer to an efficient real feed" },
+        { name: "tiny-3b", kind: "synthetic", bytes: Buffer.from("abc"), notes: "smaller than a frame header: proves overhead is reported honestly" },
+        { name: "empty", kind: "synthetic", bytes: Buffer.alloc(0), notes: "the empty stream" },
+    ];
+}
+/** Real files a runner points us at, each read whole (capped) as a sample. */
+export function fileCorpus(dir, capBytes = 64 * 1024 * 1024) {
+    const out = [];
+    for (const name of readdirSync(dir).sort()) {
+        const path = join(dir, name);
+        try {
+            if (!statSync(path).isFile())
+                continue;
+            const whole = readFileSync(path);
+            out.push({ name, kind: "real", bytes: whole.subarray(0, capBytes), notes: whole.length > capBytes ? `real file, first ${capBytes} bytes of ${whole.length}` : "real file" });
+        }
+        catch {
+            // Unreadable entries are skipped, not fatal.
+        }
+    }
+    return out;
+}
+/** Run the corpus and build the report. */
+export async function runBenchmark(corpus, options) {
+    const zstdLevels = options.zstdLevels ?? [1, 3, 9];
+    const blockBytes = options.blockBytes ?? DEFAULT_LOSSLESS.maxBlockBytes;
+    const policy = { minSavingsPercent: DEFAULT_LOSSLESS.minSavingsPercent, minSavingsBytes: DEFAULT_LOSSLESS.minSavingsBytes };
+    const samples = [];
+    for (const sample of corpus) {
+        if (options.signal?.aborted)
+            break;
+        const rows = await benchmark(sample.bytes, { blockBytes, zstdLevels, tsAware: true, policy, ...(options.signal ? { signal: options.signal } : {}) });
+        const stored = rows.find((r) => r.mode === "stored");
+        const best = rows.filter((r) => r.roundTrip && r.mode !== "stored").sort((a, b) => a.wireBytes - b.wireBytes)[0];
+        const beats = stored && best && stored.wireBytes - best.wireBytes >= policy.minSavingsBytes && ((stored.wireBytes - best.wireBytes) * 100) / stored.wireBytes >= policy.minSavingsPercent;
+        samples.push({
+            sample: sample.name,
+            kind: sample.kind,
+            inputBytes: sample.bytes.length,
+            sha256: createHash("sha256").update(sample.bytes).digest("hex"),
+            container: rows.length ? sniff(sample.bytes) : "empty",
+            rows,
+            recommendation: beats && best
+                ? { mode: best.mode, level: best.level, reason: `saves ${best.savingsPercent}% of the complete wire size` }
+                : { mode: "stored", level: 0, reason: "no codec beat stored by the configured margin" },
+        });
+    }
+    const byMode = aggregate(samples);
+    const cpu = cpus()[0]?.model ?? "unknown";
+    return {
+        schema: REPORT_SCHEMA,
+        spec: "openstream",
+        specVersion: MAGIC,
+        generatedAt: new Date().toISOString(),
+        implementation: { name: "nixamp", version: options.implementationVersion },
+        environment: {
+            ...toolVersions(),
+            os: `${platform()} ${release()}`,
+            arch: arch(),
+            cpu,
+            cores: cpus().length,
+            memoryGiB: Math.round((totalmem() / 1024 ** 3) * 10) / 10,
+        },
+        envelope: { magic: MAGIC, streamHeaderBytes: STREAM_HEADER_BYTES, frameHeaderBytes: FRAME_HEADER_BYTES },
+        policy: { ...policy, maxBlockBytes: blockBytes, zstdLevels },
+        samples,
+        summary: { corpusBytes: corpus.reduce((n, s) => n + s.bytes.length, 0), byMode },
+        caveats: [
+            `Envelope v${ENVELOPE_VERSION}: a ${STREAM_HEADER_BYTES}-byte stream header, a ${FRAME_HEADER_BYTES}-byte header per frame, plus one end frame.`,
+            "OpenStream is a framing envelope over Zstandard and gzip, not a new compression algorithm; these numbers are those codecs at the block boundary, honestly framed.",
+            "Synthetic samples do not predict production savings. A padded transport stream flatters a codec by its padding; an efficient real feed saves far less. Use --corpus with authorized real samples for numbers that mean something.",
+            "Timings are wall-clock on the machine and runtime named in `environment` and do not transfer to other hardware.",
+            "roundTrip:false in any row is a failure of exactness and must block a release.",
+        ],
+    };
+}
+function sniff(bytes) {
+    // A light container guess for the report; the full analyzer is elsewhere.
+    if (bytes.length >= 8 && bytes.toString("latin1", 4, 8) === "ftyp")
+        return "mp4";
+    if (bytes.length >= TS_PACKET && bytes[0] === SYNC && bytes[TS_PACKET] === SYNC)
+        return "mpegts";
+    return "bytes";
+}
+function aggregate(samples) {
+    const modes = new Map();
+    for (const sample of samples) {
+        for (const row of sample.rows) {
+            // A row with a note is a mode that did not apply to this sample (ts-zstd
+            // on non-transport bytes, say). It is not a saving and not a failure, so
+            // it is left out of the aggregate rather than dragging a mode down.
+            if (row.note)
+                continue;
+            const key = `${row.mode}:${row.level}`;
+            const acc = modes.get(key) ?? { mode: row.mode, level: row.level, wireBytes: 0, input: 0, roundTrip: true, encodeMs: 0, decodeMs: 0 };
+            acc.wireBytes += row.wireBytes;
+            acc.input += row.inputBytes;
+            acc.roundTrip = acc.roundTrip && row.roundTrip;
+            acc.encodeMs += row.encodeMs;
+            acc.decodeMs += row.decodeMs;
+            modes.set(key, acc);
+        }
+    }
+    return [...modes.values()].map((m) => ({
+        mode: m.mode,
+        level: m.level,
+        wireBytes: m.wireBytes,
+        savingsPercent: m.input === 0 ? 0 : Math.round(((m.input - m.wireBytes) * 100) / m.input * 100) / 100,
+        roundTrip: m.roundTrip,
+        encodeMs: Math.round(m.encodeMs * 100) / 100,
+        decodeMs: Math.round(m.decodeMs * 100) / 100,
+    }));
+}
+/** The report as Markdown, for a human and for the reports page. */
+export function reportMarkdown(report) {
+    const e = report.environment;
+    const lines = [];
+    lines.push(`# OpenStream benchmark — ${report.implementation.name} ${report.implementation.version}`);
+    lines.push("");
+    lines.push(`Generated ${report.generatedAt} · envelope ${report.specVersion} · schema ${report.schema}`);
+    lines.push("");
+    lines.push(`**Environment.** ${e.runtime}, zstd ${e.zstd}, zlib ${e.zlib}, on ${e.os} ${e.arch}, ${e.cores}× ${e.cpu}, ${e.memoryGiB} GiB.`);
+    lines.push("");
+    lines.push(`**Policy.** block ${report.policy.maxBlockBytes} B; eligible at ${report.policy.minSavingsPercent}% and ${report.policy.minSavingsBytes} B; zstd levels ${report.policy.zstdLevels.join(", ")}.`);
+    lines.push("");
+    lines.push("## Corpus");
+    lines.push("");
+    lines.push("| sample | kind | bytes | container | best mode | saves |");
+    lines.push("| --- | --- | ---: | --- | --- | ---: |");
+    for (const s of report.samples) {
+        const best = s.rows.filter((r) => r.roundTrip && r.mode !== "stored").sort((a, b) => a.wireBytes - b.wireBytes)[0];
+        const saves = s.recommendation.mode === "stored" ? "stored" : `${best?.savingsPercent ?? 0}%`;
+        lines.push(`| ${s.sample} | ${s.kind} | ${s.inputBytes} | ${s.container} | ${s.recommendation.mode}${s.recommendation.level ? ` L${s.recommendation.level}` : ""} | ${saves} |`);
+    }
+    lines.push("");
+    lines.push("## Aggregate, per mode across the corpus");
+    lines.push("");
+    lines.push("| mode | wire bytes | saving | enc ms | dec ms | round trip |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | --- |");
+    for (const m of report.summary.byMode) {
+        lines.push(`| ${m.mode}${m.level ? ` L${m.level}` : ""} | ${m.wireBytes} | ${m.savingsPercent >= 0 ? "+" : ""}${m.savingsPercent}% | ${m.encodeMs} | ${m.decodeMs} | ${m.roundTrip ? "ok" : "FAILED"} |`);
+    }
+    lines.push("");
+    lines.push("## Caveats");
+    lines.push("");
+    for (const c of report.caveats)
+        lines.push(`- ${c}`);
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Whether every applicable codec restored exactly: the gate a release must
+ * pass. A row with a note is a mode that did not apply to that sample, not a
+ * corrupted round trip, so it does not fail the gate.
+ */
+export function reportPasses(report) {
+    return report.samples.every((s) => s.rows.every((r) => r.roundTrip || Boolean(r.note)));
+}
+/** The rows that are a real exactness failure: ran, and did not restore. */
+export function exactnessFailures(report) {
+    const out = [];
+    for (const s of report.samples) {
+        for (const r of s.rows) {
+            if (!r.roundTrip && !r.note)
+                out.push({ sample: s.sample, mode: r.mode, level: r.level });
+        }
+    }
+    return out;
+}

package/dist/compression/cli.js

@@ -16,10 +16,13 @@
  * `nixamp admin` finds its target. JSON goes to stdout and only JSON;
  * progress and complaints go to stderr; a failure is a nonzero exit.
  */
-import { createWriteStream } from "node:fs";
+import { createWriteStream, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { resolveTarget } from "../admin.js";
 import { detectTools } from "../audio.js";
+import { version as nixampVersion } from "../meta.js";
 import { KEY_HEADER } from "../share.js";
+import { exactnessFailures, fileCorpus, reportMarkdown, reportPasses, runBenchmark, syntheticCorpus } from "./benchmark.js";
 import { RelayError } from "./envelope.js";
 import { receiveRelay, RelayRefused } from "./receiver.js";
 import { analyzeFile } from "./service.js";
@@ -33,6 +36,8 @@ const USAGE = `nixamp compression — lossless relay compression: measure it, se
   nixamp compression off | on          the whole server's switch
   nixamp compression pull --channel ID --from URL [--from-key KEY] [--name NAME]
   nixamp compression fetch URL --out FILE [--key KEY]
+  nixamp compression benchmark [--corpus DIR] [--out DIR] [--levels 1,3,9]
+                   prove the envelope on a corpus and write a report; no server or ffmpeg needed
 
   --url U --key K  a server other than the local daemon, as for \`nixamp admin\`
   --format json    JSON on stdout (the default when stdout is not a terminal)
@@ -315,6 +320,56 @@ async function fetchRelay(flags) {
         return 1;
     }
 }
+/**
+ * Run the OpenStream benchmark and write a report. Anyone can run it: the
+ * default corpus is bytes we generate, no server and no ffmpeg. `--corpus DIR`
+ * benchmarks a directory of real files instead; `--out DIR` writes
+ * `openstream-report.json` and `.md` there for publishing.
+ */
+async function bench(flags) {
+    const dir = flags.named.get("corpus");
+    let corpus;
+    try {
+        corpus = dir ? fileCorpus(dir) : syntheticCorpus();
+    }
+    catch (error) {
+        console.error(`nixamp: cannot read corpus ${dir}: ${error.message}`);
+        return 1;
+    }
+    if (corpus.length === 0) {
+        console.error(`nixamp: no samples${dir ? ` in ${dir}` : ""}`);
+        return 1;
+    }
+    console.error(`  Benchmarking ${corpus.length} sample${corpus.length === 1 ? "" : "s"}${dir ? ` from ${dir}` : " (synthetic)"}…`);
+    const levels = flags.named.get("levels");
+    const report = await runBenchmark(corpus, {
+        implementationVersion: nixampVersion(),
+        ...(levels ? { zstdLevels: levels.split(",").map((n) => Number(n)).filter((n) => Number.isInteger(n)) } : {}),
+    });
+    const out = flags.named.get("out");
+    if (out) {
+        try {
+            mkdirSync(out, { recursive: true });
+            writeFileSync(join(out, "openstream-report.json"), JSON.stringify(report, null, 2));
+            writeFileSync(join(out, "openstream-report.md"), reportMarkdown(report));
+            console.error(`  Wrote openstream-report.json and .md to ${out}`);
+        }
+        catch (error) {
+            console.error(`nixamp: cannot write to ${out}: ${error.message}`);
+            return 1;
+        }
+    }
+    if (wantsJson(flags))
+        console.log(JSON.stringify(report, null, 2));
+    else
+        console.log(reportMarkdown(report));
+    if (!reportPasses(report)) {
+        const bad = exactnessFailures(report).map((f) => `${f.sample}/${f.mode}${f.level ? `L${f.level}` : ""}`).join(", ");
+        console.error(`nixamp: these did not restore byte-for-byte, this build must not ship: ${bad}`);
+        return 1;
+    }
+    return 0;
+}
 export async function compression(argv) {
     const flags = parse(argv);
     const verb = flags.positional[0];
@@ -335,6 +390,9 @@ export async function compression(argv) {
                 return await pull(flags);
             case "fetch":
                 return await fetchRelay(flags);
+            case "benchmark":
+            case "bench":
+                return await bench(flags);
             default:
                 console.error(USAGE);
                 return verb === undefined || verb === "help" || flags.named.has("help") ? 0 : 2;

package/dist/compression/receiver.d.ts

@@ -10,10 +10,33 @@
  * which is surfaced as an error naming the reason, never as a stream of
  * something else.
  */
-import { type Mode, type StreamHeader } from "./envelope.ts";
+import { type Boundary, type Mode, type StreamHeader } from "./envelope.ts";
 export declare const CODECS_HEADER = "x-nixamp-stream-codecs";
 export declare const KIND_HEADER = "x-nixamp-kind";
+export declare const BOUNDARY_HEADER = "x-nixamp-boundary";
+/** What the media inside is, as JSON: video, audio, container, duration. */
+export declare const MEDIA_HEADER = "x-nixamp-codecs";
 export declare const KEY_HEADER = "x-nixamp-key";
+export interface Media {
+    video: string;
+    audio: string;
+    container: string;
+    duration?: number;
+}
+/** What a server said it would send, read off its response headers. */
+export interface Accepted {
+    codecs: string;
+    kind: "audio" | "video" | "";
+    boundary: Boundary | "";
+    media: Media | null;
+}
+/**
+ * Ask a relay what it would send, without taking it: the negotiation
+ * headers come back on the response and the body is cancelled at once.
+ * Costs one short connection; a receiver needs to know the boundary and
+ * the media before it can decide how to carry the stream.
+ */
+export declare function probeRelay(url: string, key: string | null, fetchImpl?: typeof fetch): Promise<Accepted>;
 export interface ReceiveOptions {
     url: string;
     key: string | null;
@@ -21,10 +44,7 @@ export interface ReceiveOptions {
     modes?: Mode[];
     maxFrameBytes?: number;
     /** The server said yes: what it will compress with, and what the channel carries. Before any byte. */
-    onStart?: (accepted: {
-        codecs: string;
-        kind: "audio" | "video" | "";
-    }) => void;
+    onStart?: (accepted: Accepted) => void;
     /** The stream header arrived: the generation this is. */
     onHeader?: (header: StreamHeader) => void;
     onBytes: (bytes: Buffer) => void | Promise<void>;

package/dist/compression/receiver.js

@@ -14,7 +14,60 @@ import { MEDIA_TYPE, RelayError } from "./envelope.js";
 import { RelayDecoder } from "./relay.js";
 export const CODECS_HEADER = "x-nixamp-stream-codecs";
 export const KIND_HEADER = "x-nixamp-kind";
+export const BOUNDARY_HEADER = "x-nixamp-boundary";
+/** What the media inside is, as JSON: video, audio, container, duration. */
+export const MEDIA_HEADER = "x-nixamp-codecs";
 export const KEY_HEADER = "x-nixamp-key";
+function acceptedFrom(headers) {
+    const kindSaid = headers.get(KIND_HEADER);
+    const boundarySaid = headers.get(BOUNDARY_HEADER);
+    let media = null;
+    try {
+        const raw = JSON.parse(headers.get(MEDIA_HEADER) ?? "null");
+        if (raw && typeof raw.video === "string" && typeof raw.audio === "string" && typeof raw.container === "string") {
+            media = { video: raw.video, audio: raw.audio, container: raw.container };
+            if (typeof raw.duration === "number")
+                media.duration = raw.duration;
+        }
+    }
+    catch {
+        // Not JSON: no media description, which the receiver copes with.
+    }
+    return {
+        codecs: headers.get(CODECS_HEADER) ?? "",
+        kind: kindSaid === "audio" || kindSaid === "video" ? kindSaid : "",
+        boundary: boundarySaid === "source" || boundarySaid === "channel" ? boundarySaid : "",
+        media,
+    };
+}
+/**
+ * Ask a relay what it would send, without taking it: the negotiation
+ * headers come back on the response and the body is cancelled at once.
+ * Costs one short connection; a receiver needs to know the boundary and
+ * the media before it can decide how to carry the stream.
+ */
+export async function probeRelay(url, key, fetchImpl) {
+    const headers = { accept: MEDIA_TYPE, [CODECS_HEADER]: "stored,zstd,ts-zstd" };
+    if (key)
+        headers[KEY_HEADER] = key;
+    const response = await (fetchImpl ?? fetch)(url, { headers });
+    const type = response.headers.get("content-type") ?? "";
+    if (response.status !== 200 || !type.startsWith(MEDIA_TYPE)) {
+        let reason = `${response.status}`;
+        try {
+            const body = (await response.json());
+            if (typeof body.error === "string")
+                reason = body.error;
+        }
+        catch {
+            // Not JSON; the status is the message.
+        }
+        throw new RelayRefused(response.status, reason);
+    }
+    const accepted = acceptedFrom(response.headers);
+    await response.body?.cancel().catch(() => undefined);
+    return accepted;
+}
 /** The server said no. `status` is what it said it with. */
 export class RelayRefused extends Error {
     status;
@@ -55,11 +108,7 @@ export async function receiveRelay(options) {
     }
     if (!response.body)
         throw new RelayRefused(response.status, "no body");
-    const kindSaid = response.headers.get(KIND_HEADER);
-    options.onStart?.({
-        codecs: response.headers.get(CODECS_HEADER) ?? "",
-        kind: kindSaid === "audio" || kindSaid === "video" ? kindSaid : "",
-    });
+    options.onStart?.(acceptedFrom(response.headers));
     const decoder = new RelayDecoder({
         modes,
         ...(options.maxFrameBytes !== undefined ? { maxFrameBytes: options.maxFrameBytes } : {}),

package/dist/compression/routes.js

@@ -11,7 +11,7 @@
  */
 import { createReadStream } from "node:fs";
 import { MEDIA_TYPE, parseModes } from "./envelope.js";
-import { CODECS_HEADER, KIND_HEADER } from "./receiver.js";
+import { BOUNDARY_HEADER, CODECS_HEADER, KIND_HEADER, MEDIA_HEADER } from "./receiver.js";
 /** Who a diagnostic job belongs to. Every control holder shares them. */
 const CONTROL = "control";
 /** The header a conditional change names the version in, or the body's own field. */
@@ -115,6 +115,11 @@ export async function handleChannelCompression(request, response, ctx, id, actio
                 "content-encoding": "identity",
                 [CODECS_HEADER]: answer.codecs.join(","),
                 [KIND_HEADER]: answer.kind,
+                // Which bytes these are, and what is inside them: a receiver of the
+                // source boundary hands them to its own ffmpeg and needs to know
+                // what ffmpeg will find, without a probe of its own.
+                [BOUNDARY_HEADER]: answer.boundary,
+                ...(answer.media ? { [MEDIA_HEADER]: JSON.stringify(answer.media) } : {}),
                 "x-nixamp-generation": String(answer.generation),
             });
             const leave = () => answer.session.leave();
@@ -135,7 +140,7 @@ export async function handleChannelCompression(request, response, ctx, id, actio
             }
             const key = typeof body?.["key"] === "string" ? body["key"] : null;
             const name = typeof body?.["name"] === "string" ? body["name"] : id;
-            const started = service.pull(id, from, key, name);
+            const started = await service.pull(id, from, key, name);
             if (!started.ok) {
                 json(response, started.status, { error: started.error });
                 return true;

package/dist/compression/service.d.ts

@@ -1,7 +1,7 @@
-import { type Channels } from "../channels.ts";
+import { type ChannelInfo, type Channels } from "../channels.ts";
 import { type Analysis } from "./analyze.ts";
 import { Pool } from "./codec.ts";
-import { type Mode } from "./envelope.ts";
+import { type Boundary, type Mode } from "./envelope.ts";
 import { AnalysisJobs, type Job } from "./jobs.ts";
 import { type ChannelMetricsSnapshot } from "./metrics.ts";
 import { type ChannelPolicy, type LosslessPolicy } from "./policy.ts";
@@ -66,6 +66,9 @@ export type RelayAnswer = {
     codecs: Mode[];
     generation: number;
     kind: "audio" | "video" | "";
+    /** Which bytes the stream carries, and what is inside them. */
+    boundary: Boundary;
+    media: ChannelInfo["codecs"] | null;
 } | {
     ok: false;
     status: 404 | 406 | 409 | 503;
@@ -83,6 +86,8 @@ export declare class CompressionService {
     private readonly incoming;
     private generation;
     constructor(options: CompressionServiceOptions);
+    /** Incoming source-boundary relays, so their channel is read through us. */
+    private readonly relaySource;
     private get channels();
     /** What applies to a channel right now, and why that is not what is configured, if it is not. */
     effective(id: string): EffectivePolicy;
@@ -112,15 +117,22 @@ export declare class CompressionService {
      * anything worth sending.
      */
     relay(id: string, listener: RelayListener, offered: Set<Mode>): RelayAnswer;
+    /** Null: the channel ended. False: the source boundary was asked for but is not being read through us. */
     private startEncoder;
-    /** Start listening to another nixamp's channel as one of ours. */
-    pull(id: string, from: string, key: string | null, name: string): {
+    /**
+     * Start listening to another nixamp's channel as one of ours. Probes the
+     * relay first to learn its boundary: a channel-boundary relay is decoded
+     * and its bytes are the channel's output directly; a source-boundary relay
+     * is the original transport stream, so it is read through ffmpeg here
+     * exactly as a pulled source would be, and can be relayed on again.
+     */
+    pull(id: string, from: string, key: string | null, name: string): Promise<{
         ok: true;
     } | {
         ok: false;
-        status: 409 | 400;
+        status: 409 | 400 | 502;
         error: string;
-    };
+    }>;
     /** Stop an incoming relay, and the channel it feeds. */
     stopPull(id: string): boolean;
     /**