refactor(producer): drop internal PR/phase identifiers from stages doc

Comment-only cleanup. Removes "PR 1.x", "Phase 1 PR", and "Phase 3 PR 3.1"
references from JSDoc blocks in `compileStage.ts`, `probeStage.ts`,
`planHash.ts`, and `freezePlan.ts`. Track / PR identifiers rot quickly and
belong in PR descriptions, not in source. Design-doc section citations
(DISTRIBUTED-RENDERING-PLAN.md §X.Y) are kept — those reference a stable
external artifact.

Also tightens the `probeStage.ts` `browserProbeMs` doc string to say
"near-zero when `needsBrowser` was false" instead of "0" — the Date.now()
delta around the function body is sub-ms but not literally zero.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
James
2026-05-11 19:01:08 +00:00
co-authored by Claude Opus 4.7
parent 90f14703b2
commit 56ac52384f
3 changed files with 11 additions and 16 deletions
@@ -8,9 +8,9 @@
* `deviceScaleFactor` for supersampling.
*
* The probe sub-stage (browser launch, duration discovery, recompile,
* media reconciliation) is extracted separately in PR 1.3. This stage
* stops at the point where the in-process renderer formerly entered the
* `if (needsBrowser)` branch.
* media reconciliation) lives in a sibling stage. This stage stops at
* the point where the in-process renderer enters the `if (needsBrowser)`
* branch.
*
* Hard constraints preserved verbatim from the in-process renderer:
* - `applyRenderModeHints(cfg, ...)` is allowed to mutate `cfg.forceScreenshot`.
@@ -3,11 +3,9 @@
* manifest at the end of `plan()`, compute the planHash from the frozen
* artifacts, and return the manifest path.
*
* Phase 1 PR 1.1 ships the signature only: there are no callers yet. The
* function body is added in Phase 3 PR 3.1 when `services/distributed/plan.ts`
* lands and composes the Phase-1 stages. Keeping the skeleton in this PR
* means subsequent stage-extraction PRs can grow the `stages/` directory
* without touching the `producer/src/index.ts` export surface again.
* Signature-only skeleton: there are no callers yet. The function body
* lands when `services/distributed/plan.ts` is added and composes the
* stage primitives.
*
* See DISTRIBUTED-RENDERING-PLAN.md §2.1 phase 6, §4.1 directory layout,
* §4.3 LockedRenderConfig.
@@ -18,9 +16,7 @@ import type { PlanDimensions } from "./planHash.js";
/**
* The encoder configuration locked in at plan time. Mirrors §4.3
* LockedRenderConfig in the design doc. Phase 1 declares the shape; Phase 2
* + Phase 3 populate it from the existing `renderOrchestrator` config and
* the new closed-GOP encoder args.
* LockedRenderConfig in the design doc.
*/
export interface LockedRenderConfig {
// Capture
@@ -97,10 +93,9 @@ export interface FreezePlanResult {
* Freeze a plan directory: write `meta/*.json` + top-level `plan.json`, then
* compute `planHash` over the canonicalized contents.
*
* Skeleton only in Phase 1. Phase 3 PR 3.1 wires this up.
* Skeleton — body lands when the distributed-render primitives compose the
* stage functions.
*/
export async function freezePlan(_input: FreezePlanInput): Promise<FreezePlanResult> {
throw new Error(
"freezePlan is not implemented yet — wired in Phase 3 PR 3.1 (see DISTRIBUTED-RENDERING-PLAN.md §11).",
);
throw new Error("freezePlan is not implemented yet — see DISTRIBUTED-RENDERING-PLAN.md §11.");
}
@@ -78,7 +78,7 @@ export interface ProbeStageResult {
/** Composition duration (post-probe). Guaranteed > 0 — the stage throws on <= 0. */
duration: number;
totalFrames: number;
/** Wall-clock ms for the entire probe phase (0 if `needsBrowser` was false). */
/** Wall-clock ms for the entire probe phase (near-zero when `needsBrowser` was false). */
browserProbeMs: number;
}