Skip to content

Commit c6df112

Browse files
vanceingallsclaude
andcommitted
feat(producer): enable the parallel-DE router by default, behind a per-install circuit breaker
The DE parallel router (HF_DE_PARALLEL_ROUTER) becomes default-ON. The soak answered the safety question it was gated on: zero damaged frames shipped — every fallback was the self-verification net catching a bad frame and recovering on the screenshot path. Verify PSNR p10 sits flat near 40 dB against a 32 dB floor. The residual 2.31% revert rate is an efficiency cost (a revert forfeits the speedup, never the output), accepted in exchange for parallelizing the >=700-frame band — roughly 80% of all DE capture wall-clock, frame-weighted. Default-ON is safe because the per-install circuit breaker stays underneath it. That distinction matters: 9.8% of installs hit a revert, and they are latched off permanently after the first one. Without the breaker those installs would go from "one slow render, then protected" to "every eligible render is slow". The breaker, adapted for a default-ON flag: - Writes an explicit HF_DE_PARALLEL_ROUTER=false and persists it to ~/.hyperframes/config.json, so the install stays off across processes. Absent no longer means off, so the switch has to be written, not unset. - Trips only on a real fallback, never on render count — a healthy install keeps the speedup indefinitely. - Independent of telemetry state: opting out of analytics must not cost a user the faster renderer. Telemetry governs reporting, not behavior. - An explicit user value wins in both directions, latched before the breaker can write the var and make the two indistinguishable. - The user is told when it trips and how to re-enable. isDeParallelRouterEnabled() parses the kill switch properly: false/0/off/no (case- and space-insensitive) disable; unset or empty is the default. A bare `!== "false"` would silently ignore every spelling but one and hand parallel DE to a user who asked for none. Refs PRINFRA-384 Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent a850e97 commit c6df112

5 files changed

Lines changed: 278 additions & 239 deletions

File tree

‎packages/cli/src/commands/render.test.ts‎

Lines changed: 45 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -725,7 +725,11 @@ describe("renderLocal browser GPU config", () => {
725725
});
726726
});
727727

728-
describe("renderLocal — DE parallel-router CLI trial", () => {
728+
// Suite renamed with the breaker work: this is no longer an opt-in trial. The
729+
// bindings come from main's shared top-level `renderModule` import rather than
730+
// this suite's own beforeAll — same module instance every other suite uses, so
731+
// module-scope arm/consume state resets through the one `resetTrialState()`.
732+
describe("renderLocal — DE parallel-router circuit breaker", () => {
729733
const { renderLocal, __resetDeParallelRouterTrialStateForTests: resetTrialState } = renderModule;
730734
const savedEnv = new Map<string, string | undefined>();
731735

@@ -768,19 +772,22 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
768772
browserGpuMode: "software" as const,
769773
hdrMode: "auto" as const,
770774
quiet: true,
771-
// The trial is OPT-IN (review): only the CLI's own sequential call sites
772-
// set this. These tests simulate those call sites.
773-
enableDeParallelRouterTrial: true,
775+
// Breaker management is OPT-IN (review): only the CLI's own sequential
776+
// call sites set it. These tests simulate those call sites.
777+
manageDeParallelRouterBreaker: true,
774778
};
775779

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

786793
it("does not override an env var the user already set themselves", async () => {
@@ -794,49 +801,30 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
794801
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
795802
});
796803

797-
it("does not enable the trial once it has already fired for this install", async () => {
804+
it("writes an explicit false once the breaker has tripped for this install", async () => {
805+
// THE regression this rework exists for: the old code disabled the
806+
// router by DELETING the var. With a default-ON router, absent means ON,
807+
// so deleting would silently re-enable it on the very host that just
808+
// failed. Only an explicit "false" is a real off-switch.
798809
configState.disk = {
799810
telemetryEnabled: true,
800811
deParallelRouterTrialFired: true,
801812
telemetryNoticeShown: true,
802813
};
803814
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
804-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
805-
});
806-
807-
it("does not enable the trial when shouldTrack() is false (dev mode / DO_NOT_TRACK)", async () => {
808-
configState.disk = {
809-
telemetryEnabled: true,
810-
deParallelRouterTrialFired: false,
811-
telemetryNoticeShown: true,
812-
};
813-
trackingState.shouldTrack = false;
814-
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
815-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
815+
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
816816
});
817817

818-
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 () => {
818+
it("keeps the router on for a telemetry opt-out — analytics choice must not cost performance", async () => {
819+
// The old trial refused to arm without recordable telemetry (no point
820+
// running an experiment you can't measure). Now that the router is a
821+
// shipped default, gating it on telemetry would punish a privacy choice
822+
// with a slower renderer.
819823
configState.disk = {
820824
telemetryEnabled: false,
821825
deParallelRouterTrialFired: false,
822826
telemetryNoticeShown: true,
823827
};
824-
trackingState.shouldTrack = true;
825-
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
826-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
827-
});
828-
829-
it("does not enable the trial before the first-run telemetry disclosure has been shown at least once", async () => {
830-
// cli.ts shows this notice via a fire-and-forget, unawaited dynamic
831-
// import — there's no guarantee it printed before renderLocal runs on a
832-
// brand-new install's very first invocation. Requiring
833-
// telemetryNoticeShown means the trial never races an opt-in message
834-
// against the disclosure it depends on.
835-
configState.disk = {
836-
telemetryEnabled: true,
837-
deParallelRouterTrialFired: false,
838-
telemetryNoticeShown: false,
839-
};
840828
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
841829
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
842830
});
@@ -946,11 +934,9 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
946934
});
947935

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

970956
producerState.executeImpl = async (job) => {
@@ -978,12 +964,14 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
978964
expect(configState.writeConfigCalls).toContainEqual(
979965
expect.objectContaining({ deParallelRouterTrialFired: true }),
980966
);
981-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
967+
// Explicit "false", not deleted: with a default-ON router, unsetting the
968+
// var would re-enable it on the host that just reverted.
969+
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
982970
});
983971

984972
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 () => {
985973
// The trial's process-wide env var and module-level flags are only safe
986-
// under sequential invocation, so enableDeParallelRouterTrial is OPT-IN
974+
// under sequential invocation, so manageDeParallelRouterBreaker is OPT-IN
987975
// (review): a programmatic renderLocal consumer that doesn't know about
988976
// the trial must get no trial. The CLI's concurrent-batch path relies on
989977
// the same default by leaving the option unset.
@@ -992,7 +980,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
992980
deParallelRouterTrialFired: false,
993981
telemetryNoticeShown: true,
994982
};
995-
const { enableDeParallelRouterTrial: _omitted, ...programmaticOptions } = baseOptions;
983+
const { manageDeParallelRouterBreaker: _omitted, ...programmaticOptions } = baseOptions;
996984
await renderLocal("/tmp/project", "/tmp/out.mp4", programmaticOptions);
997985
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
998986
expect(configState.writeConfigCalls).toHaveLength(0);
@@ -1011,7 +999,7 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
1011999
};
10121000
};
10131001
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
1014-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
1002+
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
10151003

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

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

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

1041-
expect(configState.writeConfigCalls).toContainEqual(
1042-
expect.objectContaining({
1043-
deParallelRouterTrialFired: true,
1044-
deParallelRouterTrialRenderCount: 25,
1045-
}),
1046-
);
1047-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
1048-
1049-
// The 26th eligible render must not re-arm it.
1050-
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
1051-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
1052-
});
1053-
1054-
it("observes a telemetry opt-out written by another process mid-batch (arm site reads fresh, not cached)", async () => {
1055-
configState.disk = {
1056-
telemetryEnabled: true,
1057-
deParallelRouterTrialFired: false,
1058-
telemetryNoticeShown: true,
1059-
};
1060-
// Row 1 arms and primes the config cache.
1061-
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
1062-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
1063-
1064-
// Another process runs `hyperframes telemetry off`, writing straight to
1065-
// "disk" — this process's cache still says telemetryEnabled: true, so a
1066-
// cached read at the arm site would keep arming (review finding).
1067-
configState.disk = { ...configState.disk, telemetryEnabled: false };
1068-
1069-
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
10701032
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
1033+
expect(
1034+
configState.writeConfigCalls.some((call) => call.deParallelRouterTrialFired === true),
1035+
).toBe(false);
10711036
});
10721037

10731038
// The config write landing is NOT enough: config.json is the copy a stale
@@ -1136,10 +1101,11 @@ describe("renderLocal — DE parallel-router CLI trial", () => {
11361101
// Nothing could persist...
11371102
expect(configState.disk.deParallelRouterTrialFired).toBe(false);
11381103
// ...but the in-process latch still blocks the next render from
1139-
// re-running the experiment that just failed (review finding).
1104+
// re-running the path that just failed (review finding) — and now does
1105+
// it by writing an explicit "false", since absent means ON.
11401106
producerState.executeImpl = async () => undefined;
11411107
await renderLocal("/tmp/project", "/tmp/out.mp4", baseOptions);
1142-
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
1108+
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
11431109
});
11441110
});
11451111

0 commit comments

Comments
 (0)