Skip to content

feat(producer): enable the parallel-DE router by default, behind a real circuit breaker #2840

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vanceingalls wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(producer): enable the parallel-DE router by default, behind a real circuit breaker #2840

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
acdae81
feat(producer): enable the parallel-DE router by default, behind a pe…
vanceingalls Jul 28, 2026
0fed335
fix(cli): keep a set-but-empty router env var breaker-managed (review)
vanceingalls Jul 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 78 additions & 71 deletions packages/cli/src/commands/render.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -698,7 +698,7 @@ describe("renderLocal browser GPU config", () => {
});
});

describe("renderLocal — DE parallel-router CLI trial", () => {
describe("renderLocal — DE parallel-router circuit breaker", () => {
let renderLocal: typeof import("./render.js").renderLocal;
let resetTrialState: typeof import("./render.js").__resetDeParallelRouterTrialStateForTests;
const savedEnv = new Map<string, string | undefined>();
Expand Down Expand Up @@ -747,19 +747,22 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
browserGpuMode: "software" as const,
hdrMode: "auto" as const,
quiet: true,
// The trial is OPT-IN (review): only the CLI's own sequential call sites
// set this. These tests simulate those call sites.
enableDeParallelRouterTrial: true,
// Breaker management is OPT-IN (review): only the CLI's own sequential
// call sites set it. These tests simulate those call sites.
manageDeParallelRouterBreaker: true,
};

it("enables the trial (sets the env var) on a fresh install with telemetry on", async () => {
it("leaves the env var untouched on a fresh install — the router is default-ON", async () => {
// Under the old opt-in trial this armed HF_DE_PARALLEL_ROUTER="true".
// The router now ships on, so the breaker's job is to stay out of the
// way until something actually fails.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});

it("does not override an env var the user already set themselves", async () => {
Expand All @@ -773,49 +776,75 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});

it("does not enable the trial once it has already fired for this install", async () => {
it("writes an explicit false once the breaker has tripped for this install", async () => {
// THE regression this rework exists for: the old code disabled the
// router by DELETING the var. With a default-ON router, absent means ON,
// so deleting would silently re-enable it on the very host that just
// failed. Only an explicit "false" is a real off-switch.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: true,
telemetryNoticeShown: true,
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});

it("does not enable the trial when shouldTrack() is false (dev mode / DO_NOT_TRACK)", async () => {
for (const emptyish of ["", " "]) {
it(`treats a set-but-empty env var (${JSON.stringify(emptyish)}) as default, not a user choice`, async () => {
// Both parsers read empty/whitespace as "unset → default ON", so the
// producer routes. If ownership instead treated any defined value as a
// user choice, the breaker would no-op and this install would keep
// retrying a failing router forever — losing the first-fallback
// protection that is the point of the breaker.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
process.env.HF_DE_PARALLEL_ROUTER = emptyish;
producerState.executeImpl = async (job) => {
job.perfSummary = {
resolution: { width: 100, height: 100 },
drawElement: { parallelRouter: "reverted" },
};
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
expect(configState.writeConfigCalls).toContainEqual(
expect.objectContaining({ deParallelRouterTrialFired: true }),
);
});
}

it("does not override an explicit user opt-in even after a fallback", async () => {
// "Explicit user choice wins in both directions" — the opt-in half.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
trackingState.shouldTrack = false;
process.env.HF_DE_PARALLEL_ROUTER = "true";
producerState.executeImpl = async (job) => {
job.perfSummary = {
resolution: { width: 100, height: 100 },
drawElement: { parallelRouter: "reverted" },
};
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
});

it("does not enable the trial when config.telemetryEnabled is false, even if shouldTrack() is stale-true (e.g. `hyperframes telemetry off` mid-batch)", async () => {
it("keeps the router on for a telemetry opt-out — analytics choice must not cost performance", async () => {
// The old trial refused to arm without recordable telemetry (no point
// running an experiment you can't measure). Now that the router is a
// shipped default, gating it on telemetry would punish a privacy choice
// with a slower renderer.
configState.disk = {
telemetryEnabled: false,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
trackingState.shouldTrack = true;
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});

it("does not enable the trial before the first-run telemetry disclosure has been shown at least once", async () => {
// cli.ts shows this notice via a fire-and-forget, unawaited dynamic
// import — there's no guarantee it printed before renderLocal runs on a
// brand-new install's very first invocation. Requiring
// telemetryNoticeShown means the trial never races an opt-in message
// against the disclosure it depends on.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: false,
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});
Expand Down Expand Up @@ -925,11 +954,9 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
});

it("persists a later --batch row's revert even though this process already armed the trial on an earlier row", async () => {
// Regression test for the exact scenario a --batch run hits: multiple
// renderLocal calls in one process. Before the fix, row 2's
// maybeEnableDeParallelRouterTrial saw process.env.HF_DE_PARALLEL_ROUTER
// already "true" (set by row 1) and mistook that for "the user set it",
// returning trialArmed=false — silently dropping row 2's revert.
// The --batch scenario: multiple renderLocal calls in one process. Row 1
// succeeds (breaker stays out of the way, env untouched); row 2 reverts
// and must still be recorded and trip the breaker.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
Expand All @@ -943,7 +970,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
};
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(configState.disk.deParallelRouterTrialFired).toBe(false);

producerState.executeImpl = async (job) => {
Expand All @@ -957,12 +984,14 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
expect(configState.writeConfigCalls).toContainEqual(
expect.objectContaining({ deParallelRouterTrialFired: true }),
);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
// Explicit "false", not deleted: with a default-ON router, unsetting the
// var would re-enable it on the host that just reverted.
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});

it("does not arm the trial for programmatic callers that never opted in (opt-in polarity — also covers --batch-concurrency N>=2, which leaves it unset)", async () => {
// The trial's process-wide env var and module-level flags are only safe
// under sequential invocation, so enableDeParallelRouterTrial is OPT-IN
// under sequential invocation, so manageDeParallelRouterBreaker is OPT-IN
// (review): a programmatic renderLocal consumer that doesn't know about
// the trial must get no trial. The CLI's concurrent-batch path relies on
// the same default by leaving the option unset.
Expand All @@ -971,7 +1000,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
const { enableDeParallelRouterTrial: _omitted, ...programmaticOptions } = baseOptions;
const { manageDeParallelRouterBreaker: _omitted, ...programmaticOptions } = baseOptions;
await renderLocal("/tmp/project", "/tmp/out.mp4", programmaticOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(configState.writeConfigCalls).toHaveLength(0);
Expand All @@ -990,7 +1019,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
};
};
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();

// A real interactive user can't do this mid-batch, but a wrapper script
// invoking the CLI programmatically in the same process could — the
Expand All @@ -1000,7 +1029,10 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});

it("caps exposure at DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS even when the router never reverts", async () => {
it("never trips on healthy renders, however many — the old 25-render cap is gone", async () => {
// The cap was sampling logic for an opt-in experiment. Under a shipped
// default it would switch the feature off behind the user's back after
// 25 good renders.
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
Expand All @@ -1013,40 +1045,14 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
};
};

for (let i = 0; i < 25; i++) {
for (let i = 0; i < 30; i++) {
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
}

expect(configState.writeConfigCalls).toContainEqual(
expect.objectContaining({
deParallelRouterTrialFired: true,
deParallelRouterTrialRenderCount: 25,
}),
);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();

// The 26th eligible render must not re-arm it.
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
});

it("observes a telemetry opt-out written by another process mid-batch (arm site reads fresh, not cached)", async () => {
configState.disk = {
telemetryEnabled: true,
deParallelRouterTrialFired: false,
telemetryNoticeShown: true,
};
// Row 1 arms and primes the config cache.
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");

// Another process runs `hyperframes telemetry off`, writing straight to
// "disk" — this process's cache still says telemetryEnabled: true, so a
// cached read at the arm site would keep arming (review finding).
configState.disk = { ...configState.disk, telemetryEnabled: false };

await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(
configState.writeConfigCalls.some((call) => call.deParallelRouterTrialFired === true),
).toBe(false);
});

it("re-asserts the fired flag when the write is lost (concurrent clobber / transient failure), without re-counting the render", async () => {
Expand Down Expand Up @@ -1088,10 +1094,11 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
// Nothing could persist...
expect(configState.disk.deParallelRouterTrialFired).toBe(false);
// ...but the in-process latch still blocks the next render from
// re-running the experiment that just failed (review finding).
// re-running the path that just failed (review finding) — and now does
// it by writing an explicit "false", since absent means ON.
producerState.executeImpl = async () => undefined;
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
});
});

Expand Down
Loading
Loading