@voltro/plugin-progression 0.0.0-stage → 0.88.0

package/dist/rankTables.entity.js

@@ -0,0 +1,100 @@
+import { boolean as e, id as t, integer as n, json as r, table as i, text as a, timestamp as o } from "@voltro/database";
+// src/rankTables.entity.ts
+var s = () => a().maxLength(120).externalId().sensitive("pii"), c = () => a().maxLength(120).externalId().sensitive("pii"), l = () => a().maxLength(64).nullable().serverOnly(), u = i("_voltro_prog_rank_definitions", {
+	id: t({ prefix: "prd" }),
+	tenantId: s(),
+	seasonId: a().maxLength(120).safe(),
+	config: r().serverOnly(),
+	rulesVersion: a().maxLength(120).safe(),
+	admission: n().serverOnly()
+}).index(["tenantId", "seasonId"]), d = i("_voltro_prog_rank_subjects", {
+	id: t({ prefix: "prs" }),
+	tenantId: s(),
+	ownerId: c().nullable(),
+	erased: e().serverOnly(),
+	sequence: n().serverOnly(),
+	admission: n().serverOnly()
+}).index(["tenantId", "ownerId"]), f = i("_voltro_prog_rank", {
+	id: t({ prefix: "prv" }),
+	tenantId: s(),
+	ownerId: c(),
+	ownerKey: l(),
+	seasonId: a().maxLength(120).safe(),
+	state: r().serverOnly(),
+	updatedAt: o().safe()
+}).index(["tenantId", "ownerKey"]), p = i("_voltro_prog_rank_ledger", {
+	id: t({ prefix: "prl" }),
+	tenantId: s(),
+	ownerId: c().nullable(),
+	ownerKey: l(),
+	seasonId: a().maxLength(120).safe(),
+	sequence: n().serverOnly(),
+	operationId: a().maxLength(64).safe(),
+	claimKey: a().maxLength(64).serverOnly(),
+	intent: r().nullable().serverOnly(),
+	before: r().nullable().serverOnly(),
+	after: r().nullable().serverOnly(),
+	at: o().safe()
+}).index(["tenantId", "ownerKey"]), m = i("_voltro_prog_rank_operations", {
+	id: t({ prefix: "pro" }),
+	tenantId: s(),
+	ownerKey: l(),
+	state: a().maxLength(16).oneOf([
+		"committed",
+		"replayed",
+		"erased"
+	]).serverOnly(),
+	claimKey: a().maxLength(64).serverOnly(),
+	linkedOperationId: a().maxLength(64).nullable().serverOnly(),
+	intent: r().nullable().serverOnly(),
+	digest: a().maxLength(64).nullable().serverOnly(),
+	receipt: r().nullable().serverOnly(),
+	at: o().safe()
+}).index(["tenantId", "ownerKey"]), h = i("_voltro_prog_rank_rewards", {
+	id: t({ prefix: "prr" }),
+	tenantId: s(),
+	ownerId: c().nullable(),
+	ownerKey: l(),
+	seasonId: a().maxLength(120).safe(),
+	operationId: a().maxLength(64).safe(),
+	reward: r().nullable().serverOnly(),
+	state: a().maxLength(16).oneOf([
+		"pending",
+		"delivered",
+		"erased"
+	]).serverOnly(),
+	createdAt: o().safe(),
+	deliveredAt: o().nullable().safe(),
+	deliveryIntent: r().nullable().serverOnly(),
+	deliveryDigest: a().maxLength(64).nullable().serverOnly(),
+	deliveryReceipt: r().nullable().serverOnly()
+}).index(["tenantId", "ownerKey"]), g = i("_voltro_prog_rank_closure_units", {
+	id: t({ prefix: "prc" }),
+	tenantId: s(),
+	ownerId: c().nullable(),
+	ownerKey: l(),
+	seasonId: a().maxLength(120).safe(),
+	version: n().safe(),
+	stateId: a().maxLength(64).serverOnly(),
+	until: o().safe(),
+	state: a().maxLength(16).oneOf([
+		"open",
+		"closed",
+		"erased"
+	]).serverOnly(),
+	receipt: r().nullable().serverOnly(),
+	createdAt: o().safe()
+}).index([
+	"state",
+	"until",
+	"id"
+]).index(["tenantId", "ownerKey"]), _ = [
+	u,
+	d,
+	f,
+	p,
+	m,
+	h,
+	g
+];
+export { g as rankClosureUnitsTable, u as rankDefinitionsTable, p as rankLedgerTable, m as rankOperationsTable, h as rankRewardsTable, f as rankStatesTable, d as rankSubjectsTable, _ as rankTables };

package/dist/ranks.d.ts

@@ -0,0 +1,167 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+/** Admit accepted custom-slot output for journal repair without calling historical strategies. */
+export declare const capturePlayerRank: (input: unknown, ladder: RankLadder, rulesVersion: string) => PlayerRank;
+
+export declare const captureRankRating: (input: unknown, pool: string) => RankRating;
+
+/** A read-only displayed score; it never writes or claims to decay the Ratings SQL pool. */
+export declare const defaultRankDecay: RankDecayResolver;
+
+export declare const defaultRankGrade: RankGradeResolver;
+
+export declare const defaultRankScore: RankScoreResolver;
+
+export declare const defaultRankSeasonReset: RankSeasonReset;
+
+export declare const defineRankLadder: (input: RankLadderDefinition | RankLadder) => RankLadder;
+
+export declare interface PlayerRank {
+    readonly ladderId: string;
+    readonly version: number;
+    readonly pool: string;
+    readonly games: number;
+    readonly placementsRemaining: number;
+    readonly rawScore: number;
+    readonly score: number;
+    readonly grade: RankGrade | null;
+    readonly ratingUpdatedAt: number | null;
+    readonly observedAt: number;
+    readonly rulesVersion: string;
+}
+
+declare class ProgressionError extends ProgressionError_base {
+}
+
+declare const ProgressionError_base: Schema.Class<ProgressionError, Schema.TaggedStruct<"ProgressionError", {
+    readonly code: Schema.Literals<readonly ["invalid_input", "invalid_record", "invalid_curve", "invalid_reward", "invalid_track", "invalid_stat", "overflow", "insufficient_resource", "forbidden", "conflict", "erased", "not_found", "limit_exceeded", "unavailable"]>;
+}>, YieldableError>;
+
+export declare interface RankContext {
+    readonly ladder: RankLadder;
+    readonly rating: RankRating;
+    readonly at: number;
+}
+
+export declare interface RankDecayDefinition {
+    readonly afterDays: number;
+    readonly perDay: number;
+    readonly floor: number;
+}
+
+export declare type RankDecayResolver = (input: RankGradeContext) => number;
+
+export declare interface RankGrade {
+    readonly index: number;
+    readonly tier: string;
+    readonly tierIndex: number;
+    readonly division: number;
+}
+
+export declare interface RankGradeContext extends RankContext {
+    readonly score: number;
+}
+
+export declare type RankGradeResolver = (input: RankGradeContext) => RankGrade | null;
+
+export declare interface RankLadder {
+    readonly id: string;
+    readonly version: number;
+    readonly rating: string;
+    readonly tiers: readonly string[];
+    readonly divisions: number;
+    readonly thresholds: readonly number[];
+    readonly placements: number;
+    readonly confidence: number;
+    readonly decay: RankDecayDefinition | null;
+    readonly softReset: RankResetDefinition | null;
+}
+
+export declare interface RankLadderDefinition {
+    readonly id?: string;
+    readonly version?: number;
+    readonly rating: string;
+    readonly tiers: readonly string[];
+    readonly divisions?: number;
+    /** Ascending cutoffs for each boundary, lowest division to highest. No hidden balancing values. */
+    readonly thresholds: readonly number[];
+    readonly placements?: number;
+    readonly confidence?: number;
+    readonly decay?: RankDecayDefinition | null;
+    readonly softReset?: RankResetDefinition | null;
+}
+
+export declare interface RankRating {
+    readonly pool: string;
+    readonly state: RankRatingState;
+    readonly games: number;
+    readonly updatedAt: number | null;
+}
+
+export declare class RankRatingSource extends RankRatingSource_base {
+}
+
+declare const RankRatingSource_base: Context.ServiceClass<RankRatingSource, "@voltro/RankRatingSource", RankRatingSourceService>;
+
+export declare interface RankRatingSourceService {
+    readonly read: (subject: Subject, pool: string) => Effect.Effect<RankRating, ProgressionError>;
+}
+
+/** SQL Ratings remain the authority; this detached shape matches Ratings.myRating. */
+export declare type RankRatingState = {
+    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;
+};
+
+export declare interface RankReaderService {
+    readonly mine: (subject: Subject) => Effect.Effect<readonly PlayerRank[], ProgressionError>;
+}
+
+export declare interface RankResetContext {
+    readonly ladder: RankLadder;
+    readonly score: number;
+}
+
+export declare interface RankResetDefinition {
+    readonly target: number;
+    readonly retain: number;
+}
+
+export declare type RankScoreResolver = (input: RankContext) => number;
+
+export declare type RankSeasonReset = (input: RankResetContext) => number;
+
+export declare interface RankStrategies {
+    readonly version?: string;
+    readonly score?: RankScoreResolver;
+    readonly decay?: RankDecayResolver;
+    readonly grade?: RankGradeResolver;
+    readonly seasonReset?: RankSeasonReset;
+}
+
+export declare const resolveRank: (input: RankContext, strategies?: RankStrategies) => PlayerRank;
+
+export declare const resolveRankSeasonReset: (ladderInput: RankLadder, value: number, strategies?: RankStrategies) => number;
+
+export declare const resolveRankStrategies: (input?: RankStrategies) => Readonly<{
+    version: string;
+    score: RankScoreResolver;
+    decay: RankDecayResolver;
+    grade: RankGradeResolver;
+    seasonReset: RankSeasonReset;
+}>;
+
+export { }

package/dist/ranks.js

@@ -0,0 +1,218 @@
+import { progressionError as e } from "./errors.js";
+import { identifier as t, integer as n, list as r, object as i } from "./capture.js";
+import { Context as a } from "effect";
+// src/ranks.ts
+var o = (t, n = -1e9, r = 1e9) => {
+	if (typeof t != "number" || !Number.isFinite(t) || Object.is(t, -0) || t < n || t > r) throw e("invalid_input");
+	return t;
+}, s = (r, a) => {
+	let s = i(r, [
+		"pool",
+		"state",
+		"games",
+		"updatedAt"
+	]), c = i(s.state).algorithm;
+	if (s.pool !== a || c !== "elo" && c !== "openskill" && c !== "glicko2") throw e("invalid_record");
+	let l;
+	if (c === "elo") {
+		let e = i(s.state, ["algorithm", "rating"]);
+		l = Object.freeze({
+			algorithm: c,
+			rating: o(e.rating)
+		});
+	} else if (c === "openskill") {
+		let e = i(s.state, [
+			"algorithm",
+			"mu",
+			"sigma"
+		]);
+		l = Object.freeze({
+			algorithm: c,
+			mu: o(e.mu),
+			sigma: o(e.sigma, 1e-12)
+		});
+	} else {
+		let e = i(s.state, [
+			"algorithm",
+			"rating",
+			"deviation",
+			"volatility"
+		]);
+		l = Object.freeze({
+			algorithm: "glicko2",
+			rating: o(e.rating),
+			deviation: o(e.deviation, 1e-12),
+			volatility: o(e.volatility, 1e-12)
+		});
+	}
+	let u = n(s.games, 0, 2147483647), d = s.updatedAt === null ? null : n(s.updatedAt, 0, 864e13);
+	if (u > 0 && d === null) throw e("invalid_record");
+	return Object.freeze({
+		pool: t(s.pool),
+		state: l,
+		games: u,
+		updatedAt: d
+	});
+}, c = (t) => {
+	if (typeof t != "string" || t.length < 1 || t.length > 120 || t.trim() !== t || /[\u0000-\u001f\u007f]/u.test(t)) throw e("invalid_input");
+	return t;
+}, l = (a) => {
+	let s = i(a, [
+		"id",
+		"version",
+		"rating",
+		"tiers",
+		"divisions",
+		"thresholds",
+		"placements",
+		"confidence",
+		"decay",
+		"softReset"
+	]), l = Object.freeze(r(s.tiers, 64).map(c)), u = n(s.divisions ?? 1, 1, 16), d = Object.freeze(r(s.thresholds, 1023).map((e) => o(e)));
+	if (!l.length || new Set(l).size !== l.length || d.length !== l.length * u - 1 || d.some((e, t) => t > 0 && e <= d[t - 1])) throw e("invalid_input");
+	let f = s.decay == null ? null : i(s.decay, [
+		"afterDays",
+		"perDay",
+		"floor"
+	]), p = s.softReset == null ? null : i(s.softReset, ["target", "retain"]), m = f === null ? null : Object.freeze({
+		afterDays: n(f.afterDays, 0, 365e3),
+		perDay: o(f.perDay, Number.MIN_VALUE),
+		floor: o(f.floor)
+	}), h = p === null ? null : Object.freeze({
+		target: o(p.target),
+		retain: o(p.retain, 0, 1)
+	});
+	return Object.freeze({
+		id: t(s.id ?? "rank"),
+		version: n(s.version ?? 1, 1, 1e6),
+		rating: t(s.rating),
+		tiers: l,
+		divisions: u,
+		thresholds: d,
+		placements: n(s.placements ?? 10, 0, 2147483647),
+		confidence: o(s.confidence ?? 3, 0, 10),
+		decay: m,
+		softReset: h
+	});
+}, u = ({ ladder: e, rating: t }) => t.state.algorithm === "openskill" ? Math.max(-1e9, Math.min(1e9, t.state.mu - e.confidence * t.state.sigma)) : t.state.rating, d = ({ ladder: e, rating: t, at: n, score: r }) => {
+	if (!e.decay || t.updatedAt === null) return r;
+	let i = Math.max(0, Math.floor((n - t.updatedAt) / 864e5) - e.decay.afterDays);
+	return Math.min(r, Math.max(e.decay.floor, r - i * e.decay.perDay));
+}, f = (e, t) => Object.freeze({
+	index: t,
+	tierIndex: Math.floor(t / e.divisions),
+	tier: e.tiers[Math.floor(t / e.divisions)],
+	division: e.divisions - t % e.divisions
+}), p = ({ ladder: e, rating: t, score: n }) => {
+	if (t.games < e.placements) return null;
+	let r = 0, i = e.thresholds.length;
+	for (; r < i;) {
+		let t = Math.floor((r + i) / 2);
+		n >= e.thresholds[t] ? r = t + 1 : i = t;
+	}
+	return f(e, r);
+}, m = ({ ladder: e, score: t }) => e.softReset ? e.softReset.target + (t - e.softReset.target) * e.softReset.retain : t, h = (n = {}) => {
+	let r = i(n, [
+		"version",
+		"score",
+		"decay",
+		"grade",
+		"seasonReset"
+	]), a = r.score ?? u, o = r.decay ?? d, s = r.grade ?? p, c = r.seasonReset ?? m;
+	if ([
+		a,
+		o,
+		s,
+		c
+	].some((e) => typeof e != "function") || (a !== u || o !== d || s !== p || c !== m) && (r.version === void 0 || r.version === "default.v1")) throw e("invalid_input");
+	return Object.freeze({
+		version: t(r.version ?? "default.v1"),
+		score: a,
+		decay: o,
+		grade: s,
+		seasonReset: c
+	});
+}, g = (t, r = {}) => {
+	let a = l(t.ladder), c = s(t.rating, a.rating), u = n(t.at, c.updatedAt ?? 0, 864e13), d = h(r), p = Object.freeze({
+		ladder: a,
+		rating: c,
+		at: u
+	}), m = o(d.score(p)), g = o(d.decay(Object.freeze({
+		...p,
+		score: m
+	})));
+	if (g > m) throw e("invalid_input");
+	let _ = d.grade(Object.freeze({
+		...p,
+		score: g
+	})), v = Math.max(0, a.placements - c.games), y = null;
+	if (_ !== null) {
+		let t = i(_, [
+			"index",
+			"tier",
+			"tierIndex",
+			"division"
+		]), r = f(a, n(t.index, 0, a.tiers.length * a.divisions - 1));
+		if (v > 0 || t.tier !== r.tier || t.tierIndex !== r.tierIndex || t.division !== r.division) throw e("invalid_input");
+		y = r;
+	} else if (v === 0) throw e("invalid_input");
+	return Object.freeze({
+		ladderId: a.id,
+		version: a.version,
+		pool: a.rating,
+		games: c.games,
+		placementsRemaining: v,
+		rawScore: m,
+		score: g,
+		grade: y,
+		ratingUpdatedAt: c.updatedAt,
+		observedAt: u,
+		rulesVersion: d.version
+	});
+}, _ = (e, t, n = {}) => {
+	let r = l(e);
+	return o(h(n).seasonReset(Object.freeze({
+		ladder: r,
+		score: o(t)
+	})));
+}, v = class extends a.Service()("@voltro/RankRatingSource") {}, y = (t, r, a) => {
+	let s = i(t, [
+		"ladderId",
+		"version",
+		"pool",
+		"games",
+		"placementsRemaining",
+		"rawScore",
+		"score",
+		"grade",
+		"ratingUpdatedAt",
+		"observedAt",
+		"rulesVersion"
+	]), c = n(s.games, 0, 2147483647), l = Math.max(0, r.placements - c), u = o(s.rawScore), d = o(s.score), p = s.ratingUpdatedAt === null ? null : n(s.ratingUpdatedAt, 0, 864e13), m = n(s.observedAt, p ?? 0, 864e13);
+	if (s.ladderId !== r.id || s.version !== r.version || s.pool !== r.rating || s.rulesVersion !== a || s.placementsRemaining !== l || d > u || c > 0 && p === null) throw e("invalid_record");
+	let h = null;
+	if (s.grade !== null) {
+		let t = i(s.grade, [
+			"index",
+			"tier",
+			"tierIndex",
+			"division"
+		]), a = f(r, n(t.index, 0, r.tiers.length * r.divisions - 1));
+		if (l > 0 || t.tier !== a.tier || t.tierIndex !== a.tierIndex || t.division !== a.division) throw e("invalid_record");
+		h = a;
+	} else if (l === 0) throw e("invalid_record");
+	return Object.freeze({
+		ladderId: r.id,
+		version: r.version,
+		pool: r.rating,
+		games: c,
+		placementsRemaining: l,
+		rawScore: u,
+		score: d,
+		grade: h,
+		ratingUpdatedAt: p,
+		observedAt: m,
+		rulesVersion: a
+	});
+};
+export { v as RankRatingSource, y as capturePlayerRank, s as captureRankRating, d as defaultRankDecay, p as defaultRankGrade, u as defaultRankScore, m as defaultRankSeasonReset, l as defineRankLadder, g as resolveRank, _ as resolveRankSeasonReset, h as resolveRankStrategies };