Annual price roll (SY rollover)

Annual price roll (SY rollover)

The annual price roll is the load-bearing workflow of the GFS calendar. Once a year, on July 1, every active customer × SKU pricing record needs to be recomputed for the new school year (SY2026 → SY2027, and so on). The roll touches more rows in one pass than every other workflow combined.

Because the blast radius is so large, this is the one workflow that runs on a native Cloudflare Workflow class — AnnualRollWorkflow — for durable execution. step.waitForEvent gates per customer cohort, so a crash or a deploy mid-roll resumes from the last committed step instead of starting over.

The contract is stored in workflow_definitions WHERE workflow_type='annual_price_roll'. Risk level 5 (the maximum). Expected duration ~4 hours wall clock from launch to last customer email approved.

Trigger conditions

• Annual cron fire on July 1 at 08:00 ET — the default path.
• Manual trigger from /annual-roll-control.html when the calendar slips or a re-run is needed.
• Cost-basis refresh completed across all assemblies and Mike wants the new floor.
• Customer-program tier change that ought to roll into next SY pricing.

The 3 beats

1. 01

   Launch AnnualRollWorkflow durable execution

   The runner emits an ANNUAL_ROLL_WORKFLOW binding invoke with {next_sy, markup_rules}. Inside the class, the four pillars (context → cost → margin → fan-out) execute as step.do blocks with per-step retries.

   Writes annual_roll_workflow_runs

   Time ~120 min wall

   Kind workflow_class_invoke

   Status stub

   Note native CF retry policy
2. 02

   Per-customer cohort notification

   Each customer cohort batch generates a draft email staged in outbound_email_log with status=pending_review. Mike approves one cohort at a time — bulk-approve is available but defaults to single-decide for the roll.

   Writes outbound_email_log

   Time per cohort

   Kind hitl_email_draft

   Status stub

   Note one_per cohort
3. 03

   Render per-customer quote PDFs

   For every approved cohort, an HTTP POST to /api/quote/pdf renders a fresh SY quote PDF and stores it at quotes/{id}.pdf in R2. Browser Rendering binding is the engine.

   Writes R2 bucket quotes/

   Time ~6–10s per quote

   Kind http_call

   Status stub

   Note one_per cohort

What's different after the workflow runs

• Every active customer has a new pricing_master row for the next school year.
• pricing_history holds a complete before/after snapshot stamped with Mike's cohort approvals.
• NetSuite itempricing records reflect the new values within the NS push drain window.
• A customer-specific PDF quote is live in R2 per cohort.
• reflexion_log carries a tagged row per cohort for next-year prep.

What can go wrong and how to recover

Adjacent workflows + diagrams

Code paths + invariants