@voltro/plugin-leaderboards 0.0.0-stage → 0.88.0

package/dist/testing.d.ts

@@ -0,0 +1,872 @@
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { PluginPrivacyRequest } from '@voltro/protocol';
+import { Schema } from 'effect';
+import { Subject } 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;
+}
+
+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'];
+}
+
+export declare const bracketAdmissionFakeLayer: (overrides?: Partial<BracketAdmissionService>) => Layer.Layer<BracketAdmissionPort>;
+
+/** Browser-safe Tag; consumers depend on admission, never a SQL adapter. */
+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>;
+}>;
+
+export declare const bracketAdmissionPortFixture: () => {
+    kind: "port";
+    tag: typeof BracketAdmissionPort;
+    fakeLayer: Layer.Layer<BracketAdmissionPort, never, never>;
+    probe: {
+        run: () => Promise<"invalid_board" | "invalid_score" | "invalid_record" | "invalid_input" | "overflow" | "unavailable" | "forbidden" | "not_found" | "conflict" | "erased" | "limit_exceeded" | "unexpected-success">;
+        expected: string;
+    };
+};
+
+export declare const bracketAdmissionPortSystemFixture: Readonly<{
+    kind: "port";
+    tag: typeof BracketAdmissionPort;
+    fakeLayer: Layer.Layer<BracketAdmissionPort, never, never>;
+    probe: {
+        run: () => Effect.Effect<string, never, never>;
+        expected: string;
+    };
+}>;
+
+declare interface BracketAdmissionRoster {
+    readonly checkedIn: ReadonlyArray<string>;
+    readonly noShows: ReadonlyArray<string>;
+}
+
+declare interface BracketAdmissionScope {
+    readonly tenantId: string;
+    readonly tournamentId: string;
+}
+
+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;
+}
+
+export declare const bracketAdmissionSystemFakeLayer: Layer.Layer<BracketAdmissionPort, never, never>;
+
+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 interface BracketResult {
+    readonly matchId: string;
+    readonly winnerId: string;
+}
+
+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;
+}
+
+export declare const bucketAssignSystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: LeaderboardBucketAssign;
+    defaultProbe: {
+        run: () => Effect.Effect<string, never, never>;
+        expected: string;
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<string, never, never>;
+        expected: string;
+    };
+}>;
+
+declare const defaultLeaderboardBucketAssign: LeaderboardBucketAssign;
+
+declare const defaultLeaderboardRankQuery: LeaderboardRankQuery;
+
+/** 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. */
+declare const defaultRatingDecay: RatingDecayPolicy;
+
+declare const defaultRatingPlacement: RatingPlacementPolicy;
+
+declare const defaultRatingRate: RatingRateStrategy;
+
+declare interface Dispute extends TournamentDisputeIntent {
+    readonly ownerId: string;
+    readonly resolutionId: string | null;
+    readonly winnerId: string | null;
+}
+
+declare interface DoubleEliminationBracket {
+    readonly format: 'double-elimination';
+    readonly version: 1;
+    readonly entrants: ReadonlyArray<TournamentEntrant>;
+    readonly matches: ReadonlyArray<DoubleEliminationMatch>;
+}
+
+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;
+};
+
+export declare const eloFixture: () => {
+    rate: EloRate;
+    input: {
+        teams: {
+            id: string;
+            rating: number;
+        }[][];
+        ranks: number[];
+    };
+};
+
+declare interface EloInput {
+    readonly teams: ReadonlyArray<ReadonlyArray<EloPlayer>>;
+    readonly ranks: ReadonlyArray<number>;
+}
+
+declare interface EloOptions {
+    readonly k?: number;
+    readonly scale?: number;
+}
+
+declare interface EloPlayer {
+    readonly id: string;
+    readonly rating: number;
+    readonly weight?: number;
+}
+
+declare type EloRate = (input: EloInput) => ReadonlyArray<ReadonlyArray<EloResult>>;
+
+declare interface EloResult {
+    readonly id: string;
+    readonly previous: number;
+    readonly rating: number;
+    readonly delta: number;
+}
+
+/** Explicit replacements may override methods; every omitted method refuses. */
+export declare const fakeBracketAdmissionService: (overrides?: Partial<BracketAdmissionService>) => BracketAdmissionService;
+
+export declare const fakeTournamentBracketService: (overrides?: Partial<TournamentBracketService>) => TournamentBracketService;
+
+export declare const fakeTournamentStageService: (overrides?: Partial<TournamentStageService>) => TournamentStageService;
+
+declare interface Glicko2Options {
+    readonly tau?: number;
+    readonly epsilon?: number;
+    readonly maxIterations?: number;
+    readonly maxOpponents?: number;
+}
+
+/** Choose one actual capacity-admitted candidate. Grouping/SQL writer admission,
+ * membership and capacity stay inside the adapter. */
+declare type LeaderboardBucketAssign = (context: LeaderboardBucketContext) => string;
+
+export declare const leaderboardBucketAssignFixture: () => {
+    readonly bucketAssign: typeof defaultLeaderboardBucketAssign;
+    readonly context: LeaderboardBucketContext;
+};
+
+declare interface LeaderboardBucketCandidate {
+    readonly id: string;
+    readonly ordinal: number;
+    readonly entries: number;
+}
+
+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>;
+}
+
+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>;
+
+/** Actual pure implementations; not a whole-system conformance fixture. */
+export declare const leaderboardPureFixture: {
+    record: (ownerId?: string) => LeaderboardRankRecord;
+    applyScore: (previous: string | bigint | number | null, submitted: string | bigint | number, operator: ScoreOperator, sort?: LeaderboardSort) => string;
+    tiebreak: LeaderboardTiebreak;
+    periodSummary: (records: ReadonlyArray< RankedLeaderboardRecord>, top?: number) => Readonly<{
+        participants: number;
+        top: readonly RankedLeaderboardRecord[];
+    }>;
+    hashBucket: (tenantId: string, periodId: string, ownerId: string, bucketCount: number) => number;
+};
+
+/** Complete ordered record identities. The adapter supplies consecutive ordinal
+ * ranks and all values from its SQL snapshot, never from strategy output. */
+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. */
+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'];
+}
+
+/** Supply the real store's read capability when a dialect slot needs SQL. The
+ * default itself remains a pure Effect over the captured fixture records. */
+export declare const leaderboardRankQueryFixture: (query: DataStore["query"]) => {
+    readonly rankQuery: typeof defaultLeaderboardRankQuery;
+    readonly context: LeaderboardRankQueryContext;
+};
+
+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;
+
+export declare const leaderboardRecordFixture: (ownerId?: string) => LeaderboardRankRecord;
+
+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>;
+}>;
+
+declare type LeaderboardSort = 'asc' | 'desc';
+
+declare type LeaderboardTiebreak = (left: LeaderboardRankRecord, right: LeaderboardRankRecord) => number;
+
+declare interface OpenSkillOptions {
+    readonly beta?: number;
+    readonly tau?: number;
+    readonly kappa?: number;
+    readonly ordinalZ?: number;
+}
+
+export declare const periodSummarySystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: (records: ReadonlyArray< RankedLeaderboardRecord>, top?: number) => Readonly<{
+        participants: number;
+        top: readonly RankedLeaderboardRecord[];
+    }>;
+    defaultProbe: {
+        run: () => Effect.Effect<number, never, never>;
+        expected: number;
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<number, never, never>;
+        expected: number;
+    };
+}>;
+
+declare interface Provision extends TournamentRoomWork {
+    readonly roomId: string | null;
+    readonly epoch: number | null;
+}
+
+declare interface RankedLeaderboardRecord extends LeaderboardRankRecord {
+    readonly rank: number;
+}
+
+export declare const rankQuerySystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: LeaderboardRankQuery;
+    defaultProbe: {
+        run: () => Effect.Effect<readonly string[], LeaderboardError, never>;
+        expected: string[];
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<string[], never, never>;
+        expected: string[];
+    };
+}>;
+
+declare interface RatingDecayContext extends RatingPlacementContext {
+    readonly state: RatingState;
+    readonly games: number;
+    readonly updatedAt: number;
+    readonly elapsedMs: number;
+}
+
+declare type RatingDecayPolicy = (context: RatingDecayContext) => RatingState;
+
+export declare const ratingDecaySystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: RatingDecayPolicy;
+    defaultProbe: {
+        run: () => Effect.Effect<{
+            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;
+        }, never, never>;
+        expected: {
+            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;
+        };
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<{
+            decayed: boolean;
+        }, never, never>;
+        expected: {
+            decayed: boolean;
+        };
+    };
+}>;
+
+declare interface RatingPlacementContext {
+    readonly tenantId: string;
+    readonly ownerId: string;
+    readonly pool: ResolvedRatingPool;
+    readonly at: number;
+}
+
+declare type RatingPlacementPolicy = (context: RatingPlacementContext) => RatingState;
+
+export declare const ratingPlacementSystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: RatingPlacementPolicy;
+    defaultProbe: {
+        run: () => Effect.Effect<{
+            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;
+        }, never, never>;
+        expected: {
+            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;
+        };
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<{
+            placed: boolean;
+        }, never, never>;
+        expected: {
+            placed: boolean;
+        };
+    };
+}>;
+
+declare interface RatingRateContext {
+    readonly tenantId: string;
+    readonly matchId: string;
+    readonly pool: ResolvedRatingPool;
+    readonly at: number;
+    readonly teams: ReadonlyArray<ReadonlyArray<RatingStrategyPlayer>>;
+    readonly ranks: ReadonlyArray<number>;
+}
+
+declare type RatingRateStrategy = (context: RatingRateContext) => ReadonlyArray<RatingStrategyResult>;
+
+export declare const ratingRateSystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: RatingRateStrategy;
+    defaultProbe: {
+        run: () => Effect.Effect<string[], never, never>;
+        expected: string[];
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<string[], never, never>;
+        expected: string[];
+    };
+}>;
+
+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 const ratingStrategiesFixture: () => {
+    readonly rate: typeof defaultRatingRate;
+    readonly placementPolicy: typeof defaultRatingPlacement;
+    readonly decay: typeof defaultRatingDecay;
+    readonly context: RatingRateContext;
+};
+
+declare interface RatingStrategyPlayer {
+    readonly ownerId: string;
+    readonly state: RatingState;
+    readonly games: number;
+    readonly updatedAt: number | null;
+    readonly weight: number;
+}
+
+declare interface RatingStrategyResult {
+    readonly ownerId: string;
+    readonly state: RatingState;
+}
+
+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 RoundRobinRound {
+    readonly round: number;
+    readonly pairs: ReadonlyArray<TournamentPair>;
+    readonly bye: string | null;
+}
+
+declare type ScoreOperator = 'best' | 'set' | 'increment' | 'decrement';
+
+declare interface SingleEliminationBracket {
+    readonly format: 'single-elimination';
+    readonly version: 1;
+    readonly entrants: ReadonlyArray<TournamentEntrant>;
+    readonly matches: ReadonlyArray<SingleEliminationMatch>;
+}
+
+declare interface SingleEliminationMatch {
+    readonly id: string;
+    readonly round: number;
+    readonly left: BracketSlot;
+    readonly right: BracketSlot;
+}
+
+/** 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 interface SwissPairing {
+    readonly pairs: ReadonlyArray<TournamentPair>;
+    readonly bye: string | null;
+    readonly searchNodes: number;
+}
+
+declare interface SwissStanding extends TournamentEntrant {
+    /** Whole scoring units selected by the studio (for example win2/draw1). */
+    readonly points: number;
+    readonly byes: number;
+    readonly opponents: ReadonlyArray<string>;
+}
+
+export declare const tiebreakSystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: LeaderboardTiebreak;
+    defaultProbe: {
+        run: () => Effect.Effect<string[], never, never>;
+        expected: string[];
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<string[], never, never>;
+        expected: 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;
+    }>;
+}
+
+export declare const tournamentBracketFakeLayer: (overrides?: Partial<TournamentBracketService>) => Layer.Layer<TournamentBracketPort>;
+
+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;
+};
+
+/** 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>;
+}>;
+
+export declare const tournamentBracketPortFixture: () => {
+    kind: "port";
+    tag: typeof TournamentBracketPort;
+    fakeLayer: Layer.Layer<TournamentBracketPort, never, never>;
+    probe: {
+        run: () => Promise<"invalid_board" | "invalid_score" | "invalid_record" | "invalid_input" | "overflow" | "unavailable" | "forbidden" | "not_found" | "conflict" | "erased" | "limit_exceeded" | "unexpected-success">;
+        expected: string;
+    };
+};
+
+export declare const tournamentBracketPortSystemFixture: Readonly<{
+    kind: "port";
+    tag: typeof TournamentBracketPort;
+    fakeLayer: Layer.Layer<TournamentBracketPort, never, never>;
+    probe: {
+        run: () => Effect.Effect<string, never, never>;
+        expected: string;
+    };
+}>;
+
+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 const tournamentBracketSystemFakeLayer: Layer.Layer<TournamentBracketPort, never, never>;
+
+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 TournamentPair {
+    readonly left: string;
+    readonly right: string;
+}
+
+/** Actual pairing primitives, with no simulated SQL, Room or prize outcome. */
+export declare const tournamentPairingFixture: () => Readonly<{
+    entrants: readonly Readonly<{
+        entrantId: `p${number}`;
+        seed: number;
+    }>[];
+    standings: readonly Readonly<{
+        points: 0;
+        byes: 0;
+        opponents: readonly string[];
+        entrantId: `p${number}`;
+        seed: number;
+    }>[];
+    roundRobin: (input: ReadonlyArray< TournamentEntrant>, options?: {
+        readonly doubleRound?: boolean;
+        readonly limits?: Partial< TournamentPairingLimits>;
+    }) => ReadonlyArray< RoundRobinRound>;
+    swissPairings: (input: ReadonlyArray< SwissStanding>, config?: Partial< TournamentPairingLimits>) => SwissPairing;
+    seedSingleElimination: (input: ReadonlyArray< TournamentEntrant>, config?: Partial< TournamentPairingLimits>) => SingleEliminationBracket;
+    advanceSingleElimination: (input: SingleEliminationBracket, inputResults: ReadonlyArray< BracketResult>, config?: Partial< TournamentPairingLimits>) => BracketProgress;
+    seedDoubleElimination: (input: ReadonlyArray< TournamentEntrant>, config?: Partial< TournamentPairingLimits>) => DoubleEliminationBracket;
+    advanceDoubleElimination: (input: DoubleEliminationBracket, inputResults: ReadonlyArray< BracketResult>, config?: Partial< TournamentPairingLimits>) => DoubleEliminationProgress;
+}>;
+
+declare interface TournamentPairingLimits {
+    readonly maxEntrants: number;
+    readonly maxMatches: number;
+    readonly maxSearchNodes: number;
+    readonly maxInputBytes: 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;
+}
+
+export declare const tournamentStageFakeLayer: (overrides?: Partial<TournamentStageService>) => Layer.Layer<TournamentStagePort>;
+
+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>;
+}>;
+
+export declare const tournamentStagePortFixture: () => {
+    kind: "port";
+    tag: typeof TournamentStagePort;
+    fakeLayer: Layer.Layer<TournamentStagePort, never, never>;
+    probe: {
+        run: () => Promise<"invalid_board" | "invalid_score" | "invalid_record" | "invalid_input" | "overflow" | "unavailable" | "forbidden" | "not_found" | "conflict" | "erased" | "limit_exceeded" | "unexpected-success">;
+        expected: string;
+    };
+};
+
+export declare const tournamentStagePortSystemFixture: Readonly<{
+    kind: "port";
+    tag: typeof TournamentStagePort;
+    fakeLayer: Layer.Layer<TournamentStagePort, never, never>;
+    probe: {
+        run: () => Effect.Effect<string, never, never>;
+        expected: string;
+    };
+}>;
+
+declare type TournamentStageService = Context.Service.Shape<typeof TournamentStagePort>;
+
+export declare const tournamentStageSystemFakeLayer: Layer.Layer<TournamentStagePort, never, never>;
+
+/** 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 declare const validateSystemFixture: Readonly<{
+    kind: "slot";
+    defaultImplementation: (input: SubmitLeaderboardInput, previous: LeaderboardRecord | null, tx: DataStore) => Effect.Effect<void, LeaderboardError>;
+    defaultProbe: {
+        run: () => Effect.Effect<string, LeaderboardError, never>;
+        expected: string;
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<string, never, never>;
+        expected: string;
+    };
+}>;
+
+export { }