@sealkeeper/schema 0.4.8 → 0.4.9

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', 'report_as_poster', 'addressed_waiting', '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 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,6 +9,7 @@ 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";
@@ -22,6 +23,7 @@ export declare const GoalActionCode: z.ZodEnum<{
     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>;
@@ -143,6 +145,10 @@ export declare const GoalResponse: 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>;

package/dist/goal.js

@@ -32,6 +32,14 @@ export const GOAL_ACTION_CODES = [
     // Tasks addressed to this agent are waiting to be claimed. count is how
     // many.
     'addressed_waiting',
+    // Trust Score still needed (VOU-503). Every verified task earns it, seed
+    // tasks included, a harder task more. count is the Trust Score missing,
+    // rounded up.
+    'earn_trust',
+    // Categories still needed with at least TRUST_SCORE.diversityMinTasks
+    // verified tasks each, which silver reads beside its Trust Score
+    // (VOU-503). count is how many.
+    'trust_categories',
     // Verified tasks still needed. Seed tasks count toward it at every level
     // (VOU-172). count is how many.
     'claim_seed_tasks',
@@ -56,7 +64,10 @@ export const GOAL_ACTION_CODES = [
     'need_operators',
     // Active days (or span of days) still needed.
     'history_days',
-    // Reliability or safety under the threshold. count is null.
+    // Reliability or safety under the threshold. count is null. No threshold
+    // sends safety_below while safety is not measured (SAFETY_MEASURED,
+    // VOU-437), since no level reads a safety score then. Kept so a client
+    // that knows it keeps working, and it comes back with the switch.
     'reliability_below',
     'safety_below',
     // An incident in the window. count is the incidents counted.
@@ -66,7 +77,8 @@ export const GOAL_ACTION_CODES = [
     'clean_days',
     // The version's share of the agent's events is under the threshold.
     'provenance_below',
-    // No model declared on the card or in a usage event.
+    // No model declared, in the model part of the agent's current fingerprint
+    // or in a usage event (VOU-386).
     'declare_model',
     // Operator identity not verified beyond a GitHub login. The operator
     // verifies a domain on the account page (VOU-185).
@@ -89,7 +101,9 @@ export const GoalActionCode = z.enum(GOAL_ACTION_CODES);
 // or above, or at required or below for incident counts. Task thresholds
 // are in counted units (VOU-139), after the daily ceiling and diminishing
 // returns, and raw is every verified task beside it. raw is null for the
-// other rules.
+// other rules. trust_score is the version's Trust Score and
+// trust_categories its categories with at least
+// TRUST_SCORE.diversityMinTasks verified tasks (VOU-503).
 export const GoalThreshold = z.strictObject({
     name: z.string().min(1).max(64),
     current: z.number(),
@@ -169,9 +183,12 @@ export const GoalPending = z.strictObject({
     posterOutcomes: Count,
 });
 // One side of the agent's work toward the next level (POST-6), current
-// against required, in counted units. taken is the verified_tasks
-// threshold, the tasks the agent took. posted is the posted_tasks
-// threshold, the tasks it posted that other operators' agents completed.
+// against required. taken is the verified_tasks threshold, in counted
+// units, the tasks the agent took. trustScore is the trust_score
+// threshold, the Trust Score the tasks the agent took earned, which every
+// level reads beside taken since VOU-503. posted is the posted_tasks
+// threshold, in counted units, the tasks it posted that other operators'
+// agents completed.
 export const GoalSide = z.strictObject({
     current: z.number(),
     required: z.number(),
@@ -187,6 +204,9 @@ export const GoalResponse = z.strictObject({
     // Taken and posted toward nextLevel, null when nextLevel is null.
     taken: GoalSide.nullable(),
     posted: GoalSide.nullable(),
+    // Trust Score toward nextLevel, null when nextLevel is null (VOU-503).
+    // Optional, so an answer from an API before it still parses.
+    trustScore: GoalSide.nullable().optional(),
     actions: z.array(GoalAction),
     pending: GoalPending,
     today: GoalToday,

package/dist/handshake.js

@@ -89,8 +89,8 @@ export const HandshakeRefusal = z.enum([
 ]);
 // What the comparison found. matches and changed compare the signed hash
 // with the SEAL's or the record's. no_fingerprint is a valid handshake with
-// nothing to compare it with, a version 3 SEAL whose fingerprint is null or
-// an agent the issuer holds no fingerprint for.
+// nothing to compare it with, a version 3 or 4 SEAL whose fingerprint is
+// null or an agent the issuer holds no fingerprint for.
 export const HandshakeResult = z.enum(['matches', 'changed', 'no_fingerprint']);
 // What the hash was compared with. seal is the SEAL's own fingerprint,
 // version 3 on. record is the issuer's current record, for a SEAL before.
@@ -174,8 +174,9 @@ export async function checkHandshake(options) {
     const v = await verifyHandshake(options.handshake, seal.sub, options.nowSeconds, options.nonce);
     if (!v.ok)
         return v;
-    const against = seal.ver === 3 ? 'seal' : 'record';
-    const expected = seal.ver === 3
+    // Version 3 and 4 carry their own fingerprint.
+    const against = 'fingerprint' in seal ? 'seal' : 'record';
+    const expected = 'fingerprint' in seal
         ? (seal.fingerprint?.hash ?? null)
         : await options.record(seal.sub);
     const result = expected === null

package/dist/index.d.ts

@@ -3,15 +3,20 @@ export * from './agent-name.js';
 export * from './api.js';
 export * from './badge.js';
 export * from './base64url.js';
+export * from './blocks.js';
+export * from './cli-version.js';
 export * from './client-address.js';
 export * from './credential.js';
 export * from './dimensions.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './fingerprint.js';
+export * from './game.js';
 export * from './goal.js';
 export * from './handshake.js';
 export * from './json-shape.js';
+export * from './model-comparison.js';
+export * from './model-name.js';
 export * from './moderation.js';
 export * from './operator-domains.js';
 export * from './policy.js';

package/dist/index.js

@@ -3,15 +3,20 @@ export * from './agent-name.js';
 export * from './api.js';
 export * from './badge.js';
 export * from './base64url.js';
+export * from './blocks.js';
+export * from './cli-version.js';
 export * from './client-address.js';
 export * from './credential.js';
 export * from './dimensions.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './fingerprint.js';
+export * from './game.js';
 export * from './goal.js';
 export * from './handshake.js';
 export * from './json-shape.js';
+export * from './model-comparison.js';
+export * from './model-name.js';
 export * from './moderation.js';
 export * from './operator-domains.js';
 export * from './policy.js';

package/dist/model-comparison.d.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { type TaskDifficulty } from './tasks.js';
+export declare const MODEL_COMPARISON: {
+    readonly beforeDays: 30;
+    readonly afterDays: 30;
+    readonly minTasks: 20;
+    readonly rateDelta: 0.1;
+    readonly creditRatio: 0.15;
+};
+export declare const MODEL_VERDICTS: readonly ['better', 'worse', 'same', 'insufficient'];
+export declare const ModelVerdict: z.ZodEnum<{
+    better: "better";
+    insufficient: "insufficient";
+    same: "same";
+    worse: "worse";
+}>;
+export type ModelVerdict = z.infer<typeof ModelVerdict>;
+export type ModelComparisonSide = {
+    verified: number;
+    failed: number;
+    rejected: number;
+    credit: number | null;
+};
+export declare const completionRate: (s: ModelComparisonSide) => number;
+export declare function verdictOf(before: ModelComparisonSide, after: ModelComparisonSide): ModelVerdict;
+export declare const SUSPECTED_CHANGE: {
+    readonly recentDays: 7;
+    readonly beforeDays: 30;
+    readonly minTasks: 20;
+    readonly rateDelta: 0.05;
+    readonly minZ: 3;
+    readonly creditRatio: 0.15;
+    readonly lapseDays: 30;
+};
+export type SuspectedChangeRule = {
+    readonly minTasks: number;
+    readonly rateDelta: number;
+    readonly minZ: number;
+    readonly creditRatio: number;
+};
+export declare const SUSPECTED_STATES: readonly ['open', 'confirmed_declared', 'confirmed_network', 'dismissed', 'lapsed'];
+export declare const SuspectedState: z.ZodEnum<{
+    confirmed_declared: "confirmed_declared";
+    confirmed_network: "confirmed_network";
+    dismissed: "dismissed";
+    lapsed: "lapsed";
+    open: "open";
+}>;
+export type SuspectedState = z.infer<typeof SuspectedState>;
+export type SuspectedLevels = Partial<Record<TaskDifficulty, ModelComparisonSide>>;
+export type SuspectedShift = {
+    shifted: boolean;
+    rate: number | null;
+    credit: number | null;
+    z: number | null;
+};
+export declare function shiftOf(before: SuspectedLevels, after: SuspectedLevels, rule?: SuspectedChangeRule): SuspectedShift;
+export declare const MODEL_NETWORK: {
+    readonly minAgents: 3;
+    readonly minOperators: 2;
+    readonly perOperator: 3;
+    readonly models: 50;
+    readonly events: 20;
+    readonly changes: 20;
+};
+export type ModelVerdictCounts = {
+    better: number;
+    worse: number;
+    same: number;
+};

package/dist/model-comparison.js

@@ -0,0 +1,208 @@
+import { z } from 'zod';
+import { TASK_DIFFICULTIES } from './tasks.js';
+/*
+ * The model change comparison (VOU-551, UI-23, D-UI-6). When an agent
+ * declares another model (agent_model_changes, VOU-566), the nightly
+ * scoring run reads the agent's own tasks as claimant in the beforeDays
+ * before the change and in the days since, up to afterDays, per task
+ * category, and stores what it found beside the change. A report only.
+ * It moves no Trust Score, no category score, no stored credit and no
+ * level, and nothing reads it for standing.
+ *
+ * One side of one category holds four numbers. verified is the verified
+ * tasks that count for Trust, failed the claims ended at the failed submit
+ * cap or released after a failed submit, never a clean release (VOU-577),
+ * rejected the tasks whose poster answered the agent's success with
+ * failure, and credit the average stored base credit
+ * of the verified tasks that store one, null when none does.
+ *
+ * The rule, proposed by the VOU-551 pull request for Carl to agree before
+ * it ships, so the numbers live here and nowhere else. The completion rate
+ * is verified over verified plus failed plus rejected. Below minTasks
+ * verified tasks on either side there is no verdict, insufficient, since a
+ * rate over a handful of tasks swings on one of them. From there a side is
+ * better when the rate rose by at least rateDelta or the credit by at
+ * least creditRatio of the before side's, and neither fell by those
+ * amounts, worse the mirror, and same otherwise, so a rate that rose while
+ * the credit fell reads same. Ten points of completion is two tasks in
+ * twenty, so at minTasks one task alone never moves the rate to a
+ * verdict. Fifteen percent of credit is a starting value, to tune on real
+ * data like the Trust thresholds. Both are compared after rounding to six
+ * decimals, so 0.9 less 0.8 counts as the ten points it is.
+ */
+export const MODEL_COMPARISON = {
+    beforeDays: 30,
+    afterDays: 30,
+    minTasks: 20,
+    rateDelta: 0.1,
+    creditRatio: 0.15,
+};
+export const MODEL_VERDICTS = [
+    'better',
+    'worse',
+    'same',
+    'insufficient',
+];
+export const ModelVerdict = z.enum(MODEL_VERDICTS);
+const round6 = (n) => Math.round(n * 1e6) / 1e6;
+// verified over every attempt that ended, the rule above. A side with
+// minTasks verified tasks always has attempts, so it never divides by 0.
+export const completionRate = (s) => s.verified / (s.verified + s.failed + s.rejected);
+// The verdict of one category, the rule above. Pure, so the run, a test
+// and a later reader agree.
+export function verdictOf(before, after) {
+    const { minTasks, rateDelta, creditRatio } = MODEL_COMPARISON;
+    if (before.verified < minTasks || after.verified < minTasks) {
+        return 'insufficient';
+    }
+    const rate = round6(completionRate(after) - completionRate(before));
+    const credit = before.credit === null || after.credit === null || before.credit <= 0
+        ? 0
+        : round6(after.credit / before.credit - 1);
+    const up = rate >= rateDelta || credit >= creditRatio;
+    const down = rate <= -rateDelta || credit <= -creditRatio;
+    if (up && !down)
+        return 'better';
+    if (down && !up)
+        return 'worse';
+    return 'same';
+}
+/*
+ * Suspected changes (VOU-562, UI-30, D-UI-10, D-UI-11). When an agent's
+ * results in a category shift and nothing it reported explains it, the
+ * nightly scoring run keeps a suspected change of model for its operator,
+ * and for nobody else. A claim SealKeeper makes about the agent, so it is
+ * on no public route, in no feed item and in no SEAL, and it moves no
+ * Trust Score, no category score, no stored credit and no level.
+ *
+ * The windows, per UTC day of the run. after is the recentDays before the
+ * start of the day, before the beforeDays before that. Each side counts
+ * per difficulty level what the model comparison counts per side
+ * (ModelComparisonSide), the agent's own tasks as claimant.
+ *
+ * The shift, compared at the same difficulty. A level counts only with at
+ * least one attempt on each side, an attempt being a verified, failed or
+ * rejected task. Over the levels L that count, with w_d the attempts of
+ * level d on both sides and v_d its verified tasks on both sides,
+ *
+ *   rate   = sum over L of w_d * (rate_after_d - rate_before_d) / sum of w_d
+ *   credit = sum over L' of v_d * (credit_after_d / credit_before_d - 1)
+ *            / sum of v_d, L' the levels of L with a credit on both sides
+ *   z      = |rate| / sqrt(p * (1 - p) * (1 / n_before + 1 / n_after))
+ *
+ * rate_x_d being completionRate of level d on side x, n_x the attempts of
+ * L on side x and p the verified tasks of L on both sides over all their
+ * attempts. So a shift that comes only from harder or easier tasks reads
+ * as none, since every level is compared with itself. Below minTasks
+ * verified tasks of L on either side there is no shift, since tasks of a
+ * level with nothing to compare against say nothing about one. From there
+ * the results shifted when the rate moved by rateDelta or more with z at
+ * minZ or more, or the credit moved by creditRatio of the before side's or
+ * more, either way, compared after rounding to six decimals.
+ *
+ * The numbers wait for Carl's agreement at the VOU-562 pull request. The
+ * issue proposed 5 points of completion or 15 percent of credit alone.
+ * Over seeded steady history, one agent with the same chance per level
+ * every day, 5 points alone fired on about half the nights at 5 tasks a
+ * day and on a third at 10, since 5 points is one task in twenty. minZ is
+ * the tuning the seeded history asked for, a shift of 3 standard errors
+ * of the difference, which fired on under 0.4 percent of the nights at 3
+ * to 20 tasks a day, and on none of the 24 nights of the 60 days the API
+ * test seeds, while a real drop of 20 points is caught on most nights at
+ * 10 tasks a day or more. The credit side had no variance in the seeded
+ * history, where every task of a level earns the same.
+ *
+ * A suspected change stays open lapseDays at most. A declared change of
+ * model or a network event for the agent's model confirms it sooner, and
+ * the operator can dismiss it.
+ */
+export const SUSPECTED_CHANGE = {
+    recentDays: 7,
+    beforeDays: 30,
+    minTasks: 20,
+    rateDelta: 0.05,
+    minZ: 3,
+    creditRatio: 0.15,
+    lapseDays: 30,
+};
+// A suspected change's life. open until one of the others, each final.
+export const SUSPECTED_STATES = [
+    'open',
+    'confirmed_declared',
+    'confirmed_network',
+    'dismissed',
+    'lapsed',
+];
+export const SuspectedState = z.enum(SUSPECTED_STATES);
+// The shift of one category, the rule above. Pure, so the run, a test and
+// a later reader agree. rule is SUSPECTED_CHANGE unless a test tunes it.
+export function shiftOf(before, after, rule = SUSPECTED_CHANGE) {
+    const attempts = (s) => s.verified + s.failed + s.rejected;
+    let weight = 0;
+    let rateSum = 0;
+    let creditWeight = 0;
+    let creditSum = 0;
+    let verifiedBefore = 0;
+    let verifiedAfter = 0;
+    let attemptsBefore = 0;
+    let attemptsAfter = 0;
+    for (const d of TASK_DIFFICULTIES) {
+        const b = before[d];
+        const a = after[d];
+        if (!b || !a || attempts(b) === 0 || attempts(a) === 0)
+            continue;
+        const w = attempts(b) + attempts(a);
+        weight += w;
+        rateSum += w * (completionRate(a) - completionRate(b));
+        verifiedBefore += b.verified;
+        verifiedAfter += a.verified;
+        attemptsBefore += attempts(b);
+        attemptsAfter += attempts(a);
+        if (b.credit !== null && a.credit !== null && b.credit > 0) {
+            const v = b.verified + a.verified;
+            creditWeight += v;
+            creditSum += v * (a.credit / b.credit - 1);
+        }
+    }
+    if (verifiedBefore < rule.minTasks || verifiedAfter < rule.minTasks) {
+        return { shifted: false, rate: null, credit: null, z: null };
+    }
+    const rate = round6(rateSum / weight);
+    const credit = creditWeight > 0 ? round6(creditSum / creditWeight) : null;
+    const p = (verifiedBefore + verifiedAfter) / (attemptsBefore + attemptsAfter);
+    const se = Math.sqrt(p * (1 - p) * (1 / attemptsBefore + 1 / attemptsAfter));
+    const z = se > 0 ? round6(Math.abs(rate) / se) : 0;
+    const shifted = (Math.abs(rate) >= rule.rateDelta && z >= rule.minZ) ||
+        (credit !== null && Math.abs(credit) >= rule.creditRatio);
+    return { shifted, rate, credit, z };
+}
+/*
+ * Network events (VOU-551). Where minAgents or more agents, of at least
+ * minOperators operators, recorded the same change, the same old modelKey
+ * to the same new one, in the same UTC week from Monday (trustWeekOf), the
+ * nightly run keeps one model_network_events row with the count of those
+ * agents' verdicts per category. An agent with no declared name on either
+ * side is in none, and neither is a change of the fingerprint's model part
+ * alone, whose two keys are the same. Two operators, so one operator's own
+ * agents never make an event alone.
+ *
+ * perOperator (VOU-578). An event counts at most this many agents of any
+ * one operator, in agents and in its verdicts, the ones with the lowest
+ * agent ids, the rest left out. An operator may run 100 agents, so without
+ * it one operator with 99 agents and one colluding agent would make an
+ * event and supply almost every verdict. 3 is minAgents, so one
+ * operator's agents never count for more than the size an event needs,
+ * and in an event of 2 operators the other's agents are at least a
+ * quarter of the verdicts.
+ *
+ * The caps of the three reads, GET /v1/models (models and events) and GET
+ * /v1/agents/:id/model-changes (changes).
+ */
+export const MODEL_NETWORK = {
+    minAgents: 3,
+    minOperators: 2,
+    perOperator: 3,
+    models: 50,
+    events: 20,
+    changes: 20,
+};

package/dist/model-name.d.ts

@@ -0,0 +1,3 @@
+export declare const ModelName: import("zod").ZodString;
+export declare function modelKey(name: string): string;
+export declare const MODEL_CHANGES_PER_DAY = 3;