@mpgd/game-services 0.6.0 → 0.7.0

package/dist/verified-leaderboard-conformance.js

@@ -71,6 +71,7 @@ async function runFirstSelectionAndSnapshotScenario(context) {
         participantLabel: 'First Player',
         attemptId: 'attempt:later',
         score: 20,
+        metrics: { elapsedMs: 20000, hints: 1, mistakes: 2 },
         completedAt: '2030-01-02T02:02:00.000Z',
     });
     const laterRecord = await context.service.recordVerifiedAttempt(laterRequest);
@@ -80,6 +81,7 @@ async function runFirstSelectionAndSnapshotScenario(context) {
         participantLabel: 'First Player',
         attemptId: 'attempt:earlier',
         score: 30,
+        metrics: { elapsedMs: 30000, hints: 0, mistakes: 1 },
         completedAt: '2030-01-02T02:01:00.000Z',
     }));
     await context.service.recordVerifiedAttempt(createAttempt({
@@ -97,10 +99,12 @@ async function runFirstSelectionAndSnapshotScenario(context) {
         participantLabel: 'First Player',
         attemptId: 'attempt:latest',
         score: 5,
+        metrics: { elapsedMs: 5000, hints: 2, mistakes: 0 },
         completedAt: '2030-01-02T02:04:00.000Z',
     }));
     assertEqual(latestRecord.retained, false, 'later completions must not replace the earliest retained attempt');
     assertEqual(latestRecord.entry.attemptId, 'attempt:earlier', 'rejected later attempts must report the retained earliest attempt');
+    assertEqual(latestRecord.entry.metrics?.elapsedMs, 30000, 'rejected attempts must report the retained entry metrics');
     const snapshot = await context.service.getSnapshot({
         leaderboardId: 'first:board',
         participantId: 'participant:first',
@@ -111,6 +115,7 @@ async function runFirstSelectionAndSnapshotScenario(context) {
     assertEqual(snapshot.entries[0]?.rank, 1, 'page entries must carry their global rank');
     assertEqual(snapshot.entries[0]?.participantId, 'participant:leader', 'ascending snapshots must rank lower scores first');
     assertEqual(snapshot.participantEntry?.attemptId, 'attempt:earlier', 'participant entries must reflect retained attempts outside the requested page');
+    assertEqual(snapshot.participantEntry?.metrics?.mistakes, 1, 'participant entries must preserve generic attempt metrics');
     assertEqual(snapshot.participantEntry?.rank, 2, 'participant entries must carry global rank');
     assertEqual(snapshot.totalParticipants, 2, 'snapshots must count retained participants');
     assertEqual(snapshot.generatedAt, context.now, 'snapshots must use the provider clock');
@@ -309,6 +314,7 @@ async function runIdentityAndDefinitionConflictsScenario(context) {
         participantLabel: 'Original Label',
         attemptId: 'attempt:identity',
         score: 42,
+        metrics: { elapsedMs: 42000, hints: 1, mistakes: 2 },
         completedAt: '2030-01-02T02:30:00.000Z',
     });
     await context.service.recordVerifiedAttempt(request);
@@ -317,6 +323,7 @@ async function runIdentityAndDefinitionConflictsScenario(context) {
         attempt: {
             ...request.attempt,
             participantLabel: 'Changed Label',
+            metrics: { mistakes: 2, elapsedMs: 42000, hints: 1 },
             completedAt: '2030-01-02T11:30:00.000+09:00',
             verification: {
                 ...request.attempt.verification,
@@ -327,10 +334,18 @@ async function runIdentityAndDefinitionConflictsScenario(context) {
     assertEqual(equivalentRetry.alreadyProcessed, true, 'equivalent retries must be idempotent');
     assertEqual(equivalentRetry.entry.participantLabel, 'Original Label', 'retry labels must not rewrite stored presentation metadata');
     assertEqual(equivalentRetry.entry.completedAt, request.attempt.completedAt, 'equivalent retries must preserve the original timestamp representation');
+    assertEqual(equivalentRetry.entry.metrics?.elapsedMs, 42000, 'equivalent retries must preserve the original metrics');
     await assertRejects(() => context.service.recordVerifiedAttempt({
         ...request,
         attempt: { ...request.attempt, score: 43 },
     }), 'attempt IDs reused with a different score must fail closed');
+    await assertRejects(() => context.service.recordVerifiedAttempt({
+        ...request,
+        attempt: {
+            ...request.attempt,
+            metrics: { elapsedMs: 42000, hints: 0, mistakes: 2 },
+        },
+    }), 'attempt IDs reused with different metrics must fail closed');
     await assertRejects(() => context.service.recordVerifiedAttempt({
         ...request,
         attempt: {
@@ -417,11 +432,15 @@ async function runMutationIsolationScenario(context) {
         participantLabel: 'Stable Label',
         attemptId: 'attempt:mutation',
         score: 50,
+        metrics: { elapsedMs: 50000, hints: 1, mistakes: 2 },
         completedAt: '2030-01-02T02:50:00.000Z',
     });
     const response = await context.service.recordVerifiedAttempt(request);
     request.definition.scoreOrder = 'descending';
     request.attempt.score = -1;
+    if (request.attempt.metrics !== undefined) {
+        request.attempt.metrics.elapsedMs = 1;
+    }
     request.attempt.verification.evidenceId = 'evidence:mutated';
     try {
         Object.assign(response.entry, { participantLabel: 'Mutated Label', score: -2 });
@@ -429,6 +448,12 @@ async function runMutationIsolationScenario(context) {
     catch {
         // Frozen provider responses are already isolated from caller mutation.
     }
+    try {
+        Object.assign(response.entry.metrics ?? {}, { elapsedMs: 2 });
+    }
+    catch {
+        // Frozen provider metric copies are already isolated from caller mutation.
+    }
     const snapshot = await context.service.getSnapshot({
         leaderboardId: 'mutation:board',
         participantId: 'participant:mutation',
@@ -440,6 +465,7 @@ async function runMutationIsolationScenario(context) {
     assert(participantEntry !== undefined, 'participant reads must return the retained entry');
     assertEqual(snapshot.definition.scoreOrder, 'ascending', 'stored definitions must be cloned');
     assertEqual(snapshotEntry.score, 50, 'stored attempts must resist caller mutation');
+    assertEqual(snapshotEntry.metrics?.elapsedMs, 50000, 'stored metrics must be cloned');
     assertEqual(snapshotEntry.participantLabel, 'Stable Label', 'response mutation must not rewrite retained entries');
     try {
         Object.assign(snapshot.definition, { scoreOrder: 'descending' });
@@ -453,12 +479,24 @@ async function runMutationIsolationScenario(context) {
     catch {
         // Frozen provider snapshot entries are already isolated from mutation.
     }
+    try {
+        Object.assign(snapshotEntry.metrics ?? {}, { elapsedMs: 3 });
+    }
+    catch {
+        // Frozen provider snapshot metrics are already isolated from mutation.
+    }
     try {
         Object.assign(participantEntry, { participantLabel: 'Participant Mutation', score: -4 });
     }
     catch {
         // Frozen provider participant entries are already isolated from mutation.
     }
+    try {
+        Object.assign(participantEntry.metrics ?? {}, { mistakes: 4 });
+    }
+    catch {
+        // Frozen provider participant metrics are already isolated from mutation.
+    }
     try {
         snapshot.entries.pop();
     }
@@ -472,9 +510,11 @@ async function runMutationIsolationScenario(context) {
     assertEqual(rereadSnapshot?.definition.scoreOrder, 'ascending', 'snapshot definition mutation must not rewrite stored policy');
     assertEqual(rereadSnapshot?.entries[0]?.score, 50, 'snapshot entry mutation must not rewrite retained attempts');
     assertEqual(rereadSnapshot?.entries[0]?.participantLabel, 'Stable Label', 'snapshot label mutation must not rewrite presentation metadata');
+    assertEqual(rereadSnapshot?.entries[0]?.metrics?.elapsedMs, 50000, 'snapshot metric mutation must not rewrite retained metrics');
     assertEqual(rereadSnapshot?.entries.length, 1, 'snapshot array mutation must not rewrite retained entries');
     assertEqual(rereadSnapshot?.participantEntry?.score, 50, 'participant entry mutation must not rewrite retained attempts');
     assertEqual(rereadSnapshot?.participantEntry?.participantLabel, 'Stable Label', 'participant entry mutation must not rewrite presentation metadata');
+    assertEqual(rereadSnapshot?.participantEntry?.metrics?.mistakes, 2, 'participant metric mutation must not rewrite retained metrics');
 }
 class ProviderOutputValidationError extends Error {
 }
@@ -552,6 +592,38 @@ async function runRuntimeValidationScenario(context) {
         score: Number.POSITIVE_INFINITY,
         completedAt: validVerificationTimestamp,
     })), 'infinite scores must fail closed');
+    await assertRejects(() => context.service.recordVerifiedAttempt(createAttempt({
+        leaderboardId: 'validation:metric-key',
+        participantId: 'participant:metric-key',
+        attemptId: 'attempt:metric-key',
+        score: 1,
+        metrics: { '1elapsedMs': 1 },
+        completedAt: validVerificationTimestamp,
+    })), 'invalid metric keys must fail closed');
+    await assertRejects(() => context.service.recordVerifiedAttempt(createAttempt({
+        leaderboardId: 'validation:metric-value',
+        participantId: 'participant:metric-value',
+        attemptId: 'attempt:metric-value',
+        score: 1,
+        metrics: { mistakes: -1 },
+        completedAt: validVerificationTimestamp,
+    })), 'negative metric values must fail closed');
+    await assertRejects(() => context.service.recordVerifiedAttempt(createAttempt({
+        leaderboardId: 'validation:metric-safe-integer',
+        participantId: 'participant:metric-safe-integer',
+        attemptId: 'attempt:metric-safe-integer',
+        score: 1,
+        metrics: { elapsedMs: Number.MAX_SAFE_INTEGER + 1 },
+        completedAt: validVerificationTimestamp,
+    })), 'unsafe integer metric values must fail closed');
+    await assertRejects(() => context.service.recordVerifiedAttempt(createAttempt({
+        leaderboardId: 'validation:metric-count',
+        participantId: 'participant:metric-count',
+        attemptId: 'attempt:metric-count',
+        score: 1,
+        metrics: Object.fromEntries(Array.from({ length: 17 }, (_, index) => [`metric${String(index)}`, index])),
+        completedAt: validVerificationTimestamp,
+    })), 'oversized metric maps must fail closed');
     const failedWriteChecks = await Promise.all([
         'validation:calendar',
         'validation:timezone',
@@ -559,6 +631,10 @@ async function runRuntimeValidationScenario(context) {
         'validation:evidence-timezone',
         'validation:score-nan',
         'validation:score-infinity',
+        'validation:metric-key',
+        'validation:metric-value',
+        'validation:metric-safe-integer',
+        'validation:metric-count',
     ].map(async (leaderboardId) => ({
         leaderboardId,
         snapshot: await context.service.getSnapshot({ leaderboardId }),
@@ -597,6 +673,7 @@ function createMutableAttempt(input) {
                 : { participantLabel: input.participantLabel }),
             attemptId: input.attemptId,
             score: input.score,
+            ...(input.metrics === undefined ? {} : { metrics: { ...input.metrics } }),
             completedAt: input.completedAt,
             verification: {
                 authorityId: 'verified-leaderboard-conformance',

package/dist/verified-leaderboard-transport.js

@@ -1,4 +1,4 @@
-import { assertGetVerifiedLeaderboardSnapshotRequest, assertVerifiedLeaderboardSnapshot, VerifiedLeaderboardCursorError, } from './verified-leaderboard.js';
+import { assertGetVerifiedLeaderboardSnapshotRequest, assertVerifiedLeaderboardSnapshot, normalizeVerifiedLeaderboardMetrics, VerifiedLeaderboardCursorError, } from './verified-leaderboard.js';
 export const verifiedLeaderboardSnapshotPath = '/game-services/verified-leaderboard/snapshot';
 export function createVerifiedLeaderboardSnapshotFetchHandler(input) {
     const path = input.path ?? verifiedLeaderboardSnapshotPath;
@@ -99,10 +99,35 @@ export function createVerifiedLeaderboardSnapshotFetchClient(input) {
                 throw new Error(`Verified leaderboard snapshot request failed: ${error}.`);
             }
             assertVerifiedLeaderboardSnapshot(body);
-            return body;
+            return normalizeSnapshotMetrics(body);
         },
     };
 }
+function normalizeSnapshotMetrics(input) {
+    const normalizeEntry = (entry) => ({
+        rank: entry.rank,
+        participantId: entry.participantId,
+        ...(entry.participantLabel === undefined
+            ? {}
+            : { participantLabel: entry.participantLabel }),
+        attemptId: entry.attemptId,
+        score: entry.score,
+        ...(entry.metrics === undefined
+            ? {}
+            : { metrics: normalizeVerifiedLeaderboardMetrics(entry.metrics) }),
+        completedAt: entry.completedAt,
+    });
+    return {
+        definition: input.definition,
+        entries: input.entries.map(normalizeEntry),
+        ...(input.participantEntry === undefined
+            ? {}
+            : { participantEntry: normalizeEntry(input.participantEntry) }),
+        totalParticipants: input.totalParticipants,
+        generatedAt: input.generatedAt,
+        ...(input.nextCursor === undefined ? {} : { nextCursor: input.nextCursor }),
+    };
+}
 function readSnapshotRequest(url) {
     const allowedParameters = new Set(['leaderboardId', 'limit', 'cursor']);
     for (const parameter of url.searchParams.keys()) {

package/dist/verified-leaderboard.d.ts

@@ -1,6 +1,9 @@
 export type VerifiedLeaderboardScoreOrder = 'ascending' | 'descending';
 export type VerifiedLeaderboardAttemptSelection = 'first' | 'best';
+export type VerifiedLeaderboardMetrics = Readonly<Record<string, number>>;
 export declare const verifiedLeaderboardIdentifierMaximumLength = 512;
+export declare const verifiedLeaderboardMetricsMaximumCount = 16;
+export declare const verifiedLeaderboardMetricKeyMaximumLength = 64;
 export interface VerifiedLeaderboardDefinition {
   readonly leaderboardId: string;
   readonly scoreOrder: VerifiedLeaderboardScoreOrder;
@@ -16,6 +19,7 @@ export interface VerifiedLeaderboardAttempt {
   readonly participantLabel?: string;
   readonly attemptId: string;
   readonly score: number;
+  readonly metrics?: VerifiedLeaderboardMetrics;
   readonly completedAt: string;
   readonly verification: LeaderboardVerificationEvidence;
 }
@@ -29,6 +33,7 @@ export interface LeaderboardRankedEntry {
   readonly participantLabel?: string;
   readonly attemptId: string;
   readonly score: number;
+  readonly metrics?: VerifiedLeaderboardMetrics;
   readonly completedAt: string;
 }
 export interface RecordVerifiedLeaderboardAttemptResponse {
@@ -107,6 +112,10 @@ export declare function assertRecordVerifiedLeaderboardAttemptRequest(input: unk
 export declare function assertRecordVerifiedLeaderboardAttemptResponse(input: unknown): asserts input is RecordVerifiedLeaderboardAttemptResponse;
 export declare function assertGetVerifiedLeaderboardSnapshotRequest(input: unknown): asserts input is GetVerifiedLeaderboardSnapshotRequest;
 export declare function assertLeaderboardRankedEntry(input: unknown): asserts input is LeaderboardRankedEntry;
+export declare function assertVerifiedLeaderboardMetrics(input: unknown): asserts input is VerifiedLeaderboardMetrics | undefined;
+export declare function normalizeVerifiedLeaderboardMetrics(input: undefined): undefined;
+export declare function normalizeVerifiedLeaderboardMetrics(input: VerifiedLeaderboardMetrics): VerifiedLeaderboardMetrics;
+export declare function areVerifiedLeaderboardMetricsEqual(left: VerifiedLeaderboardMetrics | undefined, right: VerifiedLeaderboardMetrics | undefined): boolean;
 export declare function assertVerifiedLeaderboardSnapshot(input: unknown): asserts input is VerifiedLeaderboardSnapshot;
 export declare function createVerifiedLeaderboardCursor(definition: VerifiedLeaderboardDefinition, entry: LeaderboardRankedEntry): string;
 export declare function parseVerifiedLeaderboardCursor(cursor: string, definition: VerifiedLeaderboardDefinition): VerifiedLeaderboardCursorPosition;

package/dist/verified-leaderboard.js

@@ -1,4 +1,7 @@
 export const verifiedLeaderboardIdentifierMaximumLength = 512;
+export const verifiedLeaderboardMetricsMaximumCount = 16;
+export const verifiedLeaderboardMetricKeyMaximumLength = 64;
+const verifiedLeaderboardMetricKeyPattern = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/;
 const timestampPattern = new RegExp('^(\\d{4})-(\\d{2})-(\\d{2})'
     + 'T(\\d{2}):(\\d{2}):(\\d{2})'
     + '(?:\\.(\\d{1,3}))?(Z|([+-])(\\d{2}):(\\d{2}))$');
@@ -143,6 +146,7 @@ export function assertVerifiedLeaderboardAttempt(input) {
     assertOptionalNonEmptyString(input.participantLabel, 'participantLabel');
     assertVerifiedLeaderboardIdentifier(input.attemptId, 'attemptId');
     assertFiniteNumber(input.score, 'score');
+    assertVerifiedLeaderboardMetrics(input.metrics);
     assertTimestamp(input.completedAt, 'completedAt');
     assertLeaderboardVerificationEvidence(input.verification);
 }
@@ -188,8 +192,46 @@ export function assertLeaderboardRankedEntry(input) {
     assertOptionalNonEmptyString(input.participantLabel, 'participantLabel');
     assertVerifiedLeaderboardIdentifier(input.attemptId, 'attemptId');
     assertFiniteNumber(input.score, 'score');
+    assertVerifiedLeaderboardMetrics(input.metrics);
     assertTimestamp(input.completedAt, 'completedAt');
 }
+export function assertVerifiedLeaderboardMetrics(input) {
+    if (input === undefined) {
+        return;
+    }
+    assertRecord(input, 'metrics');
+    const keys = Object.keys(input);
+    if (keys.length > verifiedLeaderboardMetricsMaximumCount) {
+        throw new Error(`metrics must contain at most ${String(verifiedLeaderboardMetricsMaximumCount)} keys.`);
+    }
+    for (const key of keys) {
+        if (!verifiedLeaderboardMetricKeyPattern.test(key)) {
+            throw new Error('metric keys must start with an ASCII letter and contain at most '
+                + `${String(verifiedLeaderboardMetricKeyMaximumLength)} ASCII letters, digits, dots, `
+                + 'underscores, or hyphens.');
+        }
+        const value = input[key];
+        if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+            throw new Error('metric values must be non-negative safe integers.');
+        }
+    }
+}
+export function normalizeVerifiedLeaderboardMetrics(input) {
+    assertVerifiedLeaderboardMetrics(input);
+    if (input === undefined) {
+        return undefined;
+    }
+    return Object.freeze(Object.fromEntries(Object.entries(input).sort(([left], [right]) => compareOrdinal(left, right))));
+}
+export function areVerifiedLeaderboardMetricsEqual(left, right) {
+    if (left === undefined || right === undefined) {
+        return left === right;
+    }
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    return leftKeys.length === rightKeys.length
+        && leftKeys.every((key) => left[key] === right[key]);
+}
 export function assertVerifiedLeaderboardSnapshot(input) {
     assertRecord(input, 'VerifiedLeaderboardSnapshot');
     assertVerifiedLeaderboardDefinition(input.definition);
@@ -292,6 +334,7 @@ function toRankedEntry(attempt, rank) {
             : { participantLabel: attempt.participantLabel }),
         attemptId: attempt.attemptId,
         score: attempt.score,
+        ...verifiedLeaderboardMetricsProperty(attempt.metrics),
         completedAt: attempt.completedAt,
     };
     assertLeaderboardRankedEntry(entry);
@@ -301,6 +344,7 @@ function assertSameAttempt(existing, candidate) {
     if (existing.participantId !== candidate.participantId
         || existing.attemptId !== candidate.attemptId
         || existing.score !== candidate.score
+        || !areVerifiedLeaderboardMetricsEqual(existing.metrics, candidate.metrics)
         || parseTimestamp(existing.completedAt) !== parseTimestamp(candidate.completedAt)
         || existing.verification.authorityId !== candidate.verification.authorityId
         || existing.verification.evidenceId !== candidate.verification.evidenceId
@@ -324,6 +368,7 @@ function cloneVerifiedLeaderboardAttempt(input) {
             : { participantLabel: input.participantLabel }),
         attemptId: input.attemptId,
         score: input.score,
+        ...verifiedLeaderboardMetricsProperty(input.metrics),
         completedAt: input.completedAt,
         verification: {
             authorityId: input.verification.authorityId,
@@ -345,6 +390,7 @@ function cloneRecordResponse(input, alreadyProcessed) {
                 : { participantLabel: input.entry.participantLabel }),
             attemptId: input.entry.attemptId,
             score: input.entry.score,
+            ...verifiedLeaderboardMetricsProperty(input.entry.metrics),
             completedAt: input.entry.completedAt,
         },
         ...(input.reason === undefined ? {} : { reason: input.reason }),
@@ -454,6 +500,9 @@ function compareOrdinal(left, right) {
     }
     return left > right ? 1 : 0;
 }
+function verifiedLeaderboardMetricsProperty(metrics) {
+    return metrics === undefined ? {} : { metrics: normalizeVerifiedLeaderboardMetrics(metrics) };
+}
 function compareRankedEntryToCursor(definition, entry, cursor) {
     if (entry.score !== cursor.score) {
         const comparison = entry.score < cursor.score ? -1 : 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -77,9 +77,9 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
+    "@mpgd/analytics": "0.3.5",
     "@mpgd/catalog": "0.3.5",
-    "@mpgd/platform": "0.5.1",
-    "@mpgd/analytics": "0.3.5"
+    "@mpgd/platform": "0.5.1"
   },
   "devDependencies": {
     "ttsc": "0.18.4",