/** * Ruleset (DESIGN §9 RulesConfig): every rule number as data, so peer-hosted * modes can vary them without running code. parseRuleset() is the only way * untrusted JSON should become a Ruleset; its bounds keep matches short and * guarantee termination. */ import { z } from 'zod'; import { KEYWORD_IDS, PORTAL_IDS } from './keywords.ts'; import { STATS, type Ruleset } from './types.ts'; const int = (min: number, max: number) => z.number().int().min(min).max(max); const id = z.string().regex(/^[a-z0-9][a-z0-9-]{0,31}$/); const params = z.record(z.string().regex(/^[A-Za-z0-9]{1,24}$/), z.number().finite().min(-100).max(100)) .refine(value => Object.keys(value).length <= 8, 'At most 8 params'); const paramTable = z.record(id, params).refine(value => Object.keys(value).length <= 32, 'At most 32 entries'); export const TopicSchema = z.object({ id, name: z.string().min(1).max(32), stat: z.enum(STATS as [string, ...string[]]), portal: z.enum(PORTAL_IDS).nullable(), }).strict(); export const RulesetSchema = z.object({ version: z.string().min(1).max(16), deckSize: int(1, 30), maxCopiesPerPage: int(1, 30), maxLoaners: int(0, 30), openingHand: int(0, 10), handLimit: int(1, 12), mulligan: z.literal(false), // not implemented in v1 turns: int(1, 12), turnSeconds: int(5, 120), afkTurns: int(1, 12), energyByTurn: z.array(int(0, 20)).min(1).max(12), energyCarryMax: int(0, 10), bonusEnergy: int(0, 10), underdog: z.boolean(), topicCount: int(1, 5), distinctStats: z.boolean(), portalReveal: z.array(int(1, 12)).max(5), laneCapacity: int(1, 8), topicPool: z.array(TopicSchema).min(1).max(32), keywordParams: paramTable, portalParams: paramTable, costThresholds: z.array(int(0, 100)).length(5), powerByCost: z.array(int(0, 30)).length(7), onTopicBonus: z.array(int(0, 10)).length(7), vanillaBonus: int(0, 10), keywordsEnabled: z.array(z.enum(KEYWORD_IDS)).max(KEYWORD_IDS.length), ownedCards: z.boolean(), trendUp: z.number().finite().min(-1000).max(1000), trendDown: z.number().finite().min(-1000).max(1000), trendMinDaily: z.number().finite().min(0).max(1e9), uncheckedCostCap: int(1, 6), factionSynergyCap: int(0, 12), verifyStats: z.boolean(), percentiles: id, starterDecks: id, }).strict().superRefine((rules, ctx) => { const issue = (message: string) => ctx.addIssue({ code: 'custom', message }); if (rules.turns * rules.turnSeconds > 240) issue('turns × turnSeconds must be ≤ 240'); if (rules.energyByTurn.length < rules.turns) issue('energyByTurn needs one entry per turn'); if (rules.portalReveal.length !== rules.topicCount) issue('portalReveal needs one entry per Topic'); if (rules.openingHand > rules.handLimit) issue('openingHand > handLimit'); if (rules.trendDown > rules.trendUp) issue('trendDown > trendUp'); if (rules.costThresholds.some((value, i) => i > 0 && value < rules.costThresholds[i - 1])) issue('costThresholds must ascend'); if (rules.distinctStats) { if (rules.topicCount !== STATS.length) issue('distinctStats needs topicCount == 3'); const stats = new Set(rules.topicPool.map(topic => topic.stat)); if (stats.size < rules.topicCount) issue('topicPool lacks enough distinct stats'); } else if (rules.topicPool.length < rules.topicCount) issue('topicPool smaller than topicCount'); const topicIds = new Set(); for (const topic of rules.topicPool) { if (topicIds.has(topic.id)) issue(`Duplicate topic id: ${topic.id}`); topicIds.add(topic.id); } if (new Set(rules.keywordsEnabled).size !== rules.keywordsEnabled.length) issue('Duplicate keywordsEnabled entry'); for (const key of Object.keys(rules.keywordParams)) if (!(KEYWORD_IDS as readonly string[]).includes(key)) issue(`Unknown keyword: ${key}`); for (const key of Object.keys(rules.portalParams)) if (!topicIds.has(key) && !(PORTAL_IDS as readonly string[]).includes(key)) issue(`portalParams key is neither a Topic id nor a Portal id: ${key}`); }); /** Validate untrusted ruleset JSON. Throws a ZodError with readable issues. */ export function parseRuleset(input: unknown): Ruleset { return RulesetSchema.parse(input) as Ruleset; } /** DESIGN §10.3 default Topic pool: per stat one plain Topic and two with Portals. Portal kind = Topic id. */ export const DEFAULT_TOPIC_POOL: Ruleset['topicPool'] = [ { id: 'current-events', name: 'Current Events', stat: 'attention', portal: null }, { id: 'main-page', name: 'Main Page', stat: 'attention', portal: 'main-page' }, { id: 'trending', name: 'Trending', stat: 'attention', portal: 'trending' }, { id: 'archive', name: 'Archive', stat: 'depth', portal: null }, { id: 'featured-article', name: 'Featured Article', stat: 'depth', portal: 'featured-article' }, { id: 'stub', name: 'Stub', stat: 'depth', portal: 'stub' }, { id: 'translations', name: 'Translations', stat: 'reach', portal: null }, { id: 'interwiki', name: 'Interwiki', stat: 'reach', portal: 'interwiki' }, { id: 'disambiguation', name: 'Disambiguation', stat: 'reach', portal: 'disambiguation' }, ]; /** DESIGN §9 defaults (v1). */ export const DEFAULT_RULESET: Ruleset = { version: '1.0', deckSize: 12, maxCopiesPerPage: 2, maxLoaners: 12, openingHand: 3, handLimit: 7, mulligan: false, turns: 6, turnSeconds: 25, afkTurns: 2, energyByTurn: [1, 2, 3, 4, 5, 6], energyCarryMax: 1, bonusEnergy: 0, underdog: false, topicCount: 3, distinctStats: true, portalReveal: [2, 3, 4], laneCapacity: 3, topicPool: DEFAULT_TOPIC_POOL, keywordParams: { viral: { amount: 1, cap: 2, powerDelta: 0 }, rising: { amount: 1, cap: 2, powerDelta: 0 }, local: { amount: 1, powerDelta: 0 }, encyclopedic: { amount: 2, powerDelta: 0 }, nostalgic: { amount: 2, powerDelta: 0 }, translated: { amount: 1, powerDelta: 0 }, edition: { amount: 2, powerDelta: 0 }, obscure: { powerDelta: 0 }, wildcard: { powerDelta: 0 }, }, portalParams: { 'main-page': { amount: 1 }, trending: { factor: 2 }, 'featured-article': { amount: 2 }, stub: { value: 2 }, interwiki: { amount: 1 }, }, costThresholds: [15, 35, 55, 75, 90], powerByCost: [0, 1, 2, 4, 6, 8, 10], onTopicBonus: [0, 1, 1, 2, 2, 3, 3], vanillaBonus: 1, keywordsEnabled: ['viral', 'rising', 'local', 'encyclopedic', 'nostalgic', 'translated'], ownedCards: true, trendUp: 25, trendDown: -200, trendMinDaily: 20, uncheckedCostCap: 4, factionSynergyCap: 3, verifyStats: true, percentiles: 'card-sample-2026-11-16', starterDecks: 'default', };