Buy-Timing Engine

The three honesty rules

A target is always a RANGE. Never a point estimate, and absent entirely when there is no basis for one. A single snapshot is a price, not a trend, and the confidence says so.

No history means no call. Empty or thin input returns `track_closely` with low confidence rather than a confident-looking guess. A free or non-ticketed event is told to just turn up instead of being put on a price watch that can never resolve.

Certainty is capped. The model will not claim near-certainty about a resale price, because the header would be lying if it did.

The clock is an argument

`now` is injected and every derived date flows from it — generatedAt, the stop-loss date, the days-to-event that drives half the decision tree. A recommendation that silently depends on when it ran cannot be reproduced, and "why was I told to wait" is exactly the question somebody asks days later with the answer already gone.

The tuning tables are yours

STOP_LOSS_DTE, EXPECTED_DISCOUNT and LISTING_THRESHOLD are exported. They encode one market's behaviour and are the part most likely to need refitting — how long before the event a tier stops being worth waiting on, how much discount is still plausible, and the listing count below which inventory looks thin, scaled by venue capacity so forty listings reads differently at a theatre and a stadium.

Input shapes are deliberately small: eight fields of an event, four of a snapshot. The application this came from had a forty-field event record, and making a buyer build that to ask a question about a price would be its own kind of dishonesty.

Verified — and the first pass caught 3 of 10

Which is the honest reason to run mutations before selling something. The tests read as thorough and pinned far less than they looked like they did. Survivors included snapshots trusted in ARRIVAL order rather than time order (so an out-of-order feed — a backfill, a retry, two collectors racing — makes the slope point the wrong way and the engine says "prices are falling, you can wait" while they climb), inventory thinness not scaling with venue size, and the target band collapsing onto a point while still satisfying low < high, because the high end is computed from the current price and stays above regardless.

22 tests now, 8 of 10 caught, 2 proved equivalent by arithmetic rather than asserted.

Delivery

Source delivered as a private repository invite within 24 hours of purchase. Single-product commercial license: use and modify in any number of products; no redistribution or resale of the source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function buildRecommendation(input: RecInput): Recommendation;

  export type DemandTier = "high" | "moderate" | "low";
  export type Marketplace = string;