# Clockwork Caper Game Contract

`clockworkcaper` is an original 5x3, 25-line Gearfall cascade slot with a
brass-and-teal clockwork workshop theme. It is a one-shot game: the base spin,
all cascades, Overdrive free spins, retriggers, Inventor Wild unlocks, and Core
milestones are generated and evaluated inside one seeded reservation. The
wallet receives one debit and one final credit, including a zero-amount credit
for a loss.

New wagers use `clockwork-reels-v2`. This is a natural-reel algorithm: seeded
reel stops create each grid first, and the server evaluates and caps the payout
afterward. It never selects, rejects, or redraws an outcome according to its
payout.

## Release configuration

- Demo: enabled.
- `bspin-staging`: enabled by `docs/bspin-staging-operator.sql`.
- `bspin-production`: enabled by `docs/bspin-production-operator.sql` for the
  approved `clockwork-reels-v2` engine, `clockwork-reels-256-v2.0.0` reel set,
  and `clockwork-math-v2.0.4` math profile.
- Production approval does not promote the tail-frequency model to
  certification. Its 1,250x estimate remains engineering evidence with the
  checked-in uncertainty disclosure, while the server-enforced payout cap
  remains authoritative.
- Two-decimal stake contract: `0.25-40.00` in `0.25` steps.
- Maximum configured payout: `50,000`.
- Game payout cap: `1,250x` the accepted stake.

## Immutable v2 math assets

| Asset | Version |
| --- | --- |
| Outcome algorithm | `clockwork-reels-v2` |
| Reel set | `clockwork-reels-256-v2.0.0` |
| Math profile | `clockwork-math-v2.0.4` |
| Grid order | Reel-major |

The checked-in module exports five independent 256-stop circular base reels and
five separate 256-stop Overdrive reels. Each complete reel has 256 distinct
circular three-symbol windows. A uniformly selected stop therefore exposes
that stop and its next two strip symbols, while keeping every row and every one
of the 25 fixed paylines statistically stationary on an initial grid.

For a cascade, winning positions are removed and survivors fall toward the
bottom row. Each affected reel consumes exactly one new uniform stop. Its
replacement symbols retain circular strip order and enter the missing top
positions. Standalone Wild and Scatter symbols are valid in anchors and
refills. Power Cores exist only on Overdrive reel five.

The reel ordering, symbol counts, construction seeds, paytable, cursor map, and
profile targets are immutable exports in `src/clockworkCaperV2.js`; production
does no runtime tuning.

## Paytable

The total stake is divided equally across 25 lines. All 25 lines are evaluated
together. Each line pays its highest, longest left-to-right 3/4/5 match, every
winning line is paid, and the union of overlapping winning positions is
removed. Values below multiply the line stake.

| Symbol | 2 | 3 | 4 | 5 |
| --- | ---: | ---: | ---: | ---: |
| Master Inventor | - | 20x | 188x | 2,200x |
| Mechanic | - | 13x | 125x | 900x |
| Scout | - | 12x | 113x | 800x |
| Clockwork Cat | - | 13x | 63x | 100x |
| A / K | - | 5x | 41x | 80x |
| Q / J / 10 | - | 4x | 41x | 80x |
| Automaton Wild | 7x | 42x | 589x | 4,300x |

Wild substitutes for standard symbols, but not Vault Key Scatter or Power
Core. The first grid in a base or free-spin chain with three or more visible
Scatters pays `3x` total stake and awards 10 free spins. A later qualifying
cascade in the same spin can trigger once; surviving or moving Scatters do not
create a second trigger for that spin.

## Cascades and Inventor rail

Every line-winning evaluation triggers gravity and a natural-reel refill.
Winning evaluations fill the six-segment Inventor rail:

- Win 2: Master Inventor becomes Wild.
- Win 4: Mechanic becomes Wild.
- Win 6: Scout becomes Wild.

An unlock applies from the following evaluation until that base/free-spin
chain ends. Every visible or newly generated matching Inventor is recorded in
`transformedPositions` and acts and renders as Wild. The rail resets for the
next base or free spin.

## Overdrive

- A qualifying base Scatter trigger awards 10 Overdrive free spins after that
  complete base cascade chain finishes.
- The presentation completes every remaining base cascade, shows a distinct
  gold popup for the authoritative base win, then collects the triggering Keys
  and activates Overdrive. A second gold popup shows only the Overdrive win
  after the feature completes.
- A qualifying Scatter trigger during Overdrive adds up to 10 free spins,
  subject to the 50-spin limit.
- Newly generated Power Cores on Overdrive reel five count once. Surviving or
  falling Cores are not counted again.
- Crossing Core 3 and Core 6 each awards up to two additional free spins.
- Crossing Core 6 activates `2x` for subsequent wins.
- Hard limits are 50 free spins, 20 cascades per spin, 200 sequence rows, and
  `1,250x` credited payout.

## Audio presentation

- The main soundtrack was supplied by the game owner on July 27, 2026 and is
  served as `public/clockworkcaper/audio/soundtrack.mp3`.
- The original 31-second, 192 kbps MP3 stream is retained without lossy
  re-encoding. After the player's first interaction it is decoded once into a
  sample-accurate Web Audio loop. On load, the decoded waveform scans the first
  and final musical phrases for the closest rhythmic-envelope match, then uses
  a short 720 ms constant-gain S-curve crossfade at those selected points. This
  avoids both a long pause and the doubled loudness of a naive overlap.
- Music intensity is presentation-only. It rises gradually for paying
  cascades, longer win chains, and Overdrive, then decays back to the ambient
  level. Win and feature callouts temporarily duck the music.
- Music Off, page visibility, and game switching pause or fade the soundtrack
  independently from Sound Off. No audio state affects the authoritative
  result, payout, RNG, or settlement.

## Raw and credited evidence

The server returns `rawMultiplier`, credited `multiplier`, `rawPayout`,
credited `payout`, `capApplied`, and `limitReached`. Every grid step likewise
records `rawStepPayout`, `creditedStepPayout`, `rawCumulativePayout`,
`cumulativePayout`, and its cap/limit evidence. This preserves a naturally
overshooting result for audit while wallet settlement and cumulative player
presentation use only the credited amount.

The authoritative sequence also retains grids, winning lines, removals,
refills, transformations, rail progress, active multipliers, Scatter and Core
events, free-spin awards, and cumulative credited payout. The client formats
these fields and never derives settlement.

## Math-profile acceptance contract

`clockwork-math-v2.0.4` has a nominal total RTP of `97%`. It is accepted only
when a complete deterministic simulation of at least five million wagers falls
inside all applicable bands:

| Metric | Acceptance |
| --- | ---: |
| Base/cascade RTP | 65.5-66.5% |
| Free-spin contribution | 30.5-31.5% |
| Total RTP | 96.5-97.5% |
| Paying base rounds | 28-32% |
| Bonus entry | 1 in 135-145 |
| 100x or greater | 1 in 950-1,150 |
| Multi-line paying anchors | At least 5% |
| Return standard deviation | 7.5-9.0x |
| Maximum credited return | 1,250x |
| Emergent cap-hit estimate | 1 in 500 million-4 billion |

The displayed 4.25/5 volatility score is an internal label supported by the
measured standard deviation and tail percentiles; it is not presented as an
industry-standard formula.

### Five-million-wager ordinary audit

The deterministic `clockwork-release-v2.0.4` audit over nonces `0..4,999,999`
completed in four contiguous shards. Its checked-in evidence is
`docs/clockwork-caper-v2-profile.json`. Earlier profiles are preserved as
versioned artifacts through `docs/clockwork-caper-v2.0.3-profile.json`.

| Metric | Observed | Gate |
| --- | ---: | --- |
| Base/cascade RTP | 65.84310% | Pass |
| Free-spin contribution | 31.14586% | Pass |
| Total RTP | 96.98896% | Pass |
| Paying base rounds | 30.77296% | Pass |
| Bonus entry | 1 in 143.90 | Pass |
| 100x or greater | 1 in 986.19 | Pass |
| Multi-line paying anchors | 42.51825% | Pass |
| Return standard deviation | 7.51112x | Pass |
| p99.9 / p99.99 | 100.64x / 266.76x | Informational |
| Maximum credited / raw | 839.12x / 839.12x | Informational |
| Capped results | 0 in 5,000,000 | Informational |
| Repeated / consecutive duplicate anchors | 10 / 0 | Informational |
| Initial-line relative spread | 1.44774% | Informational |
| Structural failures | 0 | Pass |

This ordinary sample passes every stochastic and structural gate enforced by
the five-million-wager audit for `clockwork-math-v2.0.4`. It does not certify
the separate near-`10^-9` cap-hit target: the matching importance-sampled run
below is explicitly insufficient. Reel or paytable changes require a new
immutable math-profile version and a fresh five-million-wager audit.

Run a quick structural audit while iterating:

```bash
npm run check:clockwork-rng -- --fast --rounds 10000 --seed local-review
```

Run the release-profile audit:

```bash
npm run check:clockwork-rng -- --rounds 5000000 --workers 4 --seed clockwork-release-v2.0.4 --output docs/clockwork-caper-v2-profile.json
```

The JSON report includes exact initial single-line EV and Scatter
combinatorics, base/free/total RTP, hit and feature frequencies, payout bands,
100x frequency, standard deviation and tail percentiles, line and multi-line
counts, chain lengths, retriggers, Core milestones, generated
Wild/Scatter/Core counts, duplicate anchors, immutable-strip window checks,
cursor checks, and deterministic replay evidence. `--fast` enforces structural
integrity only. Full mode also enforces the stochastic profile gates. Worker
mode partitions one nonce range into bounded, contiguous deterministic shards;
the coordinator recombines exact counts, return moments and percentiles, line
events, and base-anchor keys before evaluating the profile. The checked-in
`docs/clockwork-caper-v2-profile.json` report is the reproducible ordinary
five-million-wager evidence.

An ordinary five-million-round run records observed cap hits but cannot on its
own resolve a probability near `10^-9`; release evidence must pair it with a
separately checked-in, reproducible importance-sampled tail estimate. The
ordinary audit does not manufacture confidence that its sample cannot support.

Use the offline math model for paytable sensitivity and tail work:

```bash
npm run model:clockwork-math -- --mode sensitivity --sensitivity-rounds 100000 --candidate-validation-rounds 250000 --baseline-base 0.658430992 --baseline-feature 0.311458616 --baseline-provenance "reviewed v2.0.4 5m profile" --seed clockwork-model-v2.0.4
npm run model:clockwork-math -- --mode tail --ordinary-rounds 100000 --importance-rounds 250000 --seed clockwork-tail-v2.0.4 --output docs/clockwork-caper-v2-tail.json
```

The sensitivity run counts each paid symbol/length at its actual base or
feature multiplier, reports RTP change per paytable unit, and emits a
constrained local recommendation. It never edits the checked-in paytable.
The authoritative five-million-round baseline can be supplied separately so
the optimizer applies sampled derivative deltas instead of treating a noisier
sensitivity run as the absolute profile. Candidate validation replays paired
production and candidate outcomes through the same deterministic reel engine
and audit-only paytable seam. A material prediction error or projected RTP
outside its acceptance bands marks the recommendation `validation-failed`.
Baseline overrides are labeled user-supplied and unverified unless a separate
workflow loads and hashes an artifact. A passing paired replay is only
`locally-validated`; this engineering tool always leaves `releaseReady: false`
until a fresh full five-million-round release audit passes every profile gate.

The tail run uses a defensive full-path mixture of production-uniform sampling
and a biased, full-support stop kernel. It applies the exact path likelihood
ratio, reports global and event effective sample sizes, 95% confidence
intervals, and ordinary-simulation cross-checks at `50x` and `100x`. A run with
weak ESS, too few cap samples, excessive relative error, or failed cross-checks
is labeled `insufficient-evidence`; the tool never labels its output as
certification. The audit stop/paytable seam is not connected to `/api/bets`,
`/api/verify`, game params, or browser code.

The current `clockwork-math-v2.0.4` bounded tail evidence is
`docs/clockwork-caper-v2-tail.json`. Its `100,000` ordinary and `250,000`
importance-sampled rounds cover every anchor and refill draw and pass the
`50x` and `100x` cross-checks. The cap estimate remains
`insufficient-evidence`: `4.05288e-9` (about 1 in 246.7 million), event ESS
`5.438`, RSE `42.88%`, and 95% confidence interval
`6.46411e-10..7.45935e-9`. The point estimate is above the intended band and
the event ESS is too weak for certification, so production remains disabled.

The v2.0.1 and v2.0.2 negative tail evidence is preserved unchanged as
`docs/clockwork-caper-v2.0.1-tail.json` and
`docs/clockwork-caper-v2.0.2-tail.json`; neither applies to v2.0.4.

## Fairness cursor map

Every affected reel consumes one HMAC-derived stop at a fixed cursor. Branching
never shifts or reuses a later cursor.

| Purpose | Cursor |
| --- | ---: |
| Base block | `0..1023` |
| Base anchor, reel `r` | `r`, for `r=0..4` |
| Base refill after winning evaluation `c`, reel `r` | `5 + c*5 + r`, for `c=0..19` |
| Free-spin `i` block | `10000 + i*1024 .. +1023`, for `i=0..49` |
| Free-spin `i` anchor, reel `r` | `10000 + i*1024 + r` |
| Free-spin `i` refill after winning evaluation `c`, reel `r` | `10000 + i*1024 + 5 + c*5 + r` |

The highest used refill offset is 104, leaving the rest of every 1,024-cursor
block reserved. Public RNG evidence records each anchor/refill reel, stop,
cursor, refill count, block start, reel-set version, and cursor-map version.

## Historical verification

`clockwork-catalog-v1` is frozen solely to reproduce historical rounds. New
`/api/bets` outcomes use configured `clockwork-reels-v2`; players cannot select
an algorithm or submit feature/payout state.

`/api/verify` explicitly accepts v1 and v2, rejects unknown versions, and
defaults an omitted `algorithmVersion` to v1 for legacy requests. A v2 proof is
reproduced from the revealed server seed, original server-seed hash, client
seed, nonce, amount, currency precision, immutable reel set, and cursor map.
Clockwork Caper rejects client-authored grids, payouts, multipliers, feature
awards, and cap state.

## Release status and artwork

Demo and Bspin staging configurations enable Clockwork Caper. Production remains disabled
pending explicit approval and the publishing/security gates. This implementation
does not deploy or enable the production game.

All Clockwork Caper artwork was generated specifically for this repository from
original prompts. It does not reuse supplied third-party branding, characters,
logos, or game art. Final prompts and asset paths are retained in the
implementation handoff or PR notes.