@voltro/plugin-leaderboards 0.0.0-stage → 0.87.0

package/README.md

@@ -1,3 +1,1088 @@
-# Temporary Holding Version
+# Leaderboard foundations
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This source is **built**. It provides pure board/score/rank/rating functions
+plus a borrowed SQL adapter. The actual `leaderboardsPlugin(options)` installs
+this adapter, tables, privacy hooks, reader RPCs and durable manual period
+rolls. Automatic reset/season workflows remain unfinished.
+
+## Take
+
+`defineLeaderboard` describes a board; the root and `./leaderboard` export it.
+`./tournaments` exports captured `defineTournament`; `./score` exports `scoreValue`, `scoreString`, `applyScore`; `./ranking` exports
+`rankLeaderboardRecords`, `leaderboardAround`, `defaultLeaderboardTiebreak`,
+`defaultPeriodSummary`, `hashBucket`. `./rating` exports `elo`, `glicko2`, `openskill`. The root now includes server-only installation;
+descriptors import `./rpc`/`./errors`, never the root. Pure leaf subpaths remain
+browser-safe; `./server` is the borrowed SQL/administration entry. Player tournament joining is an explicit intent; score writing remains machine-only.
+
+```ts
+import { Schema } from 'effect'
+import { defineLeaderboard } from '@voltro/plugin-leaderboards/leaderboard'
+import { applyScore } from '@voltro/plugin-leaderboards/score'
+
+const weekly = defineLeaderboard({
+  name: 'weekly-score', sort: 'desc', operator: 'best',
+  metadata: Schema.Struct({ character: Schema.String }),
+  reset: { cron: '0 0 * * 1', timezone: 'UTC', keepHistory: 12 },
+})
+const next = applyScore('9007199254740993', '2', 'increment')
+// next === '9007199254740995'; no JavaScript Number rounding.
+```
+
+The descriptor and arithmetic above do not write SQL or activate a schedule.
+A player score-submit route does not exist. The server `leaderboards.submit`
+Action has a scope guard and the adapter independently refuses human identities;
+only its trusted system calls pass this installed route. Verified cross-app
+service names can call the standalone adapter after explicit allowlisting; plugin
+route service-audience forwarding is still unfinished, so no external service-RPC
+claim follows. Browser RPC imports expose reads only. Service-only submit is the captured
+policy. The server adapter enforces trusted system tasks or explicitly configured
+verified service names; no service is allowed by default and humans cannot submit.
+
+## Configure
+
+| Option | Default | Source budget or meaning |
+|---|---|---|
+| `sort` | `desc` | `asc` makes lower scores better |
+| `operator` | `best` | `best`, `set`, `increment`, `decrement` |
+| `metadata` | required | Actual Effect Schema; trusted JSON metadata must decode without coercion |
+| `submit.via` | `service-only` | Client score submission refuses in this descriptor |
+| `reset` | absent | Captured cron/timezone/history, not an active reset |
+| `maxRankRecords` | 10,000 | Complete supplied pure rank snapshot; at most 100,000 |
+| `maxPageSize` | 100 | Descriptor budget; at most 1,000 and no larger than rank budget |
+
+Cron parsing reuses Effect Cron, with an explicit valid timezone and bounded
+positive history count. Callback/data selection and numeric descriptor values
+are captured. Pure helpers own no score registry, store, timer or hidden authority.
+The adapter retains captured descriptor configuration and persists score authority in SQL. `best` retains the better value for sort direction; `set`
+replaces; increment/decrement use zero for a missing score. Overflow refuses.
+Scores/subscores are canonical decimal strings in the signed SQL BIGINT range
+[-9223372036854775808, 9223372036854775807]. Unsafe Numbers, fractional/exponent/
+leading-zero strings, whitespace and negative zero refuse. SQL idempotency is
+not inferred from pure arithmetic. The adapter additionally preserves winning
+Best subscore/metadata/time when a later score loses or ties without improving
+subscore; the accepted submit counter still increments.
+
+## Hook
+
+`./server` exports `dataStoreLeaderboards(store, options)` and twelve table handles.
+The adapter borrows one DataStore, captures board/provider/clock selections and
+requires verified trusted machine authority for score writes. A subject writer
+fence precedes the board fence; submission receipt, record update and initial
+period creation share one transaction. Exact retries return the original receipt
+before validation and never reapply an increment; changed input refuses. The
+`validate(input, previous, tx)` slot runs inside that transaction; its default
+`acceptLeaderboardSubmission` accepts already validated signed-64-bit scores,
+without inventing game-specific plausibility. Audit retains room/match references.
+
+`top`, `me` and `around` read a complete bounded current-period SQL snapshot for
+the verified human tenant and use exact pure sorting. The installed
+top/me/around Query routes declare the record table as reactive source and use
+these same methods. More rows than `maxRankRecords` refuse, even for Top-1. The
+initial period is created on a first submission; manual rolls close it and
+activate the next period; changing an existing board’s operator/sort refuses
+until a proper configuration/period migration is added. The trusted `rollPeriod`
+and human `history` methods now persist period close/summary/activation.
+Automatic reset workflows, `leaderboard.periodClosed`, automatic match-finished
+event wiring, cron registration and listener privacy remain unfinished.
+
+`./web` exports `useLeaderboardTop(board, limit, apiName)`,
+`useLeaderboardMe(board, apiName)`, `useLeaderboardAround(board, radius, apiName)`
+and `useLeaderboardHistory(board, limit, apiName)`
+through existing subscriptions and installed plugin aliases, without polling.
+`./server` exposes the actual `LeaderboardAdministration` service Tag for
+server-side handlers, not an invented game-stack leaf Port. The owned default
+service clears on deactivation; one plugin instance cannot cross app stores. A pure rank snapshot causes no reward or season side effect.
+SQL is the adapter score truth and the future HotStore rebuild source.
+
+## Durable manual periods
+
+The server adapter and installed internal `LeaderboardAdministration` expose
+`rollPeriod(subject, { tenantId, board, requestId, expectedPeriodId, closedAt })`.
+It requires the same trusted machine authority as submit; no player roll route
+exists. SQL serializes the board, checks the expected active period, creates a
+bounded summary, closes it and activates a deterministic successor in one
+transaction. Stable request identity and full input digest are retained in the
+successor. Recreated adapters and concurrent retries return that stored result;
+changed intention or stale expected period refuses. A close boundary before any
+included score update refuses; this does not implement late cron admission.
+
+`periodSummary(records)` is a captured pure slot. Its default is
+`defaultPeriodSummary`, selecting the first ten ranked records and participant
+count. Overrides may select at most 1,000 exact original rank records, without
+extra metadata or fabricated owners/scores. The byte budget still applies.
+`maxPeriodRows` defaults to 10,000 (at most 100,000), `maxSummaryBytes` to 16,384
+(at most 65,536). Oversized snapshots, history, summaries and privacy work refuse
+instead of truncating work. A declared `keepHistory` marks older closed periods
+archived; records and retry receipts are retained, not garbage-collected.
+
+`leaderboards.history` is a human-tenant reactive reader sourced from the period
+table; the web history hook uses the normal subscription. Current-period score
+views start empty after a roll. Historical summaries are read from SQL. Export
+adds own `periodSummaries`; erase locks persisted tenant boards in stable order,
+removes the owner from summaries and deletes own records/receipts. Retrying an
+old roll returns the currently redacted summary and cannot revive erased data.
+Participant counts remain aggregate history. No schedule or reward is activated
+by this method.
+
+The installed factory also exposes `plugin.leaderboards.service()` as a trusted
+server facade of the same internal service object, useful in ordinary workflow
+steps. It does not construct another adapter or grant browser score authority.
+Calls still require the real machine/human policy for their method, and default
+methods fail unavailable before binding or after deactivation.
+
+For a reset board, active SQL periods now persist the next Effect Cron/timezone
+boundary. Fresh submissions at or after that boundary refuse before validation;
+exact old receipts still return. The next rolled period retains its own next
+boundary. Manual roll can close earlier but cannot skip past a persisted
+deadline. Reset configuration belongs to immutable board configuration, and a
+tournament cannot span beyond its board's next reset boundary. This does not
+install a cron worker; it prevents late admission from silently mixing seasons
+while a worker is unavailable.
+
+## Time-window tournament admission
+
+`defineTournament` on `./tournaments` captures the supplied window and admission
+budgets. These fixed dates are a declaration example, not a running tournament
+or a measured capacity claim. No prize or price is invented.
+
+```ts
+import { Schema } from 'effect'
+import { defineLeaderboard } from '@voltro/plugin-leaderboards/leaderboard'
+import { defineTournament } from '@voltro/plugin-leaderboards/tournaments'
+import { leaderboardsPlugin } from '@voltro/plugin-leaderboards'
+
+const score = defineLeaderboard({ name: 'score', operator: 'best', metadata: Schema.Struct({}) })
+const tournament = defineTournament({
+  name: 'weekend', board: 'score', startsAt: Date.UTC(2026, 9, 10), endsAt: Date.UTC(2026, 9, 12),
+  maxEntries: 100, attemptsPerEntry: 3, joinRequired: true,
+})
+const plugin = leaderboardsPlugin({ boards: [score], tournaments: [tournament] })
+```
+
+At most 256 declared tournaments are accepted, each with a distinct name and
+board present in the board list. Windows use safe integral UTC milliseconds;
+end must follow start. Entry budgets are 1–1,000,000, attempts 1–2,147,483,647,
+with one attempt and explicit join required by default. These remain budgets.
+The captured tournament declaration joins the persisted board configuration. Concurrent changed declarations refuse on reads and writes; rotation needs an explicit migration. Dynamic tournament rotation, automatic settlement and prizes are unfinished.
+
+Players send only `leaderboards.joinTournament({ tournament })`. Owner and tenant
+come from the verified human request. The SQL transaction acquires subject,
+board and tournament fences, binds an empty period and serializes entry capacity.
+Repeated joins retain the original joined time and remaining attempts, including
+an already joined ended-window retry; erased identities refuse. A scored period
+cannot be silently adopted when a tournament is first materialized.
+
+A tournament board requires the trusted score input's matching `tournamentId`.
+Only machine score submissions can consume attempts. With `joinRequired:false`,
+a trusted score atomically admits its owner; otherwise an entry must exist.
+Admission, attempt decrement, score and submission receipt share one transaction;
+a failed policy or overflow rolls them back. Exact submission retries return the
+original receipt before deadline/attempt checks and never spend another attempt.
+New work requires `startsAt <= now < endsAt` and the originally bound active
+period. A manual period roll ends new tournament attempts. Joining another
+owner, supplying attempts or submitting scores from a player is not an API.
+
+`closeTournament(subject, { tenantId, tournament, requestId })` is an actual
+trusted server method on the adapter/internal service. It refuses early closes
+and humans, prepares an empty declared tournament if needed, then calls the same
+SQL-owned period roll at the declared end boundary. Preparation and roll are two
+transactions: uncertain or failed roll work remains retriable under the same
+identity and does not return a successful close. The namespace/digest and stored
+bound period make concurrent/recreated retries use the original transition.
+Changed close identities after closure refuse; empty tournaments produce zero
+participants, without entries or rewards. Later erase redacts the close summary
+through the normal period privacy path. This is a manual operation; cron,
+event/reward outbox and automatic settlement remain unfinished.
+
+`leaderboards.tournamentStatus` returns only the caller's entry plus a dated
+window observation; it reacts to entry/tournament/board writes. Clock-deadline
+invalidation is not installed, so a retained subscription value is not proof the
+window is still open. Every new write checks the actual clock independently. Web
+hooks provide explicit joining and the normal status subscription. SQL table
+roles additionally include `_voltro_lb_tournaments` and
+`_voltro_lb_tournament_entries`; all twelve roles are declared by plugin
+privacy. Export adds own `tournamentEntries`; erase takes tournament fences
+after board fences, removes entries and updates the admitted count in the same
+transaction. Recreated adapters retain the owner tombstone and cannot rejoin
+that identity.
+
+## Override
+
+`rankLeaderboardRecords(records, { sort, tiebreak, maxRecords })` receives a
+complete single-tenant/board/period snapshot, with unique record and owner IDs.
+It detaches/freezes only projected values and returns consecutive ordinal ranks.
+Primary score follows sort; default tie order is higher subscore, earlier
+`updatedAt`, binary owner/record ID. This is not SQL RANK/dense-rank semantics.
+A custom `tiebreak` is called on equal primary scores; non-finite results refuse.
+`leaderboardAround` slices around an owner; missing owners return an empty view.
+`defaultPeriodSummary` returns participant count and bounded top records.
+`hashBucket` gives a deterministic UTF-8 FNV-1a partition for an explicit bucket
+count; it does not establish fixed-size cohort admission or durable assignments.
+Indexed dialect rank queries and full periodSummary policies remain open.
+Persisted capacity-bounded buckets are described below.
+
+`elo({ k: 32, scale: 400 })` returns a pure `rate({ teams, ranks })` function.
+Each player supplies server-owned `id`, finite rating, optional weight in [0,1].
+Ranks start at 1; equal ranks draw. Team strength is its weighted rating mean.
+For each team pair, logistic expected score uses `10 ** ((other - own)/scale)`;
+team delta is `k/(teamCount-1) * (actual - expected)`. Opposite deltas are
+summed and each team's delta is distributed in proportion to participation
+weight. Zero-play members retain ratings; a whole zero-play team refuses. This
+explicit multi-team extension conserves total pairwise delta up to
+floating-point error. Options are captured, inputs are not mutated, results are
+detached/frozen. Budgets: 2–64 teams, 1–256 players/team, at most 4,096 unique
+players; ratings bounded to magnitude 1e9, positive `k`/`scale` at most 1e6.
+These are author budgets, not rating-quality or load evidence. Pure Glicko-2 and
+Weng–Lin Plackett–Luce functions and persisted placement/decay/rate slots are
+included; automatic match-finished event wiring remains unfinished.
+
+### Glicko-2 and Weng–Lin
+
+`glicko2({ tau, epsilon, maxIterations, maxOpponents })` applies one simultaneous
+period to `{ player: { rating, deviation, volatility }, opponents: [{ rating,
+deviation, score }] }`. Scores are0/0.5/1; opponent values are pre-period values.
+No opponents preserves strength/volatility and grows deviation. The bounded
+Illinois solver implements [Glickman's revised algorithm](https://glicko.net/glicko/glicko2.pdf);
+budget exhaustion or non-finite arithmetic refuses the entire computation.
+It is a head-to-head period API, not a fabricated team model.
+
+`openskill({ beta, tau, kappa, ordinalZ })` applies the [Weng–Lin Plackett–Luce
+equations](https://jmlr.org/papers/volume12/weng11a/weng11a.pdf) to `{ teams:
+[[{ id, mu, sigma, weight? }]], ranks }`, preserving supplied team order and
+ties. Its fractional participation extension uses weighted Gaussian team
+means/variances; zero participation keeps the exact prior. It does not claim the
+OpenSkill library's contribution normalization or all of that library's models.
+Risk sets use independent log-sum-exp normalization.
+
+## Extend or replace
+
+The pure tiebreak/summary/rating exports and fixtures are present. Leaderboards
+is a leaf system, so no invented LeaderboardsPort is introduced. Tables are
+`_voltro_lb_boards`, `_voltro_lb_records`, `_voltro_lb_periods`,
+`_voltro_lb_submissions`, `_voltro_lb_subject_admission`,
+`_voltro_lb_tournaments`, `_voltro_lb_tournament_entries`. The adapter’s
+export/erase methods serialize with the same owner fence. Export projects only
+own records and submission audit; erase deletes those and redacts the hashed
+fence’s plain subject ID. Repeated erase/export and adapter recreation retain
+the tombstone; peers and owner-free configuration/period rows survive.
+Historical summaries are scrubbed under the same board fences; anonymous
+historical participant counts remain. No compliance claim follows.
+`maxMetadataBytes` defaults to 16,384 (at most 65,536), `maxExportRows` and
+`maxSubmissionsPerOwner` to 10,000 (at most 100,000 and submissions no larger
+than export budget). Incomplete work refuses.
+
+## Panel and GM
+
+`GET /status` is an actual process-scoped Inspect endpoint with `inspect:read`.
+It returns captured board/operator/sort/service-only policies, snapshot/page/
+metadata/privacy/period/summary budgets and declared tournament windows/admission rules, declared reset/timezone/history, binding and actual
+Default/Custom validation/tiebreak/period-summary selection. It reads no SQL and returns no
+owner, score, metadata schema or allowed service names. Reset scheduling and hot
+index installation are explicitly unfinished; declarations are not live seasons.
+
+The transport-independent `LeaderboardsPage` is connected to Local HTTP
+inspection and the tenant-authorized Cloud proxy/page, with plugin-instance and
+replica selection owned by each host. Both languages, loading/empty/error states
+and focus-preserving guarded reload are present in source. Invalid or failed
+reads hide previous configuration. Live rank/period inspection, bans and GM
+reset/delete actions remain unfinished. No health, capacity or support claim
+follows. Templates and complete manifests remain open.
+
+## Tests
+
+`./testing` exports actual `leaderboardPureFixture`, `leaderboardRecordFixture`
+and `eloFixture`. Adapter tests additionally author actual SQL-port transactions
+on memory: service-only authority, captured metadata, exact original receipts,
+concurrent increments, Best metadata retention, real callback rollback, overflow
+and privacy. Six native dialect variants
+(PostgreSQL/MySQL/MariaDB/MSSQL/SQLite/Turso) each author
+signed-BIGINT/JSON/date/null roundtrip, all four operators, independent
+writer-pool retries, rollback, exact rank ties and successor privacy. Missing
+required fixture credentials fail instead of becoming acceptance skips.
+Installed-plugin fixtures additionally author reader descriptor/source parity,
+real server score submission/player refusal, actual internal Layer, captured
+configuration, privacy and deactivation. Five manual-period memory fixtures and
+two additional scenarios per native dialect author durable retry/races,
+rollback, history, archival and summary privacy. A strict JSON budget fixture is
+also authored.
+
+## SQL-owned rating matches
+
+`ratingPools` captures named algorithm/initial/tuning declarations before
+binding; it adds no player write route. After normal plugin installation, the
+same trusted `leaderboards.leaderboards.service()` provides
+`prepareRatingMatch`, `applyRatingMatch` and `pendingRatingMatches`.
+
+```ts
+import { leaderboardsPlugin } from '@voltro/plugin-leaderboards'
+
+export const leaderboards = leaderboardsPlugin({
+  boards: [],
+  ratingPools: [
+    { name: 'ranked', algorithm: 'elo', initial: { rating: 1000 }, options: { k: 32 } },
+    { name: 'bayesian', algorithm: 'openskill' },
+    { name: 'duel', algorithm: 'glicko2' },
+  ],
+})
+```
+
+Preparation takes `{ tenantId, pool, matchId, teams: [[{ ownerId, weight? }]],
+ranks }` from a trusted system/explicitly allowed verified service. Players supply
+no prior/new ratings or result states. SQL stores the detached intended roster,
+result and request digest under the existing subject fences followed by the pool
+writer fence. A changed retry conflicts. Pool configuration is immutable; fresh
+work and profile reads refuse conflicting declarations.
+
+Application takes only `{ tenantId, pool, matchId }`. It rechecks the stored
+intention under the same subject/pool admission, reads actual SQL priors and runs
+the selected pure algorithm. All owner states, per-owner previous/current receipts
+and match completion commit together. Completion clears the roster. Concurrent/
+recreated exact applies return the original aggregate receipt without spending
+rating updates again. Zero-participation states retain their prior and game count.
+Glicko-2 application accepts two single-player full-participation teams: each match
+is one head-to-head period; a team Glicko model is refused. Rating floats remain
+JSON floats, not rounded leaderboard BIGINT scores.
+
+`leaderboards.myRating` resolves the caller's own tenant/owner; `useMyLeaderboardRating`
+is its alias-aware live hook. An unplayed profile reports the configured initial
+state and zero games. Machine preparation/application/queue access have no browser
+RPC descriptors. This does not complete external service-audience forwarding.
+
+Four additional roles are `_voltro_lb_rating_pools`, `_voltro_lb_ratings`,
+`_voltro_lb_rating_matches` and `_voltro_lb_rating_results`: twelve roles total. Privacy
+locks persisted pools after the original subject/board/tournament fences, including
+pools removed from current configuration. Export includes only owned states/
+receipts and the owner's part of prepared evidence. Erase deletes owned states/
+results, clears affected SQL match links and cancels the whole prepared match
+if it contains that owner. Completed aggregate retries write nothing and cannot
+revive the erased owner; peers keep their already-applied strength. The existing
+subject tombstone refuses fresh preparation for that identity. Bounded privacy
+work refuses instead of truncating retained data.
+
+The process-only four-layer panel now reports declared pool names/algorithms and
+twelve table roles. It never opens SQL or reports player ratings, match
+outcomes, queue counts or active workflows. Authored memory and all-six-native
+fixtures cover concurrent/reopened receipts, JSON/date state, privacy after
+config removal and a real SQL result-key rollback.
+
+The `api-leaderboards` source starter supplies internal `rating.applyMatch` and a
+minute schedule reading a bounded page of SQL-prepared match identities. Workflow
+payload/result contain no owners or ratings. The actual Rooms match.finished
+bridge, durable event settlement, rating-to-board publication, periodic idle decay,
+full journal privacy and cluster crash/replay execution remain open.
+
+## Override rank queries
+
+`rankQuery` is a captured server strategy. `defaultLeaderboardRankQuery` is
+exported from the root and `./server`; `./testing` supplies
+`leaderboardRankQueryFixture(query)` using the actual supplied read capability.
+The default ranks the complete admitted SQL snapshot using exact scores and the
+captured tiebreak. An override may compose it or use `context.query` with an
+app-owned dialect implementation. This is the ordinary DataStore query
+capability; it exposes no write methods or native SQL client.
+
+```ts
+import { Effect } from 'effect'
+import { leaderboardsPlugin, defaultLeaderboardRankQuery } from '@voltro/plugin-leaderboards'
+import { defineLeaderboard } from '@voltro/plugin-leaderboards/leaderboard'
+import { Schema } from 'effect'
+
+const board = defineLeaderboard({ name: 'weekly', metadata: Schema.Struct({}) })
+const plugin = leaderboardsPlugin({
+  boards: [board],
+  rankQuery: context => defaultLeaderboardRankQuery(context).pipe(
+    Effect.map(ids => [...ids].reverse()),
+  ),
+})
+```
+
+This example deliberately reverses the complete order. The context contains
+frozen ranking fields and explicit tenant, board, period, sort and record budget;
+metadata and mutable storage rows stay inside the adapter. Return all original
+record IDs exactly once. The adapter refuses fabricated/duplicate IDs, sparse
+arrays and incomplete prefixes, supplies consecutive ordinal ranks and takes
+scores/metadata from SQL. The same slot drives top, me, around and period summary
+creation. Historical summary reads retain their SQL receipt. Typed refusals
+retain their error code; existing privacy and service-only write admission stay
+in effect. Both dashboard hosts display actual default/custom slot selection.
+
+This foundation still loads one complete bounded SQL snapshot before the slot.
+It does not yet implement indexed COUNT/window ranking or the large-board
+capacity targets.
+
+## Override persisted rating rules
+
+`ratingStrategies` captures three pure slots: `rate`, `placementPolicy` and
+`decay`. The root and `./server` export their single actual defaults,
+`defaultRatingRate`, `defaultRatingPlacement` and `defaultRatingDecay`.
+`./testing` exports `ratingStrategiesFixture()` for all three. The rate default
+uses the declared Elo, PL or head-to-head Glicko implementation; placement uses
+the captured pool initial state; decay preserves the exact prior.
+
+```ts
+import { leaderboardsPlugin, defaultRatingRate, defaultRatingDecay } from '@voltro/plugin-leaderboards'
+
+const plugin = leaderboardsPlugin({
+  boards: [],
+  ratingPools: [{ name: 'ranked', algorithm: 'elo' }],
+  ratingStrategies: {
+    version: 'game-rating-v1',
+    placementPolicy: () => ({ algorithm: 'elo', rating: 1200 }),
+    decay: defaultRatingDecay,
+    rate: context => defaultRatingRate(context),
+  },
+})
+```
+
+Any custom callback requires an application-owned `version`; the `voltro:`
+prefix is reserved for defaults. The SQL pool persists this version with its
+captured configuration. Fresh reads/preparation/application refuse conflicting
+versions across processes. Changing rule meaning needs a new version and an
+explicit pool-data migration or a new pool; no automatic migration is implied.
+A completed aggregate retry returns its SQL receipt without reevaluating rules,
+even if a recreated caller has different rule configuration.
+
+During fresh participated application, a missing SQL state goes through
+placement, and an existing state through decay with actual prior games/time and
+`elapsedMs`. Then rate receives the frozen teams, SQL-derived/placed/decayed
+states, weights, ranks and trusted match/tenant/pool/time. It returns every
+original owner exactly once with the same algorithm and valid bounded numerical
+state. Missing, duplicated or foreign owners, extra fields, sparse arrays,
+non-finite values and algorithm changes refuse the whole application. The adapter
+still owns games, timestamps, SQL results and match completion. It stores actual
+previous SQL state in the audit, rather than an invented client prior. The owner-
+free workflow receipt and existing privacy coverage remain unchanged.
+
+Zero-play owners bypass placement/decay; rate must retain their exact prior.
+Existing state, games and update time are unchanged. New zero-play rows start
+with the base initial state and zero games. Before first participated placement,
+`myRating` displays that configured base initial state without evaluating a rule.
+Decay runs only on fresh participated application, never on reads or retries;
+there is no periodic idle decay worker. Both dashboards show each actual slot's
+default/custom selection without running callbacks or exposing owner values.
+
+Source fixtures cover the pipeline, actual SQL priors/results, captured rules,
+version conflicts, invalid output and zero play, with two additional scenarios
+per native dialect variant. Room result bridging, rating-to-board settlement,
+timer decay, journal privacy and cluster crash/replay execution remain
+unfinished or unverified.
+
+## Persisted capacity-bounded buckets
+
+`buckets: { size, assign, skillWidth? }` now admits real SQL membership in
+`_voltro_lb_bucket_assignments`; the adapter and installed privacy declare twelve
+roles. Size is 1–10,000 and no larger than `maxRankRecords`. `assign` is `hash`,
+`skill` or `cohort`. Skill defaults to width 100 with an explicit finite width
+between 1e-6 and 1e9. These are configuration bounds, not capacity evidence.
+
+```ts
+import { Schema } from 'effect'
+import { defineLeaderboard } from '@voltro/plugin-leaderboards/leaderboard'
+import { leaderboardsPlugin, defaultLeaderboardBucketAssign } from '@voltro/plugin-leaderboards'
+
+const board = defineLeaderboard({
+  name: 'weekly', metadata: Schema.Struct({}),
+  buckets: { size: 50, assign: 'skill', skillWidth: 100 },
+})
+const plugin = leaderboardsPlugin({ boards: [board], bucketAssign: defaultLeaderboardBucketAssign })
+```
+
+Trusted score submission supplies `bucketSkill` for skill grouping or
+`bucketCohort` for cohort grouping. Hash accepts neither. Skills are finite with
+magnitude at most 1e9; cohort identifiers are bounded nonblank strings. Skill
+bands use `floor(skill / skillWidth)`, including negative skills. Cohorts are
+explicit trusted grouping, not a client-supplied rank/score. No human score route
+is added. First admitted membership is fixed for that owner/board/period; later
+trusted skill/cohort changes do not move that membership. Submission digests
+still distinguish changed intent.
+
+The original subject then board writer fence serializes capacity. The adapter
+reads complete bounded period membership, checks group/candidate identity and
+current occupancy, supplies only non-full candidates and creates a new ordinal
+only when the group has no free candidate. `defaultLeaderboardBucketAssign`
+hash-selects an eligible candidate. It is exported from root/`./server`, with
+`leaderboardBucketAssignFixture()` in `./testing`. A custom pure `bucketAssign`
+can choose only one actual admitted candidate; invented/full choices refuse.
+Its required application-owned `bucketStrategyVersion` joins immutable board
+configuration and must not use the reserved `voltro:` prefix. Changing rule
+meaning requires explicit data migration/new board. The callback receives frozen
+scope/group/candidates, no store or mutable membership data.
+
+Records now carry nullable `bucket`. `me`/`around` rank within the owner's
+current bucket on configured boards. `top` defaults to the global order; its
+optional fourth `scope: 'bucket'` argument returns the requesting owner's bucket.
+The browser Top descriptor accepts only `scope: 'global' | 'bucket'`, never a
+foreign owner/tenant/bucket identifier. The web hook is `useLeaderboardTop(board, limit, apiName, 'bucket')`. The rank strategy receives the actual `bucketId` or null for
+global ranking. Reader sources include records, board-period changes and
+membership, so source invalidation covers new periods and erasure. Wire delivery
+still requires execution evidence.
+
+A period roll uses the global summary and starts fresh membership; old
+membership remains in SQL. Export adds only own `bucketAssignments` with
+group/time; erase locks persisted boards and deletes own membership even after
+declaration removal. Remaining members retain their IDs and capacity can be
+reused; erased identities stay fenced. Membership, score and submission receipt
+commit together. Later arithmetic failure rolls back an already inserted
+assignment. Reset rewards, retention and cohort administration remain
+unfinished; no hot bucket cache exists. The current rank/query admission still
+scans a bounded complete snapshot, with `maxRankRecords` as the period
+membership budget. No indexed/large-board/throughput claim follows.
+
+## Pure league, Swiss and elimination plans
+
+`@voltro/plugin-leaderboards/brackets` now contains `roundRobin`,
+`swissPairings`, `seedSingleElimination` and `advanceSingleElimination`. They
+create detached frozen plans/observations, with no SQL, timer, Room reservation,
+workflow, client result authority or reward. The existing `defineTournament`
+still declares a time-window board tournament; these independent primitives do
+not silently enable a new installed format.
+
+```ts
+import { roundRobin, swissPairings, seedSingleElimination, advanceSingleElimination } from '@voltro/plugin-leaderboards/brackets'
+
+const entrants = [
+  { entrantId: 'a', seed: 1 }, { entrantId: 'b', seed: 2 },
+  { entrantId: 'c', seed: 3 }, { entrantId: 'd', seed: 4 },
+]
+const league = roundRobin(entrants, { doubleRound: true })
+const swiss = swissPairings(entrants.map(entrant => ({
+  ...entrant, points: 0, byes: 0, opponents: [],
+})))
+const bracket = seedSingleElimination(entrants)
+const progress = advanceSingleElimination(bracket, [
+  { matchId: 'w1.1', winnerId: 'a' },
+  { matchId: 'w1.2', winnerId: 'b' },
+  { matchId: 'w2.1', winnerId: 'a' },
+])
+```
+
+Entrants carry distinct bounded opaque IDs and a complete seed sequence1..N.
+Input order does not change plans. Inputs reuse strict detached Leaderboards JSON
+admission; accessors, sparse arrays, classes, extra fields and unknown settings
+refuse. Defaults256 entrants,65536 planned matches,100000 search nodes and65536
+input bytes are budgets, never measured tournament capacity. Input/output IDs
+carry no authorization; a server coordinator supplies trusted membership/results.
+
+`roundRobin` uses a fixed-first-seed circle schedule. Every unordered pair appears
+once per leg; every odd roster gets one bye per entrant. `doubleRound:true`
+appends a second leg with swapped orientation. This rotation does not claim a
+particular league's home/away balancing or federation rules.
+
+Swiss takes trusted `points`, `byes` and symmetric distinct `opponents` history.
+Points are nonnegative safe whole scoring units chosen by the studio (win2/draw1,
+for example). Up to128 entrants are admitted under the configured input budget.
+Players sort by points then seed; bounded backtracking tries close-score and seed
+distance partners, refusing rematches. It finds the first complete assignment in
+that order, not a globally optimal or federation-standard pairing. Gap comparison
+uses BigInt; extreme safe scores do not overflow. Odd rosters select only entrants
+with the minimum prior bye count, then lowest score and weakest seed, trying later
+eligible bye choices only when a complete pairing is impossible for earlier ones.
+No solution returns `conflict`; exhausted search returns `limit_exceeded`, never
+a partial plan or proof of impossibility. Search-node counts are algorithm values.
+
+Single Elimination uses conventional mirrored seeds (eight entrants begin1–8,
+4–5,2–7,3–6) and fills a power-of-two graph with explicit byes. Advancement rebuilds
+the exact canonical graph from its roster before accepting winner reports; forged
+edges, duplicate/unknown reports and unresolved/fabricated winners refuse. Byes
+advance automatically, ready matches accept only one of their actual entrants,
+and the last winner becomes champion. Results may be supplied in any order when
+all required predecessors are present. There is no SQL receipt, authority, event
+or exactly-once prize guarantee in this pure reconstruction.
+
+`@voltro/plugin-leaderboards/testing` exports `tournamentPairingFixture` with
+these actual functions and roster/standings. Each rule can be composed in an
+application-owned coordinator. Installed workflow strategy/version/panel
+bindings are still separate work.
+
+No new plugin table or configuration-panel installed capability is claimed.
+
+### Pure Double Elimination graph and conditional final reset
+
+The same entry now also contains `seedDoubleElimination` and
+`advanceDoubleElimination`. Winners reuse mirrored seeding. The lower bracket
+alternates crossed drops from winner rounds and consolidation rounds. Two
+entrants need no lower match. Bye losers propagate as explicit empty slots
+without a loss; only an actual completed match increments its loser. A player
+with two losses cannot enter another ready match.
+
+```ts
+import { seedDoubleElimination, advanceDoubleElimination } from '@voltro/plugin-leaderboards/brackets'
+
+const bracket = seedDoubleElimination([
+  { entrantId: 'a', seed: 1 }, { entrantId: 'b', seed: 2 },
+])
+const resetReady = advanceDoubleElimination(bracket, [
+  { matchId: 'w1.1', winnerId: 'a' },
+  { matchId: 'g1.1', winnerId: 'b' },
+])
+const complete = advanceDoubleElimination(bracket, [
+  { matchId: 'w1.1', winnerId: 'a' },
+  { matchId: 'g1.1', winnerId: 'b' },
+  { matchId: 'g2.1', winnerId: 'a' },
+])
+```
+
+`g1.1` pairs the undefeated winner finalist and the lower finalist. A win by the
+undefeated finalist makes `g2.1` inactive and establishes the champion. A lower
+finalist win activates the reset between the same entrants, now with one loss
+each; its winner becomes champion. Premature/inactive reset reports, fabricated
+winners, duplicate results and modified canonical dependencies refuse. The graph
+is reconstructed from its roster before any result advances it.
+
+Returned observations include pending/ready/walkover/empty/inactive/complete,
+actual winner/loser and per-entrant loss counts. These are pure reconstruction
+values, not committed SQL or live Room evidence. The actual fixture exports both
+functions too. Test expectations are not measured tournament capacity or runtime
+proof. Durable final/Room/reward/ dispute/check-in workflows and UI remain open.
+
+## Leagues: promotion and relegation
+
+A league is a set of division boards, best first. `defineLeague({ name, divisions,
+promote, relegate })` declares one, and `leaderboardsPlugin({ leagues })` installs
+it. A division must be a declared board without buckets, and a board belongs to at
+most one league.
+
+```ts
+import { Schema } from 'effect'
+import { defineLeaderboard, defineLeague, leaderboardsPlugin } from '@voltro/plugin-leaderboards'
+
+const division = (name: string) => defineLeaderboard({ name, operator: 'increment', metadata: Schema.Struct({}) })
+export const ladder = defineLeague({ name: 'ladder', divisions: ['gold', 'silver', 'bronze'], promote: 2, relegate: 2 })
+export const leaderboards = leaderboardsPlugin({ boards: ['gold', 'silver', 'bronze'].map(division), leagues: [ladder] })
+```
+
+Server code works through `leaderboards.service()`:
+
+- `assignLeague(system, { tenantId, league, ownerId, division })` places an owner,
+  for sign-up, seeding or a staff correction.
+- `myLeague(player, league)` returns the caller's division. An owner without one
+  starts in the bottom division.
+- `rollLeague(system, { tenantId, league, requestId, closedAt })` closes every
+  division's current period at `closedAt` and then moves members by the closed
+  ranks. In each division the best `promote` go up and the worst `relegate` go
+  down. A member without a record ranks last, the top division promotes nobody,
+  the bottom division relegates nobody, and nobody moves twice. It returns the
+  closed and new period of each division and the moves.
+- A retry of the same request returns the recorded moves and changes nothing.
+- Export lists a player's division and moves; erase removes both.
+
+A league closes when you call `rollLeague`, or on a schedule.
+`defineLeagueRollSchedule({ league, cron, timezone?, pageSize?, maxPages? })` from
+`@voltro/plugin-leaderboards/server` is an ordinary schedule. Each firing closes the
+league for every tenant with members, at the firing instant, which also names the
+request: a rerun of the same firing moves nobody twice. A tenant that fails does
+not stop the others; the run then fails, and the next run closes what is still
+open. Export it as the default of a file in `schedules/`:
+
+```ts
+import { defineLeagueRollSchedule } from '@voltro/plugin-leaderboards/server'
+
+// Mondays at midnight, Berlin time.
+export default defineLeagueRollSchedule({ league: 'ladder', cron: '0 0 * * 1', timezone: 'Europe/Berlin' })
+```
+
+Staff place or correct a player with the GM action `leagues.assign`
+([GM console](/docs/plugins/gm)).
+
+Checked: the pure move rule, a three-division close with retry and privacy, the
+system contract for both new tables, and the schedule (paging, rerun, a failing
+tenant).
+
+## Explicit SQL bracket registration and check-in
+
+`defineBracketAdmission` on `./tournaments` captures exact author-owned registration
+and check-in windows plus a two-to-256 entry budget. Unknown/accessor data and
+overlapping/non-increasing windows refuse. This is configuration, not a running
+schedule or tournament capacity claim.
+
+```ts
+import { defineBracketAdmission } from '@voltro/plugin-leaderboards/tournaments'
+
+export const bracketWindow = defineBracketAdmission({
+  registrationOpensAt: Date.UTC(2026, 9, 12, 10),
+  registrationClosesAt: Date.UTC(2026, 9, 12, 11),
+  checkInOpensAt: Date.UTC(2026, 9, 12, 11),
+  checkInClosesAt: Date.UTC(2026, 9, 12, 12),
+  maxEntries: 128,
+})
+```
+
+`./server` exports `dataStoreBracketAdmissions(store, options)`, its types and
+`bracketAdmissionsTable` (`_voltro_tournament_admissions`). This table must be
+included in the application's normal migrated schema inventory; the optional
+installed SQL binding described below contributes it to factory/privacy/inspect. The adapter
+borrows SQL and current clock/guards, with no timer/HotStore/pool/global roster.
+`create` and `seal` accept only trusted system or explicitly authorized service
+Subjects; the supplied current `authorize` policy still runs. `register`,
+`checkIn` and `status` accept verified user/guest self-intentions in their exact
+tenant, never caller-supplied owner state. All callbacks/data are captured before
+lazy execution; no successful authorization or withdrawal default is provided.
+
+Scoped SQL row locks serialize capacity/entry and check-in receipts. Creation
+retry must preserve the complete window/configuration; old registration/check-in
+receipts do not allocate another entry or timestamp. Fresh admission checks real
+half-open deadlines. Seal runs only after check-in close and returns persisted
+checked-in/no-show identities to the authorized machine; it does not invent
+rating/seed, apply a no-show penalty, create Rooms, advance a graph or grant prizes.
+Human status contains counts and only its own entry. Recreated adapters read SQL;
+there is no in-process authority or fallback. Accepted SQL promises are awaited
+even when the surrounding Effect is interrupted.
+
+`exportSubject` validates a complete bounded tenant inventory and projects only
+the selected subject's association, no peer identity. `eraseSubject` requires
+actual permanent app Subject withdrawal/quiescence, then journals erasing before
+external tournament withdrawal, outside SQL. Exact request plus target digest
+fences a conflicting cleanup. Failure retains participant data and receipt; a
+fresh adapter retries. Only confirmed withdrawal removes the selected identity
+and cancels further admission to that tournament. Other participants remain;
+the real app must cancel/await Rooms, timers, rewards and external copies. Receipt
+digests are pseudonymous data; retention/removal policy is still open. A callback
+or phase is no proof that distributed withdrawal happened. Oversized/corrupt
+inventories refuse, never truncate privacy work.
+
+The existing six native SQL fixture lanes now migrate this actual table through
+normal schema apply and invoke the same body with an independent pool; no native
+checks ran. Supplied Subjects/guards/withdrawal are explicit fixture policies.
+
+## Installed bracket admission and replacement port
+
+The optional `brackets` binding installs the same registration/check-in kernel.
+SQL binding contributes `_voltro_tournament_admissions` to ordinary schema apply,
+declares it in the shared subject privacy inventory and provides the seven-method
+`BracketAdmissionPort` from `./ports`. The installed server facade is
+`plugin.leaderboards.brackets()`; `plugin.services` provides that same facade to
+the ordinary application Effect context. No separate Runtime or SQL pool exists.
+Standalone `bracketAdmissionLayer(store, options)` on `./server` uses the same
+adapter. Explicit guards, permanent subject withdrawal, external tournament
+withdrawal, export authorization and a clock remain required owner bindings.
+
+```ts
+import { leaderboardsPlugin } from '@voltro/plugin-leaderboards'
+import type { BracketAdmissionOptions } from '@voltro/plugin-leaderboards/server'
+
+export const tournamentPlugin = (admission: BracketAdmissionOptions) =>
+  leaderboardsPlugin({ boards: [], brackets: { backend: 'sql', options: admission } })
+```
+
+With no binding the optional table, routes and Tag are absent. The server facade
+refuses work. Existing score/rating/time-window behavior remains separate.
+With a binding, browser-safe RPC descriptors and `./web` hooks provide
+`useRegisterBracket`, `useCheckInBracket` and `useBracketAdmissionStatus`.
+Players send only `{ tournamentId }`; the authenticated user/guest identity and
+tenant come from the request. Creation/sealing have no browser mutation route.
+The current supplied policy still admits or refuses each operation. The SQL
+status subscription invalidates from the actual admission table.
+
+An entire replacement uses `{ backend: 'custom', version, service, sources }`.
+`service` must implement all seven methods, including privacy. The captured
+non-reserved version names the app implementation, and `sources` explicitly
+names its one-to-32 normal application table invalidation sources. This factory
+does not install a pretend SQL admission table for a replacement. The app owns
+those tables, normal migrations, privacy and source invalidation. Replacing the
+Tag through a normal Layer permits independent consumers; replacing the factory
+binding keeps these built-in routes and hooks on the same implementation.
+
+Installed export combines the current score/rating export with own bracket
+associations. Erasure awaits the bracket withdrawal/journal before score data
+erasure; a failed bracket hook leaves the combined hook incomplete. Receipt
+digest retention and real distributed Rooms/timer/reward quiescence still need
+their full app contract. Deactivation refuses new Port work and awaits locally
+admitted whole Effects. Custom services must await their actual accepted external
+work; the counter is no all-node withdrawal proof. Base score-service teardown
+and complete workflow/history privacy remain separate open work.
+
+The existing read-only `/status` endpoint and both dashboards now carry the
+required `brackets` configuration or `null`: backend, version, binding and complete
+tenant inventory budget. The conditional thirteen-table SQL inventory is exact;
+replacements show app-owned bounds and no default admission role. Stage workflow
+installation is explicitly false. No owner, roster, result, SQL count, credentials
+or source table names are shown. The shared EN/DE section inherits current reload,
+error, scope and focus behavior. Binding does not prove health or a live tournament.
+
+`./testing` exports `fakeBracketAdmissionService`, `bracketAdmissionFakeLayer`
+and the actual `bracketAdmissionPortFixture`; omitted fake methods fail
+unavailable.
+
+## Durable elimination results, disputes and external-work journals
+
+`./server` exports `dataStoreTournamentBrackets`, `tournamentBracketLayer` and
+`tournamentBracketsTable` (`_voltro_brackets`). This explicit server coordinator
+uses canonical Single/Double Elimination and a two-to-64 entrant source budget.
+The application ordinarily migrates that table and the shared
+`leaderboardSubjectsTable`; it supplies this table's full privacy hooks and the
+eight-method `TournamentBracketPort` from `./ports`. Automatic factory binding,
+public bracket/schedule UI and workflow registration are still open. No hidden
+scheduler, pool, cache, Tick I/O, Room result or grant is generated.
+
+```ts
+import { tournamentBracketLayer } from '@voltro/plugin-leaderboards/server'
+import type { TournamentBracketOptions } from '@voltro/plugin-leaderboards/server'
+import type { DataStore } from '@voltro/database'
+
+export const bracketLayer = (store: DataStore, bindings: TournamentBracketOptions) =>
+  tournamentBracketLayer(store, bindings)
+```
+
+Creation captures the complete contiguous seeded roster, format and immutable
+application `ruleVersion`. Only authorized machines create/report/resolve/advance/
+read the internal status. The caller obtains this roster from actual sealed
+check-in/rating policy; this adapter does not invent rating seeding or no-show
+penalties. Actual canonical pairing implementations own graph progression.
+
+`advance` prepares at most one external work item under SQL admission. A ready
+match journals its exact private roster and deterministic request identity before
+the supplied `provisionRoom` runs outside the transaction. A confirmed receipt
+contains only roomId/epoch, no credential or fabricated player Subject. Lost
+replies retain pending SQL work; recreated adapters offer the same identity and
+roster again. The actual app Room participant must make that retry idempotent,
+enforce private metadata/roster/current grants and await accepted reservations.
+SQL confirmation refuses a changed receipt or a pause/erase fence. Concurrent
+callers can offer the same key; this journal alone cannot promise exactly-once
+Room creation. No success default exists for that external service.
+
+Only a trusted machine can report a result for the current ready match and its
+confirmed Room/epoch. The supplied current `verifyResult` policy verifies real
+Room authority. Fresh work rechecks admission after verification. The original
+report identity/winner are retained separately from a later GM decision; exact
+confirmed retries do not reverify or rewrite a result. Altered/foreign/unready
+reports refuse. Participants send only their own dispute intent with an allowed
+reason code. A dispute pauses further work before a GM resolution. Corrections
+that would invalidate any admitted descendant Room/result refuse; the app must
+withdraw/cancel that work rather than silently rewrite the tournament. Settlement
+already pending/completed closes this local dispute path; appeal timing is an
+explicit application policy, not a guessed timer.
+
+A canonical champion journals one deterministic settlement identity before the
+supplied real economy/inventory/Inbox participant runs. Its retry must enforce
+durable idempotency and whole participant outcomes; no price, currency or reward
+is invented here. The bracket becomes complete only after confirmed settlement.
+Accepted Effects/SQL promises are awaited on interruption. Retention, event
+delivery, reminders, scheduled stage progression and complete prize/provider
+integration remain open; a fixture service is no production participant proof.
+
+Scores/ratings, bracket admission and this coordinator share one current SQL
+subject-fence implementation with unchanged persisted identity keys. Registration/
+check-in acquire subject before tournament; seal and graph writers acquire the
+complete sorted subject roster first and refuse changed/erased rosters. Creation
+cannot associate an already erased owner, even under a machine request. Standalone
+admission now also needs `leaderboardSubjectsTable` in normal migration.
+
+Own export projects seed, own result outcome/Room links and own dispute metadata,
+never a peer roster. Erase requires permanent app withdrawal, then records the
+same SQL subject tombstone before complete bounded inventory. A per-tournament
+erase receipt precedes actual external withdrawal, including pending identities
+whose Room replies were lost. Failure retains graph/associations; a recreated
+adapter retries. Confirmed withdrawal cancels the whole shared graph, clears
+Room/result/dispute/settlement associations and removes the target roster entry.
+Peer roster entries remain until their own erasure; repeated erasure handles a
+partially scrubbed cancelled roster without reinterpreting it as a new bracket.
+Exact completed retries skip confirmed external cancellation. Digests/fence keys
+are pseudonymous data; retention/removal is still open. SQL fencing does not
+withdraw actual remote resources; the app must prevent late external work and
+await every accepted Room/reward/workflow association.
+
+Its Room/grant consumers are explicit lost-reply fault models; they prove
+nothing about actual Rooms/economy/Inbox. `./testing` exports the actual
+fail-closed eight-method service/Layer/Port fixture.
+
+## Ordinary durable tournament stage and advance workflows
+
+`./server` exports the optional `leaderboardsTournamentSources` app-shaped root,
+`tournamentStageExecutor` and `tournamentAdvanceExecutor`. It contains ordinary
+browser-safe `tournament.stage`/`tournament.advance` descriptors and paired server
+executors. The normal library build copies the actual source folder into the
+published package. These are explicit discovery sources; exporting them does not
+install a worker, start a timer or provide missing app services. The app must add
+this root through normal plugin discovery and provide actual Stage/Bracket Ports,
+schema/privacy and external participants. The optional factory graph/Stage binding below contributes these sources when Stage is configured; actual default external participants remain open.
+
+```ts
+import { tournamentStageLayer, leaderboardsTournamentSources } from '@voltro/plugin-leaderboards/server'
+import type { TournamentStageOptions } from '@voltro/plugin-leaderboards/server'
+import type { DataStore } from '@voltro/database'
+
+export const stageLayer = (store: DataStore, bindings: TournamentStageOptions) =>
+  tournamentStageLayer(store, bindings)
+
+export const tournamentSourceRoot = leaderboardsTournamentSources
+```
+
+Both workflows are internal, operator-control scope `tournaments:operate`, and
+singleton-skip per exact tenant/tournament for the stage; advance queues (`concurrency: { limit: 1 }`). Start keys include the explicit runKey;
+stage also includes format/rule version. JSON tuple keys avoid delimiter ambiguity.
+The ordinary run AppContext supplies the actual machine identity, which server
+executors capture with payload before lazy work. No fabricated user or service
+identity is introduced. Current adapters still authorize every operation; a start
+guard does not grant permanent authority after a long sleep.
+
+The stage checkpoints only admission configuration, sleeps to absolute
+registration/check-in/close instants with the shipped `sleepUntil`, calls actual
+notification participants through steps, then seals and seeds in one step. A late
+attempt or sealed/cancelled window skips obsolete reminders. A successful notify
+flag follows the actual awaited callback, not merely a timer wakeup. The
+`TournamentStagePort`/`tournamentStageLayer` borrows the existing SQL header reader,
+actual Admission/Bracket services, current clock/authorization and explicit
+`notifyEntrants`/`seedRoster` participants. No separate store/pool/Runtime exists.
+
+`seedRoster` receives actual sealed checked-in/no-show identities only inside the
+server Effect. It must recover a stable durable seed/no-show/rating decision under
+the same deterministic request identity across retries and fresh adapters. The
+returned complete seed roster must contain exactly the checked-in participants;
+foreign/missing/duplicate or invalid seeds refuse before graph creation. No-show
+penalties and rating tie rules are author policy. Fewer than two valid participants
+cannot be silently fabricated into a bracket. The actual graph adapter rechecks
+the shared SQL Subject fences, so an erased participant cannot be re-associated.
+
+Advance checkpoints one real graph/external-work operation. Workflow payloads,
+step inputs/results and final summaries contain only scope/configuration/counts;
+no roster, winner, prior/result ratings, Room credential or reward outcome. Unknown,
+duplicate or inconsistent status observations refuse rather than turning into
+zero counts. SQL remains graph truth; workflow recovery still delegates exact
+resource keys to real downstream participants. Event-triggered starts, automatic
+repeated advancement, pauses/schedule UI and real scheduler/engine replay are
+not established by these sources.
+
+Stage notifications/seeding can create durable app associations before graph
+creation. Full withdrawal must cancel/await workflows and those participants as
+well as Rooms/rewards, including pending request identities; hook receipt or a
+count is no all-node proof. Subject export/erase of engine journals, notification
+receipts and seeding records belongs to their actual owners and remains open.
+The read-only factory panel correctly keeps workflowInstalled:false until the
+factory really installs that worker; explicit app sources are not claimed there.
+
+Seed snapshots/notifications in that body are explicit participant models, not
+real rating/Inbox proof. No clock/Activity engine was faked into a workflow
+pass.
+
+
+### Advancing a bracket and the player read
+
+One `tournament.advance` run does all open work: one journaled step per ready match
+without a Room (`advance-1`, `advance-2`, …), and the champion's settlement once
+the bracket is decided. It ends when nothing is left or a step makes no progress.
+A paused bracket (an open dispute) refuses with `conflict` until staff resolve it.
+`tournament.stage` runs the same steps right after seeding, so the first round's
+Rooms exist when the stage ends.
+
+Later rounds become ready when results arrive. After `report` (or `resolve`),
+use `reportTournamentResult` (reports and queues `tournament.advance`, report ID as `runKey`);
+nothing runs on a timer. The workflow summary adds `waiting`: ready matches without a
+Room, plus one while the champion awaits settlement.
+
+Bracket status lists each match's `roomId` once provisioned. Players read their
+own matches with `leaderboards.myBracketMatches({ tournamentId })` /
+`useMyBracketMatches(tournamentId)`, live from the bracket table: phase, whether
+the caller is champion, and per match the round, status, opponent, Room and
+result. Only verified users can read it, and only their own matches. The route
+reads status as the system subject `leaderboards.myBracketMatches`, so your
+`authorize` policy must allow `status` for it.
+
+```tsx
+import { useMyBracketMatches } from '@voltro/plugin-leaderboards/web'
+
+export function MyMatches({ tournamentId }: { tournamentId: string }) {
+  const { data } = useMyBracketMatches(tournamentId)
+  if (data === undefined) return null
+  return (
+    <ul>
+      {data.matches.map(match => (
+        <li key={match.matchId}>
+          Round {match.round}: {match.opponentId ?? 'bye'}, {match.roomId === null ? 'waiting for a Room' : 'Room ' + match.roomId}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+Checked on the in-memory workflow engine: a round robin's six Rooms in one run,
+settlement in a later run, a run that waits for results, a paused bracket, the
+stage's first round, and the installed player read.
+
+## Optional installed tournament graph and stage
+
+`leaderboardsPlugin` accepts `tournamentCoordination` in addition to optional
+`brackets` admission. A SQL graph binding is `{ backend: 'sql', options }`, using
+actual `TournamentBracketOptions`. It contributes `_voltro_brackets` to the
+ordinary schema and declared subject privacy. The factory already contributes
+the shared Subject fence table; no second pool, runtime, clock loop or cache is
+created. Without coordination, its table, Tags, intent route and discovery roots
+are absent; its server facades fail unavailable.
+
+```ts
+import { leaderboardsPlugin } from '@voltro/plugin-leaderboards'
+import type { LeaderboardsPluginOptions } from '@voltro/plugin-leaderboards'
+
+export const tournamentPlugin = (bindings: LeaderboardsPluginOptions) =>
+  leaderboardsPlugin(bindings)
+```
+
+A full replacement is `{ backend: 'custom', version, service, sources }`: all eight
+`TournamentBracketPort` methods, a non-reserved application version and complete
+actual invalidation source names are required. It contributes no default graph
+SQL table. Methods/options/source names are captured before app binding; accessor
+bindings, partial services and reserved custom versions refuse. Replacement owners
+must still implement current authorization, SQL rebuild, privacy, exact downstream
+idempotency and withdrawal; capture alone is no conformance proof.
+
+The same installed services are available through `plugin.leaderboards.tournaments()`
+and actual `TournamentBracketPort` Layers. `plugin.leaderboards.tournamentStages()`
+and `TournamentStagePort` exist when `stage` is configured. A SQL stage binding is
+`{ backend: 'sql', options, privacy }`; its four options are `epochNow`, `authorize`,
+`seedRoster`, `notifyEntrants`. The factory captures the actual graph and admission
+services. SQL Stage requires the SQL admission binding, because its window reader
+uses that registered table. A custom stage binding is
+`{ backend: 'custom', version, service, privacy }`, with all three Stage methods.
+Every stage binding requires real `privacy.exportSubject` and `privacy.eraseSubject`
+participants for seed/reminder associations, including accepted pending work.
+No successful empty participant is supplied by the factory.
+
+With Stage configured, the factory contributes the ordinary app-shaped stage and
+advance source root under the stable `tournaments` discovery name. Optional
+`workflowSources` replaces that root with an absolute application directory;
+normal discovery checks directory existence, overlap and procedure collisions.
+An override without Stage refuses. These are regular descriptor/server pairs,
+using existing workflow primitives; no parallel scheduler or hidden immediate
+start. No Stage means no workflow source. Configured discovery is distinct from
+observed execution and real downstream delivery.
+
+The browser write is `leaderboards.disputeBracket`/`useDisputeBracket`:
+tournament, match, dispute identity and a reason code. The actual request supplies
+human identity and tenant; machine browser calls refuse. Results, winners, scores,
+Rooms and rewards cannot be submitted through this operation. The actual graph
+adapter checks own match participation/current authority, pauses disputed work,
+and returns only aggregate phase/counts. Reporting, resolution, creation and
+advance remain trusted server Ports. The player read is `myBracketMatches` (above).
+Public bracket screens remain open.
+
+Export awaits actual Stage participant export, graph-own export, admission and
+score export. Erase withdraws Stage participants before graph, admission and scores;
+a failed Stage withdrawal leaves downstream SQL cleanup incomplete. Each graph
+adapter retains its own external withdrawal journal. Callbacks must enforce
+permanent all-node withdrawal, not merely delete a local timer. Custom Stage data
+must join its supplied privacy participant; engine journals belong to workflow
+privacy separately. Neither registry coverage nor a declared hook proves erasure.
+
+Local shutdown closes every optional facade before waiting for admitted whole
+Effects. An already admitted SQL Stage borrows the captured real seal/create
+services until its own Effect settles, so later dependency calls survive facade
+closure. No new work or app rebinding follows closure. This is local lifecycle
+coordination, not distributed actor/worker/provider quiescence or score-service
+teardown proof.
+
+Four-layer process inspection now requires `coordination:null/config`, exact
+conditional thirteen/fourteen table roles, SQL/custom version and budget semantics,
+Stage backend/binding and default/custom workflow source selection. SQL Stage
+without SQL admission and contradictory bound/source shapes refuse in Shared,
+Cloud and Local decoding. The existing bilingual page shows bindings/configuration,
+never participants, graph results, winners, provider credentials, source paths,
+prize outcomes or live worker state. `workflowRuntimeObserved:false` explicitly
+retains the missing runtime observation. Failed refresh hides stale configuration.
+
+External Room, prize, notification and seed callbacks in fixtures are explicit
+models.
+
+
+## Production license admission
+
+Declare the actual `licensingPlugin()` before this plugin in the API app. Production and staging activation require its verified active or grace deployment-wide license to grant `leaderboards`. Explicit development/test mode stays free without recurring per-instance notices; CLI owns the actual template first-boot receipt. Tenant-scoped licenses refuse until actual tenant-bound authority exists. This server-only gate preserves normal schema, store binding and cleanup; it runs before the original activation hook, not before schema/store binding.