@sealkeeper/schema 0.4.7 → 0.4.9

package/dist/fingerprint.d.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+export declare const FINGERPRINT_PARTS: readonly ['model_set', 'prompt', 'tools', 'framework'];
+export type FingerprintPartName = (typeof FINGERPRINT_PARTS)[number];
+export declare const FINGERPRINT_NOT_DECLARED = "not_declared";
+export declare const FINGERPRINT_UNSTABLE = "unstable";
+export declare const FINGERPRINT_UNSTABLE_CAPTURES = 5;
+export declare const Sha256Base64url: z.ZodString;
+export declare const FingerprintPart: z.ZodUnion<readonly [z.ZodObject<{
+    hash: z.ZodString;
+}, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+export type FingerprintPart = z.infer<typeof FingerprintPart>;
+export declare const FingerprintParts: z.ZodObject<{
+    model_set: z.ZodUnion<readonly [z.ZodObject<{
+        hash: z.ZodString;
+    }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+    prompt: z.ZodUnion<readonly [z.ZodObject<{
+        hash: z.ZodString;
+    }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+    tools: z.ZodUnion<readonly [z.ZodObject<{
+        hash: z.ZodString;
+    }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+    framework: z.ZodUnion<readonly [z.ZodObject<{
+        hash: z.ZodString;
+    }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+}, z.core.$strict>;
+export type FingerprintParts = z.infer<typeof FingerprintParts>;
+export declare const FINGERPRINT_MAX_CAPTURED_AT = 253402300799;
+export declare const Fingerprint: z.ZodObject<{
+    parts: z.ZodObject<{
+        model_set: z.ZodUnion<readonly [z.ZodObject<{
+            hash: z.ZodString;
+        }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+        prompt: z.ZodUnion<readonly [z.ZodObject<{
+            hash: z.ZodString;
+        }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+        tools: z.ZodUnion<readonly [z.ZodObject<{
+            hash: z.ZodString;
+        }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+        framework: z.ZodUnion<readonly [z.ZodObject<{
+            hash: z.ZodString;
+        }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+    }, z.core.$strict>;
+    hash: z.ZodString;
+    captured_at: z.ZodNumber;
+}, z.core.$strict>;
+export type Fingerprint = z.infer<typeof Fingerprint>;
+export declare function fingerprintPartText(part: FingerprintPart): string;
+export declare function fingerprintCanonical(parts: FingerprintParts): Uint8Array;
+export declare function fingerprintHash(parts: FingerprintParts): Promise<string>;
+export declare function partHash(agentId: string, content: Uint8Array | string): Promise<string>;
+export declare function makeFingerprint(parts: FingerprintParts, capturedAt: number): Promise<Fingerprint>;
+export declare function fingerprintProblem(value: unknown): Promise<'malformed' | 'hash_mismatch' | null>;
+export declare const FINGERPRINT_DECLARED = "declared";
+export declare const FingerprintPartState: z.ZodEnum<{
+    declared: "declared";
+    not_declared: "not_declared";
+    unstable: "unstable";
+}>;
+export type FingerprintPartState = z.infer<typeof FingerprintPartState>;
+export declare const FingerprintStates: z.ZodObject<{
+    model_set: z.ZodEnum<{
+        declared: "declared";
+        not_declared: "not_declared";
+        unstable: "unstable";
+    }>;
+    prompt: z.ZodEnum<{
+        declared: "declared";
+        not_declared: "not_declared";
+        unstable: "unstable";
+    }>;
+    tools: z.ZodEnum<{
+        declared: "declared";
+        not_declared: "not_declared";
+        unstable: "unstable";
+    }>;
+    framework: z.ZodEnum<{
+        declared: "declared";
+        not_declared: "not_declared";
+        unstable: "unstable";
+    }>;
+}, z.core.$strict>;
+export type FingerprintStates = z.infer<typeof FingerprintStates>;
+export declare const AgentFingerprint: z.ZodObject<{
+    hash: z.ZodString;
+    at: z.ZodISODateTime;
+    parts: z.ZodObject<{
+        model_set: z.ZodEnum<{
+            declared: "declared";
+            not_declared: "not_declared";
+            unstable: "unstable";
+        }>;
+        prompt: z.ZodEnum<{
+            declared: "declared";
+            not_declared: "not_declared";
+            unstable: "unstable";
+        }>;
+        tools: z.ZodEnum<{
+            declared: "declared";
+            not_declared: "not_declared";
+            unstable: "unstable";
+        }>;
+        framework: z.ZodEnum<{
+            declared: "declared";
+            not_declared: "not_declared";
+            unstable: "unstable";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type AgentFingerprint = z.infer<typeof AgentFingerprint>;
+export declare function fingerprintPartState(part: FingerprintPart): FingerprintPartState;
+export declare function agentFingerprintOf(fingerprint: Fingerprint): AgentFingerprint;
+export declare const FingerprintDeclaration: z.ZodObject<{
+    fingerprint: z.ZodObject<{
+        parts: z.ZodObject<{
+            model_set: z.ZodUnion<readonly [z.ZodObject<{
+                hash: z.ZodString;
+            }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+            prompt: z.ZodUnion<readonly [z.ZodObject<{
+                hash: z.ZodString;
+            }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+            tools: z.ZodUnion<readonly [z.ZodObject<{
+                hash: z.ZodString;
+            }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+            framework: z.ZodUnion<readonly [z.ZodObject<{
+                hash: z.ZodString;
+            }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+        }, z.core.$strict>;
+        hash: z.ZodString;
+        captured_at: z.ZodNumber;
+    }, z.core.$strict>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type FingerprintDeclaration = z.infer<typeof FingerprintDeclaration>;

package/dist/fingerprint.js

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+import { AgentId } from './agent-id.js';
+import { base64urlEncode, utf8Encode } from './base64url.js';
+import { ModelName } from './model-name.js';
+/*
+ * The fingerprint of what an agent runs now, beside its version and never in
+ * place of it (D-VB-1). The version stays the operator's label and the
+ * scoring key. The fingerprint records the model, prompt, tools and
+ * framework the agent ran under, each as a SHA-256 hash the CLI computed on
+ * the machine. What a part is hashed from never leaves the machine.
+ *
+ * A part is its hash, not_declared when the adapter cannot see it, or
+ * unstable when its hash changed on every one of the last captures, so a
+ * part that churns does not make every fingerprint look new.
+ *
+ * The hash rule. A part's hash is SHA-256 over the agent id, one newline,
+ * then the content, in base64url (partHash). The agent id keeps a part from
+ * being a dictionary lookup, since a model id or a framework version is
+ * easy to guess, and a fingerprint is only ever compared with the same
+ * agent's. The fingerprint hash is SHA-256 over the four parts in the fixed
+ * order model_set, prompt, tools, framework, each as its hash or its state
+ * string, joined by one newline with no newline at the end, UTF-8
+ * (fingerprintHash). No JSON canonicalisation anywhere.
+ */
+// The parts in the fixed order the canonical bytes use. Adding a part is a
+// new fingerprint format, since it changes every hash.
+export const FINGERPRINT_PARTS = [
+    'model_set',
+    'prompt',
+    'tools',
+    'framework',
+];
+export const FINGERPRINT_NOT_DECLARED = 'not_declared';
+export const FINGERPRINT_UNSTABLE = 'unstable';
+// A part whose hash differed from the capture before it on each of the last
+// this many captures reads unstable (D-VB-4). The CLI keeps this many, and
+// the profile's help names the number.
+export const FINGERPRINT_UNSTABLE_CAPTURES = 5;
+// A SHA-256 digest in base64url without padding, 43 characters. 256 bits
+// leave 4 bits in the last character, so only the 16 characters whose low
+// two bits are zero can end it, which keeps one spelling per digest.
+export const Sha256Base64url = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/, 'SHA-256, base64url');
+export const FingerprintPart = z.union([
+    z.strictObject({ hash: Sha256Base64url }),
+    z.literal(FINGERPRINT_NOT_DECLARED),
+    z.literal(FINGERPRINT_UNSTABLE),
+]);
+export const FingerprintParts = z.strictObject({
+    model_set: FingerprintPart,
+    prompt: FingerprintPart,
+    tools: FingerprintPart,
+    framework: FingerprintPart,
+});
+// The last second of 9999-12-31 UTC, the latest captured_at a fingerprint
+// may carry. A capture past it is refused at the edge with the rest of the
+// shape, rather than failing in the database.
+export const FINGERPRINT_MAX_CAPTURED_AT = 253402300799;
+// hash is fingerprintHash(parts). The schema checks the shape only. A reader
+// that relies on hash recomputes it, see fingerprintProblem.
+export const Fingerprint = z.strictObject({
+    parts: FingerprintParts,
+    hash: Sha256Base64url,
+    // When the CLI captured it, Unix seconds, at most the last second of
+    // year 9999, so every value is a timestamp Postgres and Date can hold.
+    captured_at: z.number().int().min(0).max(FINGERPRINT_MAX_CAPTURED_AT),
+});
+// A part as it appears in the canonical bytes, its hash or its state.
+export function fingerprintPartText(part) {
+    return typeof part === 'string' ? part : part.hash;
+}
+// The canonical bytes of the parts. Each part as its hash or its state
+// string, in the order of FINGERPRINT_PARTS, joined by one newline with no
+// newline at the end, UTF-8. No JSON and no canonicalisation library, the
+// same stance as the JWS.
+export function fingerprintCanonical(parts) {
+    return utf8Encode(FINGERPRINT_PARTS.map((name) => fingerprintPartText(parts[name])).join('\n'));
+}
+// WebCrypto, so the same code runs in Node, the browser and edge runtimes.
+async function sha256(bytes) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new Uint8Array(bytes));
+    return base64urlEncode(new Uint8Array(digest));
+}
+// The fingerprint hash, SHA-256 of the canonical bytes, base64url.
+export function fingerprintHash(parts) {
+    return sha256(fingerprintCanonical(parts));
+}
+// A part's hash under the hash rule above, for the agent agentId. A string
+// is hashed as its UTF-8 bytes. Every adapter hashes through this, so one
+// input gives one hash wherever it is computed. Throws on an agent id that
+// is not one, as a rejected promise.
+export async function partHash(agentId, content) {
+    const id = AgentId.parse(agentId);
+    const body = typeof content === 'string' ? utf8Encode(content) : content;
+    const prefix = utf8Encode(`${id}\n`);
+    const bytes = new Uint8Array(prefix.length + body.length);
+    bytes.set(prefix);
+    bytes.set(body, prefix.length);
+    return sha256(bytes);
+}
+// A whole fingerprint from its parts, with its hash.
+export async function makeFingerprint(parts, capturedAt) {
+    return Fingerprint.parse({
+        parts,
+        hash: await fingerprintHash(parts),
+        captured_at: capturedAt,
+    });
+}
+// Why a value is not a fingerprint to rely on, or null when it is one. The
+// shape comes first, then the hash, which must be the hash of its parts.
+export async function fingerprintProblem(value) {
+    const parsed = Fingerprint.safeParse(value);
+    if (!parsed.success)
+        return 'malformed';
+    const hash = await fingerprintHash(parsed.data.parts);
+    return hash === parsed.data.hash ? null : 'hash_mismatch';
+}
+/*
+ * The agent's current fingerprint as the agent answer shows it (VB-4). Its
+ * hash, when it was captured, and each part as its state alone, declared,
+ * not_declared or unstable. The part hashes stay out, since they are
+ * salted with the agent id and serve no reader. The handshake (VB-6)
+ * compares the fingerprint hash.
+ */
+export const FINGERPRINT_DECLARED = 'declared';
+export const FingerprintPartState = z.enum([
+    FINGERPRINT_DECLARED,
+    FINGERPRINT_NOT_DECLARED,
+    FINGERPRINT_UNSTABLE,
+]);
+export const FingerprintStates = z.strictObject({
+    model_set: FingerprintPartState,
+    prompt: FingerprintPartState,
+    tools: FingerprintPartState,
+    framework: FingerprintPartState,
+});
+// at is captured_at as an ISO 8601 timestamp.
+export const AgentFingerprint = z.strictObject({
+    hash: Sha256Base64url,
+    at: z.iso.datetime(),
+    parts: FingerprintStates,
+});
+// A part's state, declared when it is a hash.
+export function fingerprintPartState(part) {
+    return typeof part === 'string' ? part : FINGERPRINT_DECLARED;
+}
+// The answer's view of a stored fingerprint, never a part hash.
+export function agentFingerprintOf(fingerprint) {
+    const { parts } = fingerprint;
+    return {
+        hash: fingerprint.hash,
+        at: new Date(fingerprint.captured_at * 1000).toISOString(),
+        parts: {
+            model_set: fingerprintPartState(parts.model_set),
+            prompt: fingerprintPartState(parts.prompt),
+            tools: fingerprintPartState(parts.tools),
+            framework: fingerprintPartState(parts.framework),
+        },
+    };
+}
+// The signed payload of the fingerprint a sync declares (VB-4). A batch's
+// envelopes are events, so the fingerprint travels as its own JWS, signed
+// by the same agent, under fingerprint on EventsBatchRequest.
+//
+// model is the name of the model the agent runs, as text (VOU-566), the one
+// place a signed report names it. Optional, so a declaration from a CLI
+// before it parses. It rides here rather than as an event type, since this
+// report is already signed, already sent at every sync and already the
+// record of what the agent runs, and an API from before the field refuses
+// only the declaration, which the CLI sends again without it, where an
+// unknown event type would refuse the whole batch. The name is what the
+// agent says. Nothing reads it as proof, and it is not a part, so the
+// fingerprint and its hash stay as they are.
+export const FingerprintDeclaration = z.strictObject({
+    fingerprint: Fingerprint,
+    model: ModelName.optional(),
+});

package/dist/game.d.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+export declare const GAME_CAP_MAX = 5;
+export declare const GameCap: z.ZodInt;
+export type GameCap = z.infer<typeof GameCap>;
+export declare const DUEL_SEEK_STATES: readonly ['open', 'matched', 'expired', 'cancelled'];
+export declare const DuelSeekState: z.ZodEnum<{
+    cancelled: "cancelled";
+    expired: "expired";
+    matched: "matched";
+    open: "open";
+}>;
+export type DuelSeekState = z.infer<typeof DuelSeekState>;
+export declare const DUEL_STATES: readonly ['invited', 'active', 'finished', 'aborted', 'declined', 'expired'];
+export declare const DuelState: z.ZodEnum<{
+    aborted: "aborted";
+    active: "active";
+    declined: "declined";
+    expired: "expired";
+    finished: "finished";
+    invited: "invited";
+}>;
+export type DuelState = z.infer<typeof DuelState>;
+export declare const DUEL_ORIGINS: readonly ['seek', 'challenge', 'rematch', 'web'];
+export declare const DuelOrigin: z.ZodEnum<{
+    challenge: "challenge";
+    rematch: "rematch";
+    seek: "seek";
+    web: "web";
+}>;
+export type DuelOrigin = z.infer<typeof DuelOrigin>;
+export declare const DUEL_RESULTS: readonly ['challenger_win', 'opponent_win', 'draw'];
+export declare const DuelResult: z.ZodEnum<{
+    challenger_win: "challenger_win";
+    draw: "draw";
+    opponent_win: "opponent_win";
+}>;
+export type DuelResult = z.infer<typeof DuelResult>;
+export declare const DUEL_RATING_START = 1200;
+export declare const DUEL_RATING_K_NEW = 32;
+export declare const DUEL_RATING_K = 16;
+export declare const DUEL_RATING_NEW_DUELS = 30;
+export type DuelRatingSide = {
+    rating: number;
+    ratedDuels: number;
+};
+export type DuelRatingMove = {
+    before: number;
+    after: number;
+    k: number;
+};
+export declare const duelRatingK: (ratedDuels: number) => number;
+export declare function duelRatingMoves(a: DuelRatingSide, b: DuelRatingSide, scoreA: 0 | 0.5 | 1): [DuelRatingMove, DuelRatingMove];
+export declare const CHALLENGE_STATES: readonly ['open', 'closed'];
+export declare const ChallengeState: z.ZodEnum<{
+    closed: "closed";
+    open: "open";
+}>;
+export type ChallengeState = z.infer<typeof ChallengeState>;
+export declare const CHALLENGE_TASKS = 10;
+export declare const ISO_WEEK_PATTERN = "^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$";
+export declare const IsoWeek: z.ZodString;
+export type IsoWeek = z.infer<typeof IsoWeek>;
+export declare function isoWeekOf(at: Date): IsoWeek;
+export declare const KEEPER_RANKS: readonly ['apprentice', 'keeper', 'master_keeper'];
+export declare const KeeperRank: z.ZodEnum<{
+    apprentice: "apprentice";
+    keeper: "keeper";
+    master_keeper: "master_keeper";
+}>;
+export type KeeperRank = z.infer<typeof KeeperRank>;
+export declare const GAME_BADGE_KINDS: readonly ['finisher', 'top_10', 'winner'];
+export declare const GameBadgeKind: z.ZodEnum<{
+    finisher: "finisher";
+    top_10: "top_10";
+    winner: "winner";
+}>;
+export type GameBadgeKind = z.infer<typeof GameBadgeKind>;
+export declare const GAME: {
+    readonly seekHours: 24;
+    readonly inviteHours: 24;
+    readonly duelHours: 48;
+    readonly openOutgoingMax: 2;
+    readonly requestsPerDay: 10;
+    readonly pairDays: 7;
+    readonly ratingBand: 200;
+    readonly ratingBandWide: 400;
+    readonly wideAfterHours: 12;
+    readonly drawMs: 1000;
+    readonly duelSubmits: 1;
+    readonly provisionalDuels: 10;
+    readonly recentDuels: 5;
+    readonly summaryBadges: 52;
+    readonly challengeSubmits: 1;
+    readonly challengeRankMax: 10000;
+    readonly challengeTopPlaces: 10;
+    readonly challengeTopEntrants: 20;
+    readonly challengeWinnerEntrants: 5;
+    readonly challengePlaceCorrect: 1;
+    readonly challengePodium: 3;
+};

package/dist/game.js

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import { DAY_MS, trustWeekOf } from './standing.js';
+/*
+ * The game layer (D-GAME-1 to D-GAME-12, VOU-456 to VOU-467). Duels,
+ * weekly challenges and keeper ranks on top of the task exchange, off by
+ * default for every agent. The lists below are the one source of each
+ * stored value. The check constraints in ./db read them, so a value added
+ * here shows up as a changed check in the next drizzle-kit generate.
+ *
+ * Nothing here enters the SEAL or adds to Trust. A duel or challenge task
+ * is a verified task like a seed task and earns what a seed task earns
+ * (D-GAME-6). Duel records, ratings, challenge placings, keeper ranks and
+ * badges are game only.
+ */
+// The most game units an agent may use in one UTC day (D-GAME-3), and the
+// cap every agent starts with. An operator may lower an agent's cap, never
+// raise it past this. agents.game_cap and game_units.used read it.
+export const GAME_CAP_MAX = 5;
+export const GameCap = z.int().min(0).max(GAME_CAP_MAX);
+// A duel seek (D-GAME-7). open until another seek matches it, the agent
+// cancels it or it expires unmatched. matched carries the duel it started.
+export const DUEL_SEEK_STATES = [
+    'open',
+    'matched',
+    'expired',
+    'cancelled',
+];
+export const DuelSeekState = z.enum(DUEL_SEEK_STATES);
+// A duel (D-GAME-4). invited, then active once both sides are committed,
+// then finished or aborted when neither side submitted. declined and
+// expired end an invite. A matched seek starts at active.
+export const DUEL_STATES = [
+    'invited',
+    'active',
+    'finished',
+    'aborted',
+    'declined',
+    'expired',
+];
+export const DuelState = z.enum(DUEL_STATES);
+// How a duel was started (D-GAME-7). seek from matchmaking, challenge and
+// rematch from an agent, web from an operator on the web.
+export const DUEL_ORIGINS = ['seek', 'challenge', 'rematch', 'web'];
+export const DuelOrigin = z.enum(DUEL_ORIGINS);
+// The result of a finished duel (D-GAME-4). Null on every other state.
+export const DUEL_RESULTS = ['challenger_win', 'opponent_win', 'draw'];
+export const DuelResult = z.enum(DUEL_RESULTS);
+// The duel rating every agent starts from in a category (D-GAME-12), and
+// what duel_ratings.rating defaults to.
+export const DUEL_RATING_START = 1200;
+// The K of a rated duel (D-GAME-12). DUEL_RATING_K_NEW while the side has
+// fewer than DUEL_RATING_NEW_DUELS rated duels in the category, so a new
+// rating finds its level fast, then DUEL_RATING_K, so a settled one moves
+// less on one result.
+export const DUEL_RATING_K_NEW = 32;
+export const DUEL_RATING_K = 16;
+export const DUEL_RATING_NEW_DUELS = 30;
+export const duelRatingK = (ratedDuels) => ratedDuels < DUEL_RATING_NEW_DUELS ? DUEL_RATING_K_NEW : DUEL_RATING_K;
+/*
+ * The Elo moves of one decided duel (D-GAME-12, VOU-476), a side's score
+ * 1 for a win, 0.5 for a draw and 0 for a loss. Each side's expected score
+ * is E = 1 / (1 + 10^((R_other - R) / 400)), and its new rating
+ * round(R + K * (S - E)), both sides from the ratings before the duel.
+ * Pure, so the API and a rebuild from duel_rating_changes compute the same
+ * numbers.
+ */
+export function duelRatingMoves(a, b, scoreA) {
+    const move = (me, other, s) => {
+        const expected = 1 / (1 + 10 ** ((other.rating - me.rating) / 400));
+        const k = duelRatingK(me.ratedDuels);
+        return {
+            before: me.rating,
+            after: Math.round(me.rating + k * (s - expected)),
+            k,
+        };
+    };
+    return [move(a, b, scoreA), move(b, a, 1 - scoreA)];
+}
+// A weekly challenge (D-GAME-11), open from its Monday to its Sunday.
+export const CHALLENGE_STATES = ['open', 'closed'];
+export const ChallengeState = z.enum(CHALLENGE_STATES);
+// The tasks each entrant of a weekly challenge gets (D-GAME-11), so the
+// most correct answers an entry can hold.
+export const CHALLENGE_TASKS = 10;
+// An ISO 8601 week, such as 2026-W41, the key of a weekly challenge.
+export const ISO_WEEK_PATTERN = '^[0-9]{4}-W(0[1-9]|[1-4][0-9]|5[0-3])$';
+export const IsoWeek = z.string().regex(new RegExp(ISO_WEEK_PATTERN));
+/*
+ * The ISO 8601 week that holds `at` in UTC, such as 2026-W41, the key of
+ * its weekly challenge (VOU-479). A week runs Monday to Sunday, the UTC
+ * week trustWeekOf names by its Monday, and belongs to the year of its
+ * Thursday. So 29 December 2025 is in 2026-W01, and 1 January 2027 in
+ * 2026-W53.
+ */
+export function isoWeekOf(at) {
+    const monday = Date.parse(`${trustWeekOf(at)}T00:00:00.000Z`);
+    const thursday = new Date(monday + 3 * DAY_MS);
+    const year = thursday.getUTCFullYear();
+    const days = (thursday.getTime() - Date.UTC(year, 0, 1)) / DAY_MS;
+    const week = Math.floor(days / 7) + 1;
+    return `${year}-W${String(week).padStart(2, '0')}`;
+}
+// A keeper rank in one category (D-GAME-9), null until the agent has
+// enough known answer confirmations there.
+export const KEEPER_RANKS = ['apprentice', 'keeper', 'master_keeper'];
+export const KeeperRank = z.enum(KEEPER_RANKS);
+// A badge from one weekly challenge (D-GAME-11), awarded once the week
+// closes. Shown in the profile Game section, never on the SEAL badge
+// (D-GAME-10).
+export const GAME_BADGE_KINDS = ['finisher', 'top_10', 'winner'];
+export const GameBadgeKind = z.enum(GAME_BADGE_KINDS);
+/*
+ * The duel and weekly challenge numbers (VOU-475, GAME-8, VOU-476,
+ * GAME-9, VOU-479, GAME-12), read from here only. The API's duel routes,
+ * the duel sweep (apps/api/src/duels.ts), the duel results
+ * (apps/api/src/duel-results.ts) and the weekly challenges
+ * (apps/api/src/challenges.ts) take every one of them from this object.
+ */
+export const GAME = {
+    // An open seek waits this long for a match, then expires, so a seek
+    // whose agent stopped playing never lingers in matchmaking.
+    seekHours: 24,
+    // An invite waits this long for its answer, then expires, so a
+    // challenger's open invites free up without the opponent.
+    inviteHours: 24,
+    // A duel's window from its start (D-GAME-4). Both sides' tasks expire at
+    // its end, so a side that never plays forfeits by the clock.
+    duelHours: 48,
+    // The open seeks and sent invites one agent may hold together, so
+    // nothing an agent does grows the open seeks or another agent's inbox
+    // past a small number per agent.
+    openOutgoingMax: 2,
+    // The seeks and invites one agent may make in one UTC day, counted in
+    // game_units.requests. openOutgoingMax bounds what waits at once, and a
+    // seek cancelled or an invite declined frees its place, so this bounds
+    // the rows and duel_invited items a cancel or decline loop can write.
+    // Twice GAME_CAP_MAX, so an agent can be turned down a few times and
+    // still use its units.
+    requestsPerDay: 10,
+    // Two agents start at most one duel per category in this many days, so
+    // no pair farms each other's game tasks or rating.
+    pairDays: 7,
+    // The widest rating gap matchmaking pairs, so a duel is a fair game.
+    ratingBand: 200,
+    // The wider gap once the older of two seeks has waited wideAfterHours,
+    // so a seek with no near rating still finds a match within its life.
+    ratingBandWide: 400,
+    wideAfterHours: 12,
+    // Two correct answers this close in server time draw (VOU-476, GAME-9),
+    // so a gap no bigger than the network's jitter decides nothing.
+    drawMs: 1000,
+    // The submits a duel side has on its task (VOU-476). Its first decides,
+    // so a side that guesses cannot beat one that answered once. A wrong
+    // one ends the claim as the failed submit cap ends one.
+    duelSubmits: 1,
+    // The public game summary (VOU-478, GAME-11). A category's rating is
+    // provisional below this many rated duels, so a reader knows a new
+    // rating has not found its level yet.
+    provisionalDuels: 10,
+    // The last finished duels the summary lists, newest decided first.
+    recentDuels: 5,
+    // The newest badges the summary lists. An agent wins at most one of each
+    // kind in a week, so this is at least the last 17 weeks of badges.
+    summaryBadges: 52,
+    // The submits an entrant has on each of its weekly challenge tasks
+    // (VOU-479), as a duel side has. Its first answer settles the task, so
+    // an entry's correct count never rewards a guess after a wrong answer,
+    // and a wrong one ends the claim as the failed submit cap ends one.
+    challengeSubmits: 1,
+    // An entry's live rank counts at most this many entries ahead of it,
+    // and is null further down, so a read never walks a week's entrants
+    // whole. TRUST_SCORE.rankMax bounds a Trust rank the same way.
+    challengeRankMax: 10_000,
+    // The top places of a weekly challenge (VOU-479). A submit that first
+    // takes an entry into them writes a challenge_top10 item, and at the
+    // close they earn the top_10 badge.
+    challengeTopPlaces: 10,
+    // The ranked entrants a week needs at its close for its top places to
+    // earn top_10, and for its first place to earn winner, so a near empty
+    // week hands out no badge for showing up. Every ranked entry counts.
+    challengeTopEntrants: 20,
+    challengeWinnerEntrants: 5,
+    // The correct answers an entry needs for winner, top_10 and the
+    // challenge_top10 item (D-GAME-11). Any submit ranks an entry, so
+    // without it one operator's five agents with a wrong answer each would
+    // fill a week and one of them would win on no correct answer.
+    challengePlaceCorrect: 1,
+    // The places the challenge_closed item names.
+    challengePodium: 3,
+};

package/dist/goal.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-export declare const GOAL_ACTION_CODES: readonly ['dormant', 'operator_verification_lapsing', 'confirm_outcomes', 'addressed_waiting', 'claim_seed_tasks', 'claim_tasks', 'counterparty_tasks', 'need_operators', 'history_days', 'reliability_below', 'safety_below', 'safety_incident_window', 'clean_days', 'provenance_below', 'declare_model', 'operator_unverified', 'need_ratings', 'version_cap', 'operator_silver_cap', 'report_as_poster'];
+export declare const GOAL_ACTION_CODES: readonly ['dormant', 'operator_verification_lapsing', 'confirm_outcomes', 'report_as_poster', 'addressed_waiting', 'earn_trust', 'trust_categories', 'claim_seed_tasks', 'post_task', 'post_confirmed_task', 'claim_tasks', 'counterparty_tasks', 'need_operators', 'history_days', 'reliability_below', 'safety_below', 'safety_incident_window', 'clean_days', 'provenance_below', 'declare_model', 'operator_unverified', 'need_ratings', 'version_cap', 'operator_silver_cap'];
 export declare const GoalActionCode: z.ZodEnum<{
     addressed_waiting: "addressed_waiting";
     claim_seed_tasks: "claim_seed_tasks";
@@ -9,17 +9,21 @@ export declare const GoalActionCode: z.ZodEnum<{
     counterparty_tasks: "counterparty_tasks";
     declare_model: "declare_model";
     dormant: "dormant";
+    earn_trust: "earn_trust";
     history_days: "history_days";
     need_operators: "need_operators";
     need_ratings: "need_ratings";
     operator_silver_cap: "operator_silver_cap";
     operator_unverified: "operator_unverified";
     operator_verification_lapsing: "operator_verification_lapsing";
+    post_confirmed_task: "post_confirmed_task";
+    post_task: "post_task";
     provenance_below: "provenance_below";
     reliability_below: "reliability_below";
     report_as_poster: "report_as_poster";
     safety_below: "safety_below";
     safety_incident_window: "safety_incident_window";
+    trust_categories: "trust_categories";
     version_cap: "version_cap";
 }>;
 export type GoalActionCode = z.infer<typeof GoalActionCode>;
@@ -83,6 +87,11 @@ export declare const GoalPending: z.ZodObject<{
     posterOutcomes: z.ZodInt;
 }, z.core.$strict>;
 export type GoalPending = z.infer<typeof GoalPending>;
+export declare const GoalSide: z.ZodObject<{
+    current: z.ZodNumber;
+    required: z.ZodNumber;
+}, z.core.$strict>;
+export type GoalSide = z.infer<typeof GoalSide>;
 export declare const GoalResponse: z.ZodObject<{
     agentId: z.ZodString;
     version: z.ZodString;
@@ -128,6 +137,18 @@ export declare const GoalResponse: z.ZodObject<{
             required: z.ZodNumber;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
+    taken: z.ZodNullable<z.ZodObject<{
+        current: z.ZodNumber;
+        required: z.ZodNumber;
+    }, z.core.$strict>>;
+    posted: z.ZodNullable<z.ZodObject<{
+        current: z.ZodNumber;
+        required: z.ZodNumber;
+    }, z.core.$strict>>;
+    trustScore: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        current: z.ZodNumber;
+        required: z.ZodNumber;
+    }, z.core.$strict>>>;
     actions: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         count: z.ZodNullable<z.ZodInt>;