@voltro/plugin-leaderboards 0.0.0-stage → 0.88.0

package/dist/index.d.ts

@@ -0,0 +1,1208 @@
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { PluginPrivacyRequest } from '@voltro/protocol';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { VoltroPlugin } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+declare interface AdmissionState {
+    readonly version: 1;
+    readonly definition: BracketAdmissionDefinition;
+    readonly phase: 'open' | 'sealed' | 'erasing' | 'cancelled';
+    readonly entries: ReadonlyArray<BracketAdmissionEntry>;
+    readonly eraseRequest: string | null;
+    readonly eraseTarget: string | null;
+}
+
+export declare interface ApplyRatingMatchInput {
+    readonly tenantId: string;
+    readonly pool: string;
+    readonly matchId: string;
+}
+
+/** Submission idempotency belongs to SQL, not this pure arithmetic function. */
+export declare const applyScore: (previous: string | bigint | number | null, submitted: string | bigint | number, operator: ScoreOperator, sort?: LeaderboardSort) => string;
+
+declare type BracketAdmissionBinding = {
+    readonly backend: 'sql';
+    readonly options: BracketAdmissionOptions;
+} | {
+    readonly backend: 'custom';
+    readonly version: string;
+    readonly service: BracketAdmissionService;
+    readonly sources: ReadonlyArray<string>;
+};
+
+declare interface BracketAdmissionDefinition {
+    readonly registrationOpensAt: number;
+    readonly registrationClosesAt: number;
+    readonly checkInOpensAt: number;
+    readonly checkInClosesAt: number;
+    readonly maxEntries: number;
+}
+
+declare interface BracketAdmissionEntrants {
+    readonly phase: AdmissionState['phase'];
+    readonly entries: ReadonlyArray<BracketAdmissionEntry>;
+}
+
+declare interface BracketAdmissionEntry {
+    readonly ownerId: string;
+    readonly joinedAt: number;
+    readonly checkedInAt: number | null;
+}
+
+declare interface BracketAdmissionExport extends BracketAdmissionEntry {
+    readonly tournamentId: string;
+    readonly phase: BracketAdmissionStatus['phase'];
+}
+
+declare interface BracketAdmissionOptions {
+    readonly epochNow: () => number;
+    readonly maxTenantTournaments?: number;
+    /** Normal current application guards; no successful policy is provided. */
+    authorize(subject: Subject, scope: BracketAdmissionScope, operation: 'create' | 'register' | 'checkIn' | 'status' | 'seal' | 'entrants'): Effect.Effect<void, LeaderboardError>;
+    /** Permanent Subject admission fence + await every accepted app association. */
+    withdrawSubject(request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+    /** Cancel and await actual Rooms/timers/rewards that use this sealed roster. */
+    withdrawTournament(scope: BracketAdmissionScope, request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+    authorizeExport(request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+}
+
+/** Browser-safe Tag; consumers depend on admission, never a SQL adapter. */
+export declare class BracketAdmissionPort extends BracketAdmissionPort_base {
+}
+
+declare const BracketAdmissionPort_base: Context.ServiceClass<BracketAdmissionPort, "@voltro/BracketAdmissionPort", {
+    create(subject: Subject, scope: BracketAdmissionScope, definition: BracketAdmissionDefinition): Effect.Effect<void, LeaderboardError>;
+    register(subject: Subject, scope: BracketAdmissionScope): Effect.Effect<BracketAdmissionStatus, LeaderboardError>;
+    checkIn(subject: Subject, scope: BracketAdmissionScope): Effect.Effect<BracketAdmissionStatus, LeaderboardError>;
+    status(subject: Subject, scope: BracketAdmissionScope): Effect.Effect<BracketAdmissionStatus, LeaderboardError>;
+    seal(subject: Subject, scope: BracketAdmissionScope): Effect.Effect<BracketAdmissionRoster, LeaderboardError>;
+    /** Trusted read of every registration with its check-in, for notifications. */
+    entrants(subject: Subject, scope: BracketAdmissionScope): Effect.Effect<BracketAdmissionEntrants, LeaderboardError>;
+    exportSubject(request: PluginPrivacyRequest): Effect.Effect<ReadonlyArray<BracketAdmissionExport>, LeaderboardError>;
+    eraseSubject(request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+}>;
+
+declare interface BracketAdmissionRoster {
+    readonly checkedIn: ReadonlyArray<string>;
+    readonly noShows: ReadonlyArray<string>;
+}
+
+declare interface BracketAdmissionScope {
+    readonly tenantId: string;
+    readonly tournamentId: string;
+}
+
+export declare type BracketAdmissionService = Context.Service.Shape<typeof BracketAdmissionPort>;
+
+declare interface BracketAdmissionStatus {
+    readonly phase: AdmissionState['phase'];
+    readonly entries: number;
+    readonly checkedIn: number;
+    readonly own: BracketAdmissionEntry | null;
+}
+
+declare interface BracketMatchObservation {
+    readonly id: string;
+    readonly round: number;
+    readonly left: string | null;
+    readonly right: string | null;
+    readonly status: 'pending' | 'ready' | 'walkover' | 'complete';
+    readonly winnerId: string | null;
+}
+
+declare interface BracketProgress {
+    readonly matches: ReadonlyArray<BracketMatchObservation>;
+    readonly champion: string | null;
+}
+
+declare type BracketSlot = {
+    readonly kind: 'entrant';
+    readonly entrantId: string;
+} | {
+    readonly kind: 'winner';
+    readonly matchId: string;
+} | {
+    readonly kind: 'bye';
+};
+
+declare interface BracketState extends TournamentBracketDefinition {
+    readonly version: 1;
+    readonly phase: 'active' | 'paused' | 'complete' | 'erasing' | 'cancelled';
+    readonly withdrawn: boolean;
+    readonly provisions: ReadonlyArray<Provision>;
+    readonly results: ReadonlyArray<Result>;
+    readonly disputes: ReadonlyArray<Dispute>;
+    readonly settlement: {
+        readonly requestId: string;
+        readonly winnerId: string;
+        readonly complete: boolean;
+    } | null;
+    readonly erase: {
+        readonly requestId: string;
+        readonly targetDigest: string;
+    } | null;
+}
+
+declare interface CloseLeaderboardTournamentInput {
+    readonly tenantId: string;
+    readonly tournament: string;
+    readonly requestId: string;
+}
+
+/** Bounded SQL snapshot foundation: no hot board, reset scheduler or client writes. */
+declare const dataStoreLeaderboards: (store: DataStore, input: LeaderboardStoreOptions) => {
+    assignLeague: (subject: Subject, original: {
+        readonly tenantId: string;
+        readonly league: string;
+        readonly ownerId: string;
+        readonly division: string;
+    }) => Effect.Effect<{
+        readonly league: string;
+        readonly division: string;
+    }, LeaderboardError>;
+    myLeague: (subject: Subject, league: string) => Effect.Effect<{
+        readonly league: string;
+        readonly division: string;
+        readonly assigned: boolean;
+    }, LeaderboardError>;
+    rollLeague: (subject: Subject, original: {
+        readonly tenantId: string;
+        readonly league: string;
+        readonly requestId: string;
+        readonly closedAt: number;
+    }) => Effect.Effect<{
+        readonly divisions: ReadonlyArray<{
+            readonly division: string;
+            readonly closedPeriodId: string;
+            readonly activePeriodId: string;
+        }>;
+        readonly movements: ReadonlyArray<LeagueMovement>;
+    }, LeaderboardError>;
+    leagueTenants: (subject: Subject, original: {
+        readonly league: string;
+        readonly after?: string | null;
+        readonly limit: number;
+    }) => Effect.Effect<{
+        readonly tenants: ReadonlyArray<string>;
+        readonly next: string | null;
+    }, LeaderboardError>;
+    prepareRatingMatch: (subject: Subject, original: PrepareRatingMatchInput) => Effect.Effect< RatingMatchReceipt, LeaderboardError, never>;
+    applyRatingMatch: (subject: Subject, original: ApplyRatingMatchInput) => Effect.Effect< RatingMatchReceipt, LeaderboardError, never>;
+    myRating: (subject: Subject, poolName: string) => Effect.Effect<{
+        pool: string;
+        state: {
+            readonly algorithm: "elo";
+            readonly rating: number;
+        } | {
+            readonly algorithm: "openskill";
+            readonly mu: number;
+            readonly sigma: number;
+        } | {
+            readonly algorithm: "glicko2";
+            readonly rating: number;
+            readonly deviation: number;
+            readonly volatility: number;
+        };
+        games: number;
+        updatedAt: number | null;
+    }, LeaderboardError, never>;
+    pendingRatingMatches: (subject: Subject, tenantId: string, poolName: string, limit?: number) => Effect.Effect<{
+        tenantId: string;
+        pool: string;
+        matchId: string;
+    }[], LeaderboardError, never>;
+    closeTournament: (subject: Subject, original: CloseLeaderboardTournamentInput) => Effect.Effect<RollLeaderboardPeriodResult, LeaderboardError>;
+    joinTournament: (subject: Subject, tournamentName: string) => Effect.Effect<{
+        readonly tournament: string;
+        readonly joinedAt: number;
+        readonly attemptsLeft: number;
+    }, LeaderboardError, never>;
+    tournamentStatus: (subject: Subject, tournamentName: string) => Effect.Effect<{
+        readonly tournament: string;
+        readonly board: string;
+        readonly startsAt: number;
+        readonly endsAt: number;
+        readonly observedAt: number;
+        readonly joinRequired: boolean;
+        readonly state: "open" | "upcoming" | "ended";
+        readonly entry: {
+            readonly tournament: string;
+            readonly joinedAt: number;
+            readonly attemptsLeft: number;
+        } | null;
+    }, LeaderboardError, never>;
+    rollPeriod: (subject: Subject, original: RollLeaderboardPeriodInput) => Effect.Effect<RollLeaderboardPeriodResult, LeaderboardError>;
+    history: (subject: Subject, boardName: string, limit?: number) => Effect.Effect<{
+        readonly id: string;
+        readonly board: string;
+        readonly startsAt: number;
+        readonly endsAt: number | null;
+        readonly state: "closed" | "active" | "archived";
+        readonly summary: {
+            readonly participants: number;
+            readonly top: readonly {
+                readonly id: string;
+                readonly tenantId: string;
+                readonly board: string;
+                readonly periodId: string;
+                readonly ownerId: string;
+                readonly score: string;
+                readonly subscore: string;
+                readonly updatedAt: number;
+                readonly rank: number;
+            }[];
+        } | null;
+    }[], LeaderboardError, never>;
+    submit: (subject: Subject, original: SubmitLeaderboardInput) => Effect.Effect<LeaderboardRecord, LeaderboardError>;
+    top: (subject: Subject, boardName: string, limit?: number, scope?: "global" | "bucket") => Effect.Effect<{
+        rank: number;
+        id: string;
+        board: string;
+        periodId: string;
+        ownerId: string;
+        score: string;
+        subscore: string;
+        numSubmits: number;
+        metadata: {
+            readonly [x: string]: unknown;
+        };
+        updatedAt: number;
+        bucket: string | null;
+    }[], LeaderboardError, never>;
+    me: (subject: Subject, boardName: string) => Effect.Effect<{
+        rank: number;
+        id: string;
+        board: string;
+        periodId: string;
+        ownerId: string;
+        score: string;
+        subscore: string;
+        numSubmits: number;
+        metadata: {
+            readonly [x: string]: unknown;
+        };
+        updatedAt: number;
+        bucket: string | null;
+    } | null, LeaderboardError, never>;
+    around: (subject: Subject, boardName: string, radius?: number) => Effect.Effect<{
+        rank: number;
+        id: string;
+        board: string;
+        periodId: string;
+        ownerId: string;
+        score: string;
+        subscore: string;
+        numSubmits: number;
+        metadata: {
+            readonly [x: string]: unknown;
+        };
+        updatedAt: number;
+        bucket: string | null;
+    }[], LeaderboardError, never>;
+    exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<{
+        records: {
+            readonly id: string;
+            readonly board: string;
+            readonly periodId: string;
+            readonly ownerId: string;
+            readonly score: string;
+            readonly subscore: string;
+            readonly numSubmits: number;
+            readonly metadata: {
+                readonly [x: string]: unknown;
+            };
+            readonly updatedAt: number;
+            readonly bucket: string | null;
+        }[];
+        submissions: {
+            id: unknown;
+            board: unknown;
+            periodId: unknown;
+            record: {
+                readonly id: string;
+                readonly board: string;
+                readonly periodId: string;
+                readonly ownerId: string;
+                readonly score: string;
+                readonly subscore: string;
+                readonly numSubmits: number;
+                readonly metadata: {
+                    readonly [x: string]: unknown;
+                };
+                readonly updatedAt: number;
+                readonly bucket: string | null;
+            };
+            roomId: unknown;
+            matchId: unknown;
+            tournamentId: unknown;
+            at: number;
+        }[];
+        bucketAssignments: {
+            board: unknown;
+            periodId: unknown;
+            bucket: unknown;
+            group: unknown;
+            assignedAt: number;
+        }[];
+        leagues: {
+            league: unknown;
+            division: unknown;
+            updatedAt: number;
+        }[];
+        leagueMoves: {
+            league: unknown;
+            from: string;
+            to: string;
+            at: number;
+        }[];
+        periodSummaries: {
+            periodId: string;
+            board: string;
+            startsAt: number;
+            endsAt: number;
+            record: RankedLeaderboardRecord;
+        }[];
+        tournamentEntries: {
+            readonly tournament: string;
+            readonly joinedAt: number;
+            readonly attemptsLeft: number;
+        }[];
+        ratings: {
+            pool: unknown;
+            state: unknown;
+            games: unknown;
+            updatedAt: number;
+        }[];
+        ratingResults: {
+            pool: unknown;
+            matchId: {} | null;
+            previous: unknown;
+            current: unknown;
+            at: number;
+        }[];
+        pendingRatingMatches: {
+            pool: unknown;
+            matchId: unknown;
+            weight: number;
+            rank: number | undefined;
+            preparedAt: number;
+        }[];
+    }, LeaderboardError, never>;
+    eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, LeaderboardError, never>;
+};
+
+export declare const defaultLeaderboardBucketAssign: LeaderboardBucketAssign;
+
+export declare const defaultLeaderboardRankQuery: LeaderboardRankQuery;
+
+/** Equal primary score: higher subscore, then earlier submission, then binary owner/record ID. */
+export declare const defaultLeaderboardTiebreak: LeaderboardTiebreak;
+
+export declare const defaultPeriodSummary: (records: ReadonlyArray<RankedLeaderboardRecord>, top?: number) => Readonly<{
+    participants: number;
+    top: readonly RankedLeaderboardRecord[];
+}>;
+
+/** Decay is applied on fresh participated match application, never on a read or
+ * retry. The default preserves the exact prior; no periodic decay job exists. */
+export declare const defaultRatingDecay: RatingDecayPolicy;
+
+export declare const defaultRatingPlacement: RatingPlacementPolicy;
+
+export declare const defaultRatingRate: RatingRateStrategy;
+
+export declare const defineLeaderboard: <S extends Schema.Codec<unknown, unknown>>(input: LeaderboardDefinition<S>) => LeaderboardDescriptor<S>;
+
+export declare const defineLeague: (input: LeagueDefinition) => LeagueDefinition;
+
+/** Declarative entry/attempt budgets only. No price, prize or reward is invented. */
+export declare const defineTournament: (input: TournamentDefinition) => TournamentDescriptor;
+
+declare interface Dispute extends TournamentDisputeIntent {
+    readonly ownerId: string;
+    readonly resolutionId: string | null;
+    readonly winnerId: string | null;
+}
+
+declare interface DoubleEliminationMatch {
+    readonly id: string;
+    readonly stage: 'winners' | 'losers' | 'final' | 'reset';
+    readonly round: number;
+    readonly left: DoubleEliminationSlot;
+    readonly right: DoubleEliminationSlot;
+}
+
+declare interface DoubleEliminationObservation extends Omit<BracketMatchObservation, 'status'> {
+    readonly stage: DoubleEliminationMatch['stage'];
+    readonly status: BracketMatchObservation['status'] | 'empty' | 'inactive';
+    readonly loserId: string | null;
+}
+
+declare interface DoubleEliminationProgress {
+    readonly matches: ReadonlyArray<DoubleEliminationObservation>;
+    readonly champion: string | null;
+    readonly losses: ReadonlyArray<{
+        readonly entrantId: string;
+        readonly losses: number;
+    }>;
+}
+
+declare type DoubleEliminationSlot = BracketSlot | {
+    readonly kind: 'loser';
+    readonly matchId: string;
+};
+
+/** Pairwise mean Elo; each team's delta is split by participation weight. */
+export declare const elo: (options?: EloOptions) => EloRate;
+
+export declare interface EloInput {
+    readonly teams: ReadonlyArray<ReadonlyArray<EloPlayer>>;
+    readonly ranks: ReadonlyArray<number>;
+}
+
+export declare interface EloOptions {
+    readonly k?: number;
+    readonly scale?: number;
+}
+
+export declare interface EloPlayer {
+    readonly id: string;
+    readonly rating: number;
+    readonly weight?: number;
+}
+
+export declare type EloRate = (input: EloInput) => ReadonlyArray<ReadonlyArray<EloResult>>;
+
+export declare interface EloResult {
+    readonly id: string;
+    readonly previous: number;
+    readonly rating: number;
+    readonly delta: number;
+}
+
+/** Glickman's revised Illinois procedure; one complete simultaneous rating period.
+ * https://glicko.net/glicko/glicko2.pdf — independently implemented equations. */
+export declare const glicko2: (options?: Glicko2Options) => Glicko2Rate;
+
+export declare interface Glicko2Input {
+    readonly player: Glicko2Rating;
+    /** All opponents carry their pre-period ratings, not sequentially updated ones. */
+    readonly opponents: ReadonlyArray<Glicko2Opponent>;
+}
+
+export declare interface Glicko2Opponent {
+    readonly rating: number;
+    readonly deviation: number;
+    readonly score: 0 | 0.5 | 1;
+}
+
+export declare interface Glicko2Options {
+    readonly tau?: number;
+    readonly epsilon?: number;
+    readonly maxIterations?: number;
+    readonly maxOpponents?: number;
+}
+
+export declare type Glicko2Rate = (input: Glicko2Input) => Glicko2Result;
+
+export declare interface Glicko2Rating {
+    readonly rating: number;
+    readonly deviation: number;
+    readonly volatility: number;
+}
+
+export declare interface Glicko2Result extends Glicko2Rating {
+    readonly previous: Glicko2Rating;
+}
+
+/** Stable FNV-1a UTF-8 partition helper. Does not enforce fixed-size cohort admission. */
+export declare const hashBucket: (tenantId: string, periodId: string, ownerId: string, bucketCount: number) => number;
+
+/** Internal server service for this leaf plugin's handlers, not a game-stack Port. */
+declare type LeaderboardAdministrationService = Omit<ReturnType<typeof dataStoreLeaderboards>, 'exportSubject' | 'eraseSubject'>;
+
+export declare const leaderboardAround: (records: ReadonlyArray<RankedLeaderboardRecord>, ownerId: string, radius?: number) => ReadonlyArray<RankedLeaderboardRecord>;
+
+/** Choose one actual capacity-admitted candidate. Grouping/SQL writer admission,
+ * membership and capacity stay inside the adapter. */
+export declare type LeaderboardBucketAssign = (context: LeaderboardBucketContext) => string;
+
+export declare interface LeaderboardBucketCandidate {
+    readonly id: string;
+    readonly ordinal: number;
+    readonly entries: number;
+}
+
+export declare interface LeaderboardBucketContext {
+    readonly tenantId: string;
+    readonly board: string;
+    readonly periodId: string;
+    readonly ownerId: string;
+    readonly assign: 'hash' | 'skill' | 'cohort';
+    readonly size: number;
+    readonly group: string | null;
+    readonly candidates: ReadonlyArray<LeaderboardBucketCandidate>;
+}
+
+export declare interface LeaderboardDefinition<S extends Schema.Codec<unknown, unknown>> {
+    readonly name: string;
+    readonly sort?: LeaderboardSort;
+    readonly operator?: ScoreOperator;
+    readonly metadata: S;
+    /** Only service-owned writes exist in this foundation; no client score route. */
+    readonly submit?: {
+        readonly via: 'service-only';
+    };
+    readonly reset?: {
+        readonly cron: string;
+        readonly timezone: string;
+        readonly keepHistory: number;
+    } | undefined;
+    readonly maxRankRecords?: number;
+    readonly maxPageSize?: number;
+    readonly buckets?: {
+        readonly size: number;
+        readonly assign: 'hash' | 'skill' | 'cohort';
+        readonly skillWidth?: number;
+    } | undefined;
+}
+
+export declare interface LeaderboardDescriptor<S extends Schema.Codec<unknown, unknown>> {
+    readonly kind: 'leaderboard';
+    readonly name: string;
+    readonly sort: LeaderboardSort;
+    readonly operator: ScoreOperator;
+    readonly metadata: S;
+    readonly submit: {
+        readonly via: 'service-only';
+    };
+    readonly reset: LeaderboardDefinition<S>['reset'];
+    readonly maxRankRecords: number;
+    readonly maxPageSize: number;
+    readonly buckets: LeaderboardDefinition<S>['buckets'];
+}
+
+export declare class LeaderboardError extends LeaderboardError_base {
+}
+
+declare const LeaderboardError_base: Schema.Class<LeaderboardError, Schema.TaggedStruct<"LeaderboardError", {
+    readonly code: Schema.Literals<readonly ["invalid_board", "invalid_score", "invalid_record", "invalid_input", "overflow", "unavailable", "forbidden", "not_found", "conflict", "erased", "limit_exceeded"]>;
+}>, YieldableError>;
+
+declare interface LeaderboardPeriodSummary {
+    readonly participants: number;
+    readonly top: ReadonlyArray<RankedLeaderboardRecord>;
+}
+
+/** A summary selector may only retain exact records from the captured snapshot. */
+declare type LeaderboardPeriodSummarySlot = (records: ReadonlyArray<RankedLeaderboardRecord>) => LeaderboardPeriodSummary;
+
+/** Complete ordered record identities. The adapter supplies consecutive ordinal
+ * ranks and all values from its SQL snapshot, never from strategy output. */
+export declare type LeaderboardRankQuery = (context: LeaderboardRankQueryContext) => Effect.Effect<ReadonlyArray<string>, LeaderboardError>;
+
+/** The admitted complete SQL snapshot is detached from the storage rows. A
+ * dialect implementation may use the declared read capability; writes are not
+ * part of this strategy's contract. Every returned ID must belong to records. */
+export declare interface LeaderboardRankQueryContext {
+    readonly tenantId: string;
+    readonly board: string;
+    readonly periodId: string;
+    /** null is the global view; a value is the admitted owner's current cohort. */
+    readonly bucketId: string | null;
+    readonly sort: LeaderboardSort;
+    readonly maxRecords: number;
+    readonly records: ReadonlyArray<LeaderboardRankRecord>;
+    readonly tiebreak: LeaderboardTiebreak;
+    readonly query: DataStore['query'];
+}
+
+export declare interface LeaderboardRankRecord {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly board: string;
+    readonly periodId: string;
+    readonly ownerId: string;
+    readonly score: string;
+    readonly subscore: string;
+    readonly updatedAt: number;
+}
+
+declare type LeaderboardRecord = typeof LeaderboardRecordSchema.Type;
+
+declare const LeaderboardRecordSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly board: Schema.String;
+    readonly periodId: Schema.String;
+    readonly ownerId: Schema.String;
+    readonly score: Schema.String;
+    readonly subscore: Schema.String;
+    readonly numSubmits: Schema.Number;
+    readonly metadata: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly updatedAt: Schema.Number;
+    readonly bucket: Schema.NullOr<Schema.String>;
+}>;
+
+export declare type LeaderboardSort = 'asc' | 'desc';
+
+export declare interface LeaderboardsPlugin extends VoltroPlugin {
+    /** Trusted server facade of the same installed internal service; no browser authority. */
+    readonly leaderboards: {
+        readonly service: () => LeaderboardAdministrationService;
+        readonly brackets: () => BracketAdmissionService;
+        readonly tournaments: () => TournamentBracketService;
+        readonly tournamentStages: () => TournamentStageService;
+    };
+}
+
+export declare const leaderboardsPlugin: (input: LeaderboardsPluginOptions) => LeaderboardsPlugin;
+
+export declare interface LeaderboardsPluginOptions extends LeaderboardStoreOptions {
+    readonly brackets?: BracketAdmissionBinding;
+    readonly tournamentCoordination?: TournamentBinding;
+}
+
+/** System21 manifest: strategy slots, ports and events this system declares. */
+export declare const leaderboardsSystemContract: Readonly<{
+    slots: {
+        tiebreak: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+        rankQuery: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+        bucketAssign: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+        periodSummary: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+        validate: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+        ratingRate: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+        ratingPlacement: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+        ratingDecay: {
+            defaultExport: string;
+            fixtureExport: string;
+        };
+    };
+    ports: {
+        bracketAdmission: {
+            tagExport: string;
+            fakeLayerExport: string;
+            fixtureExport: string;
+        };
+        tournamentBracket: {
+            tagExport: string;
+            fakeLayerExport: string;
+            fixtureExport: string;
+        };
+        tournamentStage: {
+            tagExport: string;
+            fakeLayerExport: string;
+            fixtureExport: string;
+        };
+    };
+    events: readonly string[];
+}>;
+
+export declare interface LeaderboardStoreOptions {
+    readonly boards: ReadonlyArray<LeaderboardDescriptor<Schema.Codec<unknown, unknown>>>;
+    readonly tournaments?: ReadonlyArray<TournamentDescriptor>;
+    /** Leagues over declared, non-bucketed boards (`defineLeague`); a board belongs to at most one league. */
+    readonly leagues?: ReadonlyArray<LeagueDefinition>;
+    readonly ratingPools?: ReadonlyArray<RatingPoolDefinition>;
+    readonly ratingStrategies?: RatingStrategies;
+    /** Explicit verified service callers; none are authorized by default. System tasks are trusted. */
+    readonly allowedServices?: ReadonlyArray<string>;
+    readonly validate?: (input: SubmitLeaderboardInput, previous: LeaderboardRecord | null, tx: DataStore) => Effect.Effect<void, LeaderboardError>;
+    readonly tiebreak?: LeaderboardTiebreak;
+    readonly rankQuery?: LeaderboardRankQuery;
+    readonly bucketAssign?: LeaderboardBucketAssign;
+    readonly bucketStrategyVersion?: string;
+    readonly periodSummary?: LeaderboardPeriodSummarySlot;
+    readonly maxPeriodRows?: number;
+    readonly maxSummaryBytes?: number;
+    readonly maxMetadataBytes?: number;
+    readonly maxExportRows?: number;
+    readonly maxSubmissionsPerOwner?: number;
+    readonly now?: () => number;
+}
+
+export declare type LeaderboardTiebreak = (left: LeaderboardRankRecord, right: LeaderboardRankRecord) => number;
+
+/** A league: ordered division boards (best first) whose periods close together; at each
+ * close the best `promote` of a division move up and the worst `relegate` move down. */
+export declare interface LeagueDefinition {
+    readonly name: string;
+    /** Board names, top division first; each a declared, non-bucketed board of this plugin. */
+    readonly divisions: readonly [string, string, ...string[]];
+    readonly promote: number;
+    readonly relegate: number;
+}
+
+export declare interface LeagueMovement {
+    readonly ownerId: string;
+    readonly from: string;
+    readonly to: string;
+}
+
+/** Moves for one close, from each division's standings (best first). The top division
+ * promotes nobody, the bottom one relegates nobody; a player is never moved twice. */
+export declare const leagueMovements: (league: LeagueDefinition, standings: ReadonlyArray<{
+    readonly division: string;
+    readonly owners: ReadonlyArray<string>;
+}>) => ReadonlyArray<LeagueMovement>;
+
+/** Weng–Lin Plackett–Luce, Algorithm4 (2011), with linear Gaussian partial play.
+ * https://jmlr.org/papers/volume12/weng11a/weng11a.pdf
+ * Fractional weights enter the team mean linearly and variance quadratically;
+ * they are not the OpenSkill library's contribution/weight-normalization API. */
+export declare const openskill: (options?: OpenSkillOptions) => OpenSkillRate;
+
+export declare interface OpenSkillInput {
+    readonly teams: ReadonlyArray<ReadonlyArray<OpenSkillPlayer>>;
+    readonly ranks: ReadonlyArray<number>;
+}
+
+export declare interface OpenSkillOptions {
+    readonly beta?: number;
+    readonly tau?: number;
+    readonly kappa?: number;
+    readonly ordinalZ?: number;
+}
+
+export declare interface OpenSkillPlayer {
+    readonly id: string;
+    readonly mu: number;
+    readonly sigma: number;
+    /** Fraction of participation. Zero retains the exact prior. */
+    readonly weight?: number;
+}
+
+export declare type OpenSkillRate = (input: OpenSkillInput) => ReadonlyArray<ReadonlyArray<OpenSkillResult>>;
+
+export declare interface OpenSkillResult {
+    readonly id: string;
+    readonly previous: {
+        readonly mu: number;
+        readonly sigma: number;
+    };
+    readonly mu: number;
+    readonly sigma: number;
+    readonly ordinal: number;
+}
+
+export declare type PrepareRatingMatchInput = typeof PrepareRatingMatchSchema.Type;
+
+declare const PrepareRatingMatchSchema: Schema.Struct<{
+    readonly tenantId: Schema.NonEmptyString;
+    readonly pool: Schema.NonEmptyString;
+    readonly matchId: Schema.NonEmptyString;
+    readonly teams: Schema.$Array<Schema.$Array<Schema.Struct<{
+        readonly ownerId: Schema.NonEmptyString;
+        readonly weight: Schema.optional<Schema.Number>;
+    }>>>;
+    readonly ranks: Schema.$Array<Schema.Number>;
+}>;
+
+declare interface Provision extends TournamentRoomWork {
+    readonly roomId: string | null;
+    readonly epoch: number | null;
+}
+
+export declare interface RankedLeaderboardRecord extends LeaderboardRankRecord {
+    readonly rank: number;
+}
+
+/** Whole supplied board/period snapshot. No SQL/window-query or million-row capacity claim. */
+export declare const rankLeaderboardRecords: (input: ReadonlyArray<LeaderboardRankRecord>, options?: RankOptions) => ReadonlyArray<RankedLeaderboardRecord>;
+
+export declare interface RankOptions {
+    readonly sort?: LeaderboardSort;
+    readonly tiebreak?: LeaderboardTiebreak;
+    readonly maxRecords?: number;
+}
+
+export declare interface RatingDecayContext extends RatingPlacementContext {
+    readonly state: RatingState;
+    readonly games: number;
+    readonly updatedAt: number;
+    readonly elapsedMs: number;
+}
+
+export declare type RatingDecayPolicy = (context: RatingDecayContext) => RatingState;
+
+export declare interface RatingMatchReceipt {
+    readonly pool: string;
+    readonly matchId: string;
+    readonly participants: number;
+    readonly state: 'prepared' | 'applied';
+    readonly preparedAt: number;
+    readonly appliedAt: number | null;
+}
+
+export declare interface RatingPlacementContext {
+    readonly tenantId: string;
+    readonly ownerId: string;
+    readonly pool: ResolvedRatingPool;
+    readonly at: number;
+}
+
+export declare type RatingPlacementPolicy = (context: RatingPlacementContext) => RatingState;
+
+export declare type RatingPoolDefinition = {
+    readonly name: string;
+    readonly algorithm: 'elo';
+    readonly initial?: {
+        readonly rating: number;
+    };
+    readonly options?: EloOptions;
+} | {
+    readonly name: string;
+    readonly algorithm: 'openskill';
+    readonly initial?: {
+        readonly mu: number;
+        readonly sigma: number;
+    };
+    readonly options?: OpenSkillOptions;
+} | {
+    readonly name: string;
+    readonly algorithm: 'glicko2';
+    readonly initial?: {
+        readonly rating: number;
+        readonly deviation: number;
+        readonly volatility: number;
+    };
+    readonly options?: Glicko2Options;
+};
+
+export declare interface RatingRateContext {
+    readonly tenantId: string;
+    readonly matchId: string;
+    readonly pool: ResolvedRatingPool;
+    readonly at: number;
+    readonly teams: ReadonlyArray<ReadonlyArray<RatingStrategyPlayer>>;
+    readonly ranks: ReadonlyArray<number>;
+}
+
+export declare type RatingRateStrategy = (context: RatingRateContext) => ReadonlyArray<RatingStrategyResult>;
+
+export declare type RatingState = typeof RatingStateSchema.Type;
+
+declare const RatingStateSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly algorithm: Schema.Literal<"elo">;
+    readonly rating: Schema.Number;
+}>, Schema.Struct<{
+    readonly algorithm: Schema.Literal<"openskill">;
+    readonly mu: Schema.Number;
+    readonly sigma: Schema.Number;
+}>, Schema.Struct<{
+    readonly algorithm: Schema.Literal<"glicko2">;
+    readonly rating: Schema.Number;
+    readonly deviation: Schema.Number;
+    readonly volatility: Schema.Number;
+}>]>;
+
+export declare interface RatingStrategies {
+    /** Required for any custom callback. Change it whenever rule meaning changes;
+     * the SQL pool configuration refuses conflicting versions across writers. */
+    readonly version?: string;
+    readonly rate?: RatingRateStrategy;
+    readonly placementPolicy?: RatingPlacementPolicy;
+    readonly decay?: RatingDecayPolicy;
+}
+
+export declare interface RatingStrategyPlayer {
+    readonly ownerId: string;
+    readonly state: RatingState;
+    readonly games: number;
+    readonly updatedAt: number | null;
+    readonly weight: number;
+}
+
+export declare interface RatingStrategyResult {
+    readonly ownerId: string;
+    readonly state: RatingState;
+}
+
+export declare interface ResolvedRatingPool {
+    readonly name: string;
+    readonly algorithm: RatingState['algorithm'];
+    readonly initial: RatingState;
+    readonly options: EloOptions | OpenSkillOptions | Glicko2Options;
+}
+
+declare interface Result extends TournamentResultReport {
+    readonly reportedWinnerId: string;
+}
+
+declare interface RollLeaderboardPeriodInput {
+    readonly tenantId: string;
+    readonly board: string;
+    readonly requestId: string;
+    readonly expectedPeriodId: string;
+    /** Stable intended boundary, retained on retry; never supplied by a player. */
+    readonly closedAt: number;
+}
+
+declare interface RollLeaderboardPeriodResult {
+    readonly closedPeriodId: string;
+    readonly activePeriodId: string;
+    readonly closedAt: number;
+    readonly summary: LeaderboardPeriodSummary;
+}
+
+export declare type ScoreOperator = 'best' | 'set' | 'increment' | 'decrement';
+
+export declare const scoreString: (input: string | bigint | number) => string;
+
+/** SQL signed BIGINT range; wire values use canonical decimal strings. */
+export declare const scoreValue: (input: string | bigint | number) => bigint;
+
+/** Trusted service submission, never a player score-intent payload. */
+declare interface SubmitLeaderboardInput {
+    readonly tenantId: string;
+    readonly board: string;
+    readonly ownerId: string;
+    readonly submissionId: string;
+    readonly score: string;
+    readonly subscore?: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly roomId?: string;
+    readonly matchId?: string;
+    readonly tournamentId?: string;
+    readonly bucketSkill?: number;
+    readonly bucketCohort?: string;
+}
+
+declare type TournamentBinding = ({
+    readonly backend: 'sql';
+    readonly options: TournamentBracketOptions;
+} | {
+    readonly backend: 'custom';
+    readonly version: string;
+    readonly service: TournamentBracketService;
+    readonly sources: ReadonlyArray<string>;
+}) & {
+    readonly stage?: TournamentStageBinding;
+    readonly workflowSources?: string;
+};
+
+declare interface TournamentBracketDefinition {
+    readonly format: TournamentBracketFormat;
+    readonly entrants: ReadonlyArray<TournamentEntrant>;
+    /** Swiss only: rounds to play (default: enough to separate a winner, ceil(log2 entrants)). */
+    readonly rounds?: number | undefined;
+    /** Immutable application prize/Room/no-show policy identity, not a price. */
+    readonly ruleVersion: string;
+}
+
+declare interface TournamentBracketExport {
+    readonly tournamentId: string;
+    readonly phase: BracketState['phase'];
+    readonly seed: number;
+    readonly matches: ReadonlyArray<{
+        readonly matchId: string;
+        readonly roomId: string;
+        readonly won: boolean;
+    }>;
+    readonly disputes: ReadonlyArray<TournamentDisputeIntent & {
+        readonly resolutionId: string | null;
+    }>;
+}
+
+declare type TournamentBracketFormat = 'single-elimination' | 'double-elimination' | 'round-robin' | 'swiss';
+
+/** A bracket match with the Room it plays in, once one was provisioned. */
+declare type TournamentBracketMatch = (BracketProgress['matches'][number] | DoubleEliminationProgress['matches'][number]) & {
+    readonly roomId: string | null;
+};
+
+declare interface TournamentBracketOptions {
+    readonly epochNow: () => number;
+    readonly maxTenantTournaments?: number;
+    authorize(subject: Subject, scope: BracketAdmissionScope, operation: 'create' | 'report' | 'dispute' | 'resolve' | 'advance' | 'status'): Effect.Effect<void, LeaderboardError>;
+    /** Actual durable Room creation/reservations: same request returns same Room,
+     * enforces private roster/options/current grants, and awaits accepted work. */
+    provisionRoom(work: TournamentRoomWork): Effect.Effect<TournamentRoomReceipt, LeaderboardError>;
+    verifyResult(subject: Subject, scope: BracketAdmissionScope, report: TournamentResultReport): Effect.Effect<void, LeaderboardError>;
+    /** The real economy/inventory/Inbox participant owns atomic idempotency. */
+    settleChampion(work: BracketAdmissionScope & {
+        readonly requestId: string;
+        readonly winnerId: string;
+        readonly ruleVersion: string;
+    }): Effect.Effect<void, LeaderboardError>;
+    withdrawSubject(request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+    /** Must withdraw pending request identities too, even with lost Room replies. */
+    withdrawTournament(scope: BracketAdmissionScope, request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+    authorizeExport(request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+}
+
+/** Trusted server coordinator contract; SQL types are erased imports only. */
+declare class TournamentBracketPort extends TournamentBracketPort_base {
+}
+
+declare const TournamentBracketPort_base: Context.ServiceClass<TournamentBracketPort, "@voltro/TournamentBracketPort", {
+    create(subject: Subject, scope: BracketAdmissionScope, definition: TournamentBracketDefinition): Effect.Effect<TournamentBracketStatus, LeaderboardError>;
+    report(subject: Subject, scope: BracketAdmissionScope, report: TournamentResultReport): Effect.Effect<TournamentBracketStatus, LeaderboardError>;
+    dispute(subject: Subject, scope: BracketAdmissionScope, intent: TournamentDisputeIntent): Effect.Effect<TournamentBracketStatus, LeaderboardError>;
+    resolve(subject: Subject, scope: BracketAdmissionScope, intent: TournamentDisputeResolution): Effect.Effect<TournamentBracketStatus, LeaderboardError>;
+    advance(subject: Subject, scope: BracketAdmissionScope): Effect.Effect<TournamentBracketStatus, LeaderboardError>;
+    status(subject: Subject, scope: BracketAdmissionScope): Effect.Effect<TournamentBracketStatus, LeaderboardError>;
+    exportSubject(request: PluginPrivacyRequest): Effect.Effect<ReadonlyArray<TournamentBracketExport>, LeaderboardError>;
+    eraseSubject(request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+}>;
+
+declare type TournamentBracketService = Context.Service.Shape<typeof TournamentBracketPort>;
+
+declare interface TournamentBracketStatus {
+    readonly phase: BracketState['phase'];
+    readonly format: TournamentBracketFormat;
+    readonly champion: string | null;
+    readonly matches: ReadonlyArray<TournamentBracketMatch>;
+    readonly unresolvedDisputes: number;
+}
+
+export declare interface TournamentDefinition {
+    readonly name: string;
+    readonly board: string;
+    readonly startsAt: number;
+    readonly endsAt: number;
+    readonly maxEntries: number;
+    readonly joinRequired?: boolean;
+    readonly attemptsPerEntry?: number;
+}
+
+export declare interface TournamentDescriptor extends Omit<TournamentDefinition, 'joinRequired' | 'attemptsPerEntry'> {
+    readonly kind: 'tournament';
+    readonly format: 'time-window';
+    readonly joinRequired: boolean;
+    readonly attemptsPerEntry: number;
+}
+
+declare interface TournamentDisputeIntent {
+    readonly disputeId: string;
+    readonly matchId: string;
+    readonly reason: 'result_mismatch' | 'no_show' | 'connection';
+}
+
+declare interface TournamentDisputeResolution {
+    readonly disputeId: string;
+    readonly resolutionId: string;
+    readonly winnerId: string;
+}
+
+declare interface TournamentEntrant {
+    readonly entrantId: string;
+    readonly seed: number;
+}
+
+declare interface TournamentResultReport extends TournamentRoomReceipt {
+    readonly matchId: string;
+    readonly reportId: string;
+    readonly winnerId: string;
+}
+
+declare interface TournamentRoomReceipt {
+    readonly roomId: string;
+    readonly epoch: number;
+}
+
+declare interface TournamentRoomWork extends BracketAdmissionScope {
+    readonly matchId: string;
+    readonly requestId: string;
+    readonly left: string;
+    readonly right: string;
+    readonly ruleVersion: string;
+}
+
+declare type TournamentStageBinding = ({
+    readonly backend: 'sql';
+    readonly options: Omit<TournamentStageOptions, 'admissions' | 'brackets'>;
+} | {
+    readonly backend: 'custom';
+    readonly version: string;
+    readonly service: TournamentStageService;
+}) & {
+    readonly privacy: TournamentStagePrivacy;
+};
+
+declare interface TournamentStageOptions {
+    readonly epochNow: () => number;
+    readonly admissions: Pick<BracketAdmissionService, 'seal'>;
+    readonly brackets: Pick<TournamentBracketService, 'create'>;
+    authorize(subject: Subject, scope: BracketAdmissionScope, operation: 'window' | 'notify' | 'seed'): Effect.Effect<void, LeaderboardError>;
+    /** Current SQL/rating/no-show preparation participant. Same request must
+     * recover the same durable seed decision, never reread a changed prior. */
+    seedRoster(work: TournamentStagePayload & BracketAdmissionRoster & {
+        readonly requestId: string;
+    }): Effect.Effect<ReadonlyArray<TournamentEntrant>, LeaderboardError>;
+    /** Actual Inbox/Push idempotency and external withdrawal remain required. */
+    notifyEntrants(work: TournamentStagePayload & {
+        readonly phase: 'registration' | 'check-in';
+        readonly requestId: string;
+    }): Effect.Effect<void, LeaderboardError>;
+}
+
+declare const TournamentStagePayload: Schema.Struct<{
+    readonly format: Schema.Literals<readonly ["single-elimination", "double-elimination", "round-robin", "swiss"]>;
+    readonly ruleVersion: Schema.String;
+    readonly tenantId: Schema.String;
+    readonly tournamentId: Schema.String;
+    readonly runKey: Schema.String;
+}>;
+
+declare type TournamentStagePayload = typeof TournamentStagePayload.Type;
+
+declare class TournamentStagePort extends TournamentStagePort_base {
+}
+
+declare const TournamentStagePort_base: Context.ServiceClass<TournamentStagePort, "@voltro/TournamentStagePort", {
+    window(subject: Subject, payload: TournamentStagePayload): Effect.Effect<BracketAdmissionDefinition, LeaderboardError>;
+    notify(subject: Subject, payload: TournamentStagePayload, phase: "registration" | "check-in"): Effect.Effect<{
+        readonly notified: boolean;
+    }, LeaderboardError>;
+    seed(subject: Subject, payload: TournamentStagePayload): Effect.Effect<TournamentWorkflowSummary, LeaderboardError>;
+}>;
+
+declare interface TournamentStagePrivacy {
+    /** Own subject data from actual seed/notification participants, no peer export. */
+    exportSubject(request: PluginPrivacyRequest): Effect.Effect<unknown, LeaderboardError>;
+    /** Permanently withdraw accepted seed/reminder work before subject cleanup. */
+    eraseSubject(request: PluginPrivacyRequest): Effect.Effect<void, LeaderboardError>;
+}
+
+declare type TournamentStageService = Context.Service.Shape<typeof TournamentStagePort>;
+
+/** Counts only: no roster/winner/ratings/Room credentials in workflow journals. */
+declare const TournamentWorkflowSummary: Schema.Struct<{
+    readonly phase: Schema.Literals<readonly ["active", "paused", "complete", "erasing", "cancelled"]>;
+    readonly ready: Schema.Int;
+    readonly completed: Schema.Int;
+    /** Advance work still open: ready matches without a Room, plus the champion's settlement. */
+    readonly waiting: Schema.Int;
+    readonly unresolvedDisputes: Schema.Int;
+}>;
+
+declare type TournamentWorkflowSummary = typeof TournamentWorkflowSummary.Type;
+
+export { }