One-box traffic shifting — a weighted router in front of production

Decision: how traffic is split

Goals & non-goals

• Goal: test a production build against real traffic before the whole fleet gets it, with a configurable slice and bake window, and a one-write rollback.
• Goal: make production's composition (Workers, domains, databases, resources, traffic weights) visible as a graph.
• Goal: fully optional per app; apps that don't enable it are byte-for-byte unchanged.
• Non-goal: a general-purpose L7 load balancer across arbitrary origins (Phase 4 covers node-platform lanes only).
• Non-goal: per-stage database isolation changes — one-box shares production's DB by design.
• Non-goal: replacing attestation/readiness gates; the bake is an additional signal feeding the existing prod_canary gate.

flowchart LR
  D[app.example.com<br/>Workers custom domain] --> R{{"&lt;slug&gt;-router<br/>weight from KV"}}
  R -- "90% (idle: 100%)" --> P["&lt;slug&gt;<br/>primary Worker"]
  R -- "10% (idle: 0%)" --> O["&lt;slug&gt;-onebox<br/>one-box Worker"]
  P -.binding.-> DB[(Postgres via Hyperdrive<br/>fg-slug-production)]
  O -.binding.-> DB
  P -.binding.-> RES[(D1 / R2 / KV<br/>app_resources @ production)]
  O -.binding.-> RES
  KV[(CONFIG KV<br/>split:appId)] --> R
  UI[UI slider / fg traffic set] --> KV

What exists today (and what this replaces)

Model

One-box is a second target on the production stage, not a fifth stage

Secrets, DB bindings and app_resources are scoped per (app, stage). Putting one-box on the production stage as a deployment_targets row (name: "one-box", platform: "cloudflare-workers", config.workerName: "<slug>-onebox") gives "shared databases, separate Workers" for free: the agent's existing wrangler patching (patchWranglerVars / planned patchWranglerBindings) emits the same Hyperdrive/D1/R2/KV bindings into both Workers because they resolve from the same stage. It also keeps STAGES.md's four canonical names intact and finally gives the legacy prod_canary lane (execution_requests.environment, lane-enforcement.ts, readiness.ts) a concrete thing it refers to: prod_canary ≡ production / one-box target, prod_main ≡ production / primary target.

New table traffic_splits (one row per app + stage, effectively production)

id, app_id, stage_id                     -- unique (app_id, stage_id)
enabled            boolean  default false
router_worker_name text                    -- "<slug>-router"
primary_target_id  text → deployment_targets
canary_target_id   text → deployment_targets   -- the one-box
canary_weight_bps  integer  default 0      -- live weight, basis points (1000 = 10%)
default_canary_bps integer  default 1000   -- what a deploy shifts to
bake_seconds       integer  default 900    -- seeded from execution_policies.canaryWindowSeconds
stickiness         text     default 'cookie'   -- cookie | none
auto_promote       boolean  default true   -- promote after a clean bake
rollback_on_unhealthy boolean default true
state              text     default 'idle' -- idle | canary_deploying | shifting | baking | promoting | draining | failed
state_changed_at, bake_ends_at, active_deployment_id, updated_by, created_at, updated_at

Weight history goes to a sibling traffic_events table (traffic_split_id, deployment_id?, kind, payload, actor) — deployment_events.deployment_id is NOT NULL and manual shifts happen outside any deploy. Kinds: traffic.enabled / enable_failed / disabled / shifted / settings; Phase 2 adds traffic.state. Events that belong to a deploy carry its id so the deployment timeline can render them.

Manifest (.forgegraph.yaml)

traffic:
  enabled: true
  oneBox:
    workerName: myapp-onebox      # default: <slug>-onebox
  canaryPercent: 10               # default 10
  bakeMinutes: 15                 # default 15
  stickiness: cookie              # cookie | none
  autoPromote: true
  rollbackOnUnhealthy: true

fg config apply upserts the one-box target + the traffic_splits settings, and excludes the one-box target from its "not in manifest → delete" cleanup. It never touches Cloudflare: enabling/disabling (router upload, hostname move) is always an explicit fg traffic enable|disable or the UI, so a manifest push can't silently re-route production. Apply warns when enabled: disagrees with live state.

The router Worker

A small, ForgeGraph-owned script deployed by the hub (not from the app's repo) via a new putWorkerScript helper in cloudflare-client.ts (the client wraps domains, settings, secrets and tails today, but not script upload) — PUT /workers/scripts/<slug>-router with multipart metadata declaring two service bindings (PRIMARY, CANARY) and a CONFIG KV binding. Weight lives in KV under split:<appId> ({bps, stickiness, version}), cached in-isolate for 10s; a weight change is a single KV write (propagates ≤60s, typically seconds). No redeploy, no wrangler, no agent involvement.

export default {
  async fetch(req, env, ctx) {
    const cfg = await readConfig(env);              // KV, 10s isolate cache
    const cookie = getCookie(req, "fg_lane");
    let lane = cookie === "canary" || cookie === "primary" ? cookie : null;
    if (!lane || cfg.stickiness === "none")
      lane = Math.random() * 10000 < cfg.bps ? "canary" : "primary";
    const res = await (lane === "canary" ? env.CANARY : env.PRIMARY).fetch(req);
    const out = new Response(res.body, res);
    out.headers.set("x-fg-lane", lane);             // observable in tails + health checks
    if (cfg.stickiness === "cookie" && cookie !== lane)
      out.headers.append("Set-Cookie", `fg_lane=${lane}; Path=/; Max-Age=1800; HttpOnly; Secure; SameSite=Lax`);
    return out;
  }
}

• Stickiness is what makes 10% safe for apps with sessions/migrations-in-flight: a user lands on one lane and stays there for 30 min. Force a lane with ?fg_lane=canary (operator-only, behind the same cookie) for manual smoke testing.
• bps = 0 short-circuits to PRIMARY with no KV read cost beyond the cache — steady state is effectively a passthrough.
• Hostname binding: enabling traffic for an app moves the Workers custom domain (/workers/domains, already wrapped in cloudflare-client.ts) from <slug> to <slug>-router. Disabling moves it back. Both are one API call and recorded as deployment_events.
• Node-platform apps: same router, but the bindings become origin URLs (PRIMARY_URL, CANARY_URL — the tunnel hostnames already provisioned for routes) and the router fetches them. Phase 1 ships Workers→Workers only; the origin-URL variant is Phase 4.

Deploy lifecycle (the pipeline)

stateDiagram-v2
  [*] --> idle
  idle --> canary_deploying: fg deploy create (production)
  canary_deploying --> shifting: one-box health green
  canary_deploying --> failed: deploy/health failed
  shifting --> baking: KV bps = default (10%)
  baking --> promoting: bake clean and auto_promote
  baking --> baking: operator hold / raise weight
  baking --> draining: probe fail / 5xx ratio / abort
  promoting --> draining: primary deployed and green
  promoting --> draining: primary deploy failed (rollback primary)
  draining --> idle: KV bps = 0
  draining --> failed: after failure
  failed --> idle: operator resolves canary_paused

• Bake verdict = deep-health-check on the one-box URL every 10s and Worker-level signal: tail sampled 5xx / exception ratio on <slug>-onebox vs <slug> over the window (the tail API is already wrapped at cloudflare-client.ts:625). Thresholds: any health probe failure, or canary 5xx rate > max(2× primary, 1%) → fail.
• Fail / operator abort → bps=0 immediately (one KV write; this is the rollback — the primary Worker was never touched), state failed, open a canary_paused intervention (enum exists), notify via the policy webhook. The one-box keeps the bad build so it can be debugged with ?fg_lane=canary.
• Pause / hold: an operator can freeze at any weight from the UI (autoPromote=false turns the bake into "hold until promoted"), and can move the slider up (25%, 50%) before promoting — each step writes KV + an event.
• Policy reuse: bake_seconds defaults from execution_policies.canaryWindowSeconds for the prod_canary lane, rollback_on_unhealthy from rollbackOnFailure, auto_promote from autoPromoteAfterMs != null. Changing them in the traffic UI writes both, so the two views never disagree.
• Promotion gate: lane-enforcement.ts already requires prod_canary healthy before prod_main; the traffic_splits.state machine becomes the source of that signal instead of the stub.

UI

Pipeline tab → flow chart (apps/[id]/pipeline-tab.tsx)

Add a React Flow graph above the existing changeset matrix (the matrix stays — it answers "where is this commit"; the graph answers "what is production made of and where is traffic going") (reuse @xyflow/react and the node/edge styling from packages/ui/src/fleet-topology.tsx; add @dagrejs/dagre for left-to-right layout). One tRPC query pipeline.graph({appId}) returns nodes + edges:

Edges: domain → router → {primary, one-box} carry the weight label (90% / 10%, animated while baking); target → database/resource edges are dashed "binding" edges; stage → stage edges follow sortOrder and carry the promotion gate state from readiness.ts. Live updates poll every 5s while state != idle, matching the deployments page.

Traffic panel (router node click, and a "Traffic" card on the production stage)

• Enable/disable one-box (creates target + router + moves the domain; shows the three steps with status).
• Slider for canary weight (0–100, snaps 0/5/10/25/50/100) with Apply — writes KV + event. Disabled while a deploy is in canary_deploying/promoting.
• Settings: default canary %, bake duration, stickiness, auto-promote, rollback-on-unhealthy.
• Live bake view: countdown, probe sparkline, canary-vs-primary 5xx rate, Promote now / Abort (drain to 0%) / Hold.

Mocks

M1 · Pipeline tab — flow chart, mid-bake

M2 · Traffic panel — idle (steady state)

M3 · Traffic panel — baking, with performance stats (Phase 6)

M4 · Traffic panel — promoting

M5 · Traffic panel — failed (auto-drained)

M6 · Settings

CLI

fg traffic status   --app X                      # weights, state, bake remaining
fg traffic set      --app X --canary 25          # manual shift
fg traffic promote  --app X | fg traffic abort --app X
fg deploy create    --app X --stage production   # unchanged; goes through one-box automatically when traffic.enabled
fg deploy create    --app X --stage production --skip-one-box   # break-glass, recorded as an event

Release pipeline architecture

First-class definitions

• App-owned pipeline definition: ordered nodes and transitions replace implicit ordering spread across stage names, lane enums and UI constants. Repository execution policies reference pipeline nodes; they do not define the app pipeline.
• Repository manifest: declares verification suites and selectors. Sync materializes stable, versioned ForgeGraph suite definitions; a pipeline node selects suites by ID or capability. Manifest removal retires a definition rather than deleting historical runs.
• Separate evidence types: unit-test results are build artifacts. Integration verification runs are post-deploy jobs attached to a deployment target and artifact digest. Neither is inferred from the other.
• Capability-aware runner queue: ForgeGraph runners claim jobs matching capabilities such as playwright, maestro, platform, architecture and network reachability. Capacity provider is metadata, so future DigitalOcean runners use the same protocol and scheduler.
• Database boundary: beta resources are isolated. One-box and primary production bind the same production database. Schema changes therefore use expand before one-box and contract only after production rollout and compatibility checks.
• Promotion blockers: missing/failed required evidence, artifact mismatch, unhealthy target, failed OTel verdict, incomplete bake, migration incompatibility or an open intervention all stop the transition. Break-glass is explicit, authorized and recorded.

Verification workspace information architecture

• Blocked state: the strip states the current stage, the blocking reason and the downstream consequence in one scan, for example BETA BLOCKED · 1 required suite failed · 7 tests running · One-box locked.
• Verified state: the same stable region changes in place to an affirmative verdict and next action, for example BETA VERIFIED · Continue to one-box.
• Persistent context: stage names, current stage, artifact digest continuity and the aggregate verdict never disappear behind the Details, Logs, Artifacts, Evidence or Gates tabs. The Gates tab expands the policy evaluation; it is not the only place that exposes it.
• Safety: color supplements explicit text and glyphs. A failure remains visible until resolved or explicitly waived, even when newer passing tests arrive.

• Suite policy: every suite is visibly labeled Required, Optional or Quarantined. Only required suites participate in the default promotion verdict; optional and quarantined results remain visible as evidence without silently blocking.
• Live accounting: passed, failed, running, queued, skipped and cancelled are mutually exclusive counts derived from the current attempt. Their sum equals the displayed total, and each transition updates the suite tree, aggregate strip and selected detail in one event.
• Worst-state persistence: a required failure remains called out as the blocking state while other tests continue. The interface provides a direct next-failure action rather than allowing rising pass counts to visually bury the blocker.

Verification workspace state model

Storybook contract: the suite tree, aggregate gate strip, log viewer, run header and every complex evidence panel ship with Default, Empty, Loading and Error stories, plus Running, Partial, Reconnecting and Stale where applicable.

Failure-to-recovery journey

1. Detect: the persistent gate strip states the blocker, the suite tree retains the worst required state and the failed test becomes the selected detail.
2. Triage: Next failure moves deterministically through unresolved failures. Details, Logs, Artifacts, Evidence and Gates stay in the same workspace and state exactly what each surface contains.
3. Retry: an authorized operator can retry the failed suite. The action names its scope, requires confirmation when it consumes scarce or device-bound capacity, and records actor, reason and source attempt.
4. Reconcile: the new linked attempt runs against the unchanged deployment and digest. The prior failure remains inspectable; it is not rewritten or visually presented as if it passed.
5. Re-evaluate: aggregate eligibility changes only when the replacement attempt reaches a complete, fresh and policy-valid terminal state.
6. Advance: after all required suites pass, show Continue to one-box for manual policy or visibly begin automatic advancement when app pipeline policy permits it. Either path records the exact gate snapshot and digest.

Motion hierarchy

• Pipeline: animate only the currently active stage; all completed, blocked and future stages use static text and semantic glyphs.
• Suite tree: animate only the selected running test. Other running tests use a static running glyph and their explicit status text.
• Stream: a single restrained pulse may accompany Live. Reconnecting and Stale use text, timestamp and a static state glyph rather than escalating animation.
• Reduced motion: prefers-reduced-motion removes pulses and transitions without removing information. State changes remain legible through text, glyph, position and semantic color.

Design-system contract

• Success: green appears only for terminal success and an eligible gate.
• Failure: red identifies a failed assertion or blocking condition; it is never the sole carrier of meaning.
• Attention: the warning token identifies degraded, waived or operator-attention states without presenting them as failures.
• Execution: pending and running use their dedicated neutral semantic tokens, explicit labels and glyphs.
• Consistency: pipeline rail, aggregate gate strip, suite tree, counters, tabs and evidence panels share the same status mapping. Page-local hex values and a verification-specific palette are prohibited.
• Editorial hierarchy: use Newsreader for the page title, Public Sans for interface copy and IBM Plex Mono for digests, timestamps, runner identity, counters and log evidence, matching DESIGN.md.

Responsive verification workspace

Viewport changes preserve the selected suite, selected tab, log cursor and scroll-follow preference. No breakpoint may hide the artifact digest, current target, transport freshness or promotion blocker; compact layouts may disclose secondary metadata behind an explicit Details control.

Keyboard and assistive-technology contract

• Suite hierarchy: use tree semantics with roving focus, Up/Down traversal, Left/Right collapse and expansion, Home/End movement and an explicit shortcut to return focus from detail to the selected tree item.
• Tabs and controls: use the existing accessible Radix tabs primitive, visible :focus-visible rings, logical tab order and minimum 44 px touch targets. Live updates do not reorder focused controls.
• Pipeline and status: every stage has an accessible name and current/completed/blocked relationship. Text and glyph carry status alongside color.
• Announcements: one polite live region announces debounced aggregate changes such as Beta blocked: one required suite failed. Raw log lines, timers and rapidly changing counters are not automatically announced.
• Efficiency: documented shortcuts move to the next unresolved failure and return to the suite tree. Route transitions place focus on the destination heading; in-place tab and event updates preserve focus.

Verification evidence taxonomy

Log and execution controls

• Viewport controls: use Pause stream, Clear viewport and Follow newest, plus search, wrap, timestamps and download. Pausing or clearing never stops, cancels or deletes runner output.
• Job controls: use explicit actions such as Cancel run, Cancel suite and Retry suite. Keep them outside the Logs toolbar and state the affected attempt before confirmation.
• Confirmation and audit: destructive or capacity-impacting actions require confirmation appropriate to their impact and record actor, reason, target, prior state and resulting attempt or cancellation event.
• Responsive wording: compact viewports may move low-frequency viewport controls into a labeled menu, but may not shorten their names to ambiguous verbs such as Pause or Clear.

Screen hierarchy and navigation flow

┌──────────────────────────────────────────────────────────────────────────────┐
│ ForgeGraph / App / Verification       digest · target · runner · freshness │
├──────────────────────────────────────────────────────────────────────────────┤
│ Git repository ─ Build ─ BETA ─ One-box ─ Production                       │
│ BETA BLOCKED · 1 required suite failed · 7 running · One-box locked        │
├──────────────────────┬───────────────────────────────────────────────────────┤
│ SUITE TREE           │ SELECTED SUITE · attempt · elapsed · job actions     │
│ Required             ├───────────────────────────────────────────────────────┤
│  ✓ api.auth          │ Details | LOGS | Artifacts | Evidence | Gates        │
│  ✕ api  [selected]   ├──────────────────────────────┬────────────────────────┤
│  ◌ worker            │ live append-only log         │ selected evidence      │
│ Optional             │ viewport controls only       │ and gate context        │
│ Quarantined          │                              │                        │
├──────────────────────┴──────────────────────────────┴────────────────────────┤
│ 64 passed · 1 failed · 7 running · 3 of 4 required suites passed           │
└──────────────────────────────────────────────────────────────────────────────┘

Navigation: aggregate verdict → next unresolved failure → in-place evidence →
immutable retry → recomputed gate → Continue to one-box or policy auto-advance.

Constraint worship — if only three things survive: (1) the current promotion verdict and downstream consequence, (2) the next required failure to resolve, and (3) fresh live evidence for the selected attempt. Secondary metadata may compress; those three never disappear.

Interaction state coverage matrix

Operator journey and emotional arc

Time horizons: five seconds answers “where am I and is promotion blocked?”; five minutes supports failure diagnosis and safe retry; five years preserves a legible, independently auditable release record.

Phases

Phase 1+2 are shippable without the UI (CLI + events) and are how we validate on a real Workers app first; Phase 3 is the product surface. Recommended proving app: one of the D1-migrated Workers apps already used for the bindings plan.

Risks & mitigations

Verification

• Unit: router script (weight math, stickiness, drain flag) under miniflare/workerd; traffic router (enable/disable idempotent, weight bounds, events written); bake state machine transitions incl. abort mid-bake.
• Integration (beta): deploy one digest to a beta target with its isolated DB; required Playwright/Maestro suites become capability-matched runner jobs; promotion remains blocked until all required suites report green.
• One-box integration: enable on a Workers app → domain rebinds to router, curl -I shows x-fg-lane: primary; set 100% canary → all hits canary; disable → domain back on primary.
• End-to-end: one artifact digest advances Build → Beta verification → One-box bake → Production; graph shows live weights; a deliberately bad lane-aware OTel signal drains to 0% and opens canary_paused.

NOT in scope

• A general pipeline-DAG builder: v1 materializes versioned app-owned definitions for the canonical ordered release path; arbitrary visual workflow authoring is deferred.
• A redesign of the CI build viewer: unit-test evidence remains on the existing CI surface; this work reuses its interaction vocabulary while keeping post-deploy verification distinct.
• DigitalOcean runner provisioning UI: the scheduler and protocol remain provider-neutral now; a future DigitalOcean capacity provider can join without a second job system.
• Framework-specific orchestration inside ForgeGraph: Playwright and Maestro adapters translate to the common verification contract; ForgeGraph does not become either framework's test runner.
• Automatic quarantine decisions: Required, Optional and Quarantined are explicit versioned policy inputs; ForgeGraph does not silently quarantine a flaky test.
• Beta one-box traffic: one-box remains a production-stage target in v1; Beta uses deployment-target verification against its isolated database.
• Contract migrations during rollout: destructive schema contraction waits until production compatibility is proven and is not part of the one-box bake interaction.

What already exists

Approved Mockups

Implementation Tasks

Synthesized from this review's findings. Each task derives from a specific finding above. Run with Claude Code or Codex; checkbox as you ship.

• ☐ T1 (P1, human: ~3d / CC: ~2h) — Pipeline model — Materialize versioned app-owned pipeline definitions.
  Surfaced by: Information Architecture — the canonical stage order and database boundaries cannot remain implicit. Files: packages/db/src/schema, packages/api/src/pipeline, manifest sync and migrations. Verify: schema tests, legacy 0/3/4-stage backfill tests, immutable-digest transition tests.
• ☐ T2 (P1, human: ~4d / CC: ~3h) — Verification model — Add suite definitions, runs, attempts, tests and evidence custody.
  Surfaced by: State Coverage + Evidence Taxonomy — retries must create linked immutable attempts and structured evidence must remain distinct from files and logs. Files: packages/db/src/schema, packages/api/src/verification, repository config parser. Verify: migration, policy-version, attempt-lineage and retention tests.
• ☐ T3 (P1, human: ~4d / CC: ~3h) — Runner protocol — Execute capability-matched Playwright and Maestro verification jobs.
  Surfaced by: User Journey — Beta verification needs provider-neutral runner claims, structured results, logs and artifacts. Files: agent, packages/api runner routes, CLI/config sync. Verify: claim compatibility, cancellation, retry and provider-metadata contract tests.
• ☐ T4 (P1, human: ~3d / CC: ~2h) — Promotion engine — Gate Beta to one-box on complete fresh evidence and digest continuity.
  Surfaced by: Information Architecture — the persistent verdict must be backed by one deterministic policy snapshot. Files: packages/api/src/pipeline, lane enforcement, readiness and intervention audit events. Verify: blockers, waivers, stale streams, mismatch, manual advance and auto-advance tests.
• ☐ T5 (P1, human: ~2d / CC: ~90min) — Live transport — Add resumable verification event streaming.
  Surfaced by: Interaction State Coverage — reconnect by acknowledged cursor, backfill, deduplicate and reconcile aggregates without erasing the viewport. Files: apps/web/src/app/api/events, evidence stream routes and verification hooks. Verify: disconnect/reconnect, duplicate event and missed-event integration tests.
• ☐ T6 (P1, human: ~5d / CC: ~4h) — Verification workspace — Build the approved suite-centric desktop experience.
  Surfaced by: Passes 1, 3, 4, 5 and 7 — implement labeled rail, gate strip, suite tree, outcome counts, immutable retry, five tabs, dominant logs and scoped controls. Files: apps/web/src/app/apps/[id], packages/ui/src and Storybook. Verify: component tests, realtime transition tests and visual comparison with the approved mockup.
• ☐ T7 (P2, human: ~3d / CC: ~2h) — Responsive and accessibility — Implement the three viewport modes and operational keyboard contract.
  Surfaced by: Responsive & Accessibility — preserve state across breakpoints, route-based mobile detail, tree navigation, stable focus and aggregate-only announcements. Files: verification workspace routes/components and Storybook. Verify: keyboard-only flows, axe checks, 375/768/1280 visual tests and reduced-motion tests.
• ☐ T8 (P2, human: ~2d / CC: ~90min) — State stories and end-to-end proof — Cover every reviewed state and full release journey.
  Surfaced by: State Coverage — complex components require Default, Empty, Loading and Error stories plus Running, Partial, Reconnecting and Stale where applicable. Files: packages/ui stories, web integration tests and beta verification fixtures. Verify: Playwright/Maestro fixture run and one digest advancing Build → Beta → One-box → Production.

Design plan review — completion summary

+====================================================================+
|         DESIGN PLAN REVIEW — COMPLETION SUMMARY                    |
+====================================================================+
| System Audit         | DESIGN.md present; app workspace UI         |
| Step 0               | 4/10; all 7 dimensions + live viewer        |
| Pass 1  (Info Arch)  | 4/10 → 10/10 after fixes                    |
| Pass 2  (States)     | 4/10 → 10/10 after fixes                    |
| Pass 3  (Journey)    | 5/10 → 10/10 after fixes                    |
| Pass 4  (AI Slop)    | 6/10 → 10/10 after fixes                    |
| Pass 5  (Design Sys) | 7/10 → 10/10 after fixes                    |
| Pass 6  (Responsive) | 3/10 → 10/10 after fixes                    |
| Pass 7  (Decisions)  | 2 resolved, 0 deferred                      |
+--------------------------------------------------------------------+
| NOT in scope         | written (7 items)                           |
| What already exists  | written                                     |
| TODOS.md updates     | 0 proposed; no design debt deferred         |
| Approved Mockups     | 5 generated, 1 approved                     |
| Decisions made       | 11 reflected in the plan                    |
| Decisions deferred   | 0 design decisions                          |
| Overall design score | 4/10 → 10/10                                |
+====================================================================+

Result: Plan is design-complete. Run /design-review after implementation for visual QA.

Deferred architecture questions

These pre-existing architecture choices are outside this UI design review and remain explicit implementation gates rather than silently defaulted design decisions.

• Should one-box also be offered on beta (beta one-box for internal-traffic bakes)? The model allows it (traffic_splits keys on stage) — proposal: production only in v1.
• Weight-by-header for synthetic checks (e.g. always route the deep-health-check to canary during bake) vs. probing the workers.dev URL directly. Proposal: probe directly, it's simpler and doesn't leak into the router.
• Default bake: 15 min here vs. 5 min in canaryWindowSeconds today — pick one and migrate the default.

Engineering review findings (2026-08-23)

Six findings against the implemented stack (phases 1–7c, 76 files; phase 8 additionally implemented). Scope was challenged and kept cohesive: import tracing showed the bake verdict depends on phase 6's metrics and phase 7c's promotion path depends on the phase 8 verification schema, so no meaningful sub-stack could be carved out. Two critical gaps (silent failure, no test, no handling) are marked.

Engineering review tasks — all applied before landing

E1–E7 shipped in feat/one-box-traffic (PR #404) and feat/release-verification (PR #405). One item was deliberately delivered in part; it is named under "Residual gap" below rather than marked done.

• E1 (P1) — Router: pass 101/WebSocket through untouched; make bps=0 a true passthrough. Verify: router test for a 101 + webSocket response.
• E2 (P1) — Router/metrics: remove ?fg_lane=; exclude override-forced requests from the bake verdict.
• E3 (P2) — Router: compose both script variants from one shared prelude; correct the stale duplication comment.
• E4 (P1) — Lifecycle + traffic panel: record and surface promotions made without traffic evidence.
• E5 (P1) — Fake-db unit tests for promote, drain (incl. KV-write-fail retry), tickBakingSplit, and the stuck-state sweeper.
• E6 (P1, CRITICAL regression) — Regression test for the viaOneBox deploy branch in api/fg/deploy: split enabled routes to one-box; --skip-one-box and explicit --target bypass; non-idle lifecycle returns 409. The deploy POST tests currently mock loadEnabledSplit to null, so this branch is unexercised.
• E7 (P1) — Landing hygiene: renumber 0088_traffic_splits → 0089+ around the merged mise 0088_build_toolchains; delete the superseded blue-green.ts stub; drop the duplicate vitest config; reconcile the bake default (15 min here vs 5 min in canaryWindowSeconds) to one value.

Two TODOs were filed rather than absorbed: repairing the emulate-PGlite DB harness, and a CI guard against duplicate Drizzle migration numbers.

Residual gap — forced traffic still counts toward the bake verdict

E2 shipped in part. The shareable ?fg_lane= form is gone and the header override now marks its request upstream with x-fg-lane-forced, so a posted link can no longer push a crowd onto the canary. Excluding forced traffic from the verdict is not done. fg.lane is an OTel resource attribute fixed at deploy time, so it tags every span from the one-box Worker regardless of why the request arrived there; excluding forced requests needs a per-span attribute set from the incoming header in @forgegraph/otel, a ClickHouse filter in traffic-metrics-signoz.ts, and every app to upgrade the otel package before it takes effect. A scripted client can therefore still skew a bake one header at a time. Named here rather than half-built.

Not covered by the new tests

E5 added state-machine coverage for promote, drain (including the KV-write-failure retry), hadTrafficEvidence and the stuck-state sweeper — 11 tests against an in-memory db stub. tickBakingSplit's probe and metrics branches remain uncovered: they are the largest surface and depend on the DB harness in the TODO above.

GSTACK REVIEW REPORT

VERDICT: DESIGN + ENG CLEARED — E1–E7 applied; phases 1–7c in PR #404, phase 8 in PR #405.

NO UNRESOLVED DECISIONS