Equity Timing Lab

Equity Timing Lab shows when waiting for better ESPP or RSU tax treatment is worth the stock-price risk, using deterministic calculations and verified GPT-5.6 explanations.

Comment

Inspiration

Employees often know that waiting may improve the tax treatment of an equity sale, but that is only half the decision. Waiting also exposes the shares to market risk. Traditional tax tools explain classifications and calculate taxes. Generic AI may provide fluent but unverifiable advice. Neither clearly answers the practical question: How far could the stock fall before the modeled tax benefit of waiting disappears?

The insight The useful output is not “sell” or “wait.” It is a neutral break-even threshold that helps the individual understand the trade-off between modeled tax treatment and stock-price risk.

What it does

That is why I built Equity Timing Lab with Codex. The application:

  1. Models a proposed ESPP or vested-RSU sale.
  2. Compares it with the first relevant holding milestone.
  3. Calculates incremental federal ordinary-income tax, preferential capital-gain tax, NIIT, and California tax.
  4. Finds the lowest cent-level future stock price at which the wait scenario’s estimated net proceeds meet or exceed the proposed-sale outcome.
  5. Shows the proposed and wait scenarios, tax drivers, official sources, assumptions, and limitations.
  6. Optionally asks GPT-5.6 to explain the verified result without authoring financial values or making a sell, hold, buy, or wait recommendation.
  7. Includes one-click synthetic ESPP and RSU examples so judges and users can explore the complete workflow without entering personal financial data.

How we built it

Equity Timing Lab separates authoritative computation from probabilistic explanation. The implementation includes:

  1. A deterministic TypeScript calculation engine.
  2. Source-backed ESPP and vested-RSU state machines.
  3. A versioned Verified Result contract.
  4. A source-backed 2025 federal and California tax profile.
  5. High-precision decimal arithmetic with independently rounded two-decimal display values.
  6. A cent-level break-even solver with explicit verification at the returned price and one cent below it.
  7. A server-only OpenAI Responses API integration using GPT-5.6 and Structured Outputs.
  8. A minimized verified-value catalog that prevents GPT-5.6 from authoring financial values.
  9. A centralized applicability policy, independent semantic verification, deterministic rendering, and deterministic fallback.
  10. A responsive and accessible Vinext/Next.js interface deployed through OpenAI Sites.

I used Codex throughout the project to help translate tax-rule decisions into versioned contracts, design the calculation architecture, implement the engine and UI, build the test suite, investigate defects, audit privacy and dependency risks, and complete deployment.

I retained the key product decisions: limiting the supported scope, choosing the approved tax-rule interpretations, separating exact and displayed values, keeping the output neutral, and defining the bounded role of GPT-5.6.

Challenges we ran into

Translating tax authority into deterministic software Tax rules are written for human interpretation, not as executable specifications. I needed to define explicit date boundaries, compensation and basis rules, capital character, selling-fee treatment, and unsupported states. Each implemented rule had to map to an official source and behave consistently at edge cases such as anniversary dates, leap years, fractional shares, and capital losses.

Defining the break-even threshold correctly The break-even result could not be produced by a simple fixed-rate formula because the complete tax scenario changes across brackets, capital-gain stacking, NIIT thresholds, and California rules. The solver therefore evaluates the complete wait scenario on an integer-cent price grid.

Preserving precision without overwhelming the user Financial calculations must reconcile exactly, but users expect monetary values to display as dollars and cents. The engine retains high-precision decimal values for calculations, comparisons, and reconciliation while every user-facing monetary value is rendered with explicit half-up two-decimal formatting.

Building trust without turning the product into advice The application needed to explain a complicated financial trade-off while refusing to make the decision for the user. This required neutral language, official-source links, visible limitations, synthetic sample data, and an explicit educational-use disclaimer.

Delivering within a short timeline I learned about OpenAI Build Week only three to four days before the deadline. Codex made it possible to move from problem definition and architecture through implementation, testing, audit, responsive design, and deployment without abandoning the correctness and governance requirements.

Accomplishments that we're proud of

  1. Delivered a complete public application within a very short Build Week timeline.
  2. Built deterministic ESPP and vested-RSU comparison workflows rather than a static demonstration.
  3. Produced an explainable cent-level break-even threshold with an independently verified one-cent boundary.
  4. Integrated GPT-5.6 without allowing the model to calculate, invent, or modify authoritative financial values.
  5. Added human-readable links to the official authorities supporting each tax component.
  6. Created an accessible responsive experience that works across desktop, tablet, and mobile.
  7. Completed 181 automated tests across 22 test files, along with type checking, linting, production builds, security review, and deployment verification.
  8. Successfully completed my first Codex project and used it throughout architecture, implementation, testing, audits, and deployment.

What we learned

The best financial decision tool may refuse to decide Equity Timing Lab deliberately provides a comparison rather than a sell, hold, buy, or wait recommendation.

The primary complexity is source-of-truth governance The hardest part was not just the arithmetic. It was deciding exactly which tax rules the product would support, grounding those decisions in the right sources, and making sure every layer used the same interpretation.

Exact computation and display precision are different concerns Calculations use high-precision decimal arithmetic. User-facing values are independently rounded to two decimals, while exact values remain the source of truth for reconciliation and break-even comparisons.

AI is strongest when bounded by verified state GPT-5.6 adds value by selecting which verified facts and material drivers need explanation. It does not perform the authoritative arithmetic or author financial values.

Trust is a product feature Official-source links, privacy-safe execution, explicit limitations, accessible validation, synthetic samples, and neutral language are part of the core product. Deterministic computation decides the numbers; probabilistic intelligence explains them.

What's next for Equity Timing Lab

The next steps are professional tax review, additional tax years and jurisdictions, and carefully selected additional equity instruments. I would also expand the coverage for more break-even and rounding combinations, and continue evaluating the governed explanation policy across additional supported states.

Built With

Share this project:

Updates