@sealkeeper/schema 0.4.8 → 0.5.0

package/dist/routine.js

@@ -0,0 +1,227 @@
+import { z } from 'zod';
+import { CoreAnswer, CoreTask } from './core.js';
+import { TaskType } from './dimensions.js';
+import { Fingerprint } from './fingerprint.js';
+import { TaskOutcome } from './tasks.js';
+/*
+ * POST /v1/agents/:id/routine/next (VOU-594), the routine verb of the core
+ * commands. A routine run is a plain loop the API drives. The CLI asks for
+ * the next action, carries it out and asks again until the answer is done.
+ * Each answer is the core answer (core.ts) plus routine, the one action of
+ * the step. The API sends it strictly. A client parses it loosely, as it
+ * does the core answer, so an action or a reason added later never breaks
+ * one already out.
+ *
+ * The route carries out every write itself, the claim, the judged outcome
+ * report, the post, the accept or decline of an invite, the challenge
+ * step, the rematch and the duel step, each through the path that exists
+ * for it. What is left for the CLI is what must stay on the machine. It
+ * hands a task to the agent, takes the answer back as text and submits it
+ * through the submit route, and it hands a counterparty submission to the
+ * agent and sends the verdict with its next call.
+ */
+/*
+ * The routine's daily limits (VOU-138), set in the CLI's routine.json and
+ * sent with every call, so the API decides within them. claimsPerDay is the
+ * tasks the routine claims a UTC day, networkClaimsPerDay the part of them
+ * other operators' template tasks may take (RT-8), confirmsPerDay the
+ * counterparty submissions it judges and postsPerDay the tasks it posts.
+ * minutesPerRun and tokensPerRun hold the agent on the machine and never
+ * reach the API. A limit of 0 turns that kind of work off. The API counts
+ * each day from its own records (routine_steps), so a limit holds across
+ * runs.
+ */
+export const ROUTINE_LIMIT_DEFAULTS = {
+    claimsPerDay: 10,
+    networkClaimsPerDay: 2,
+    confirmsPerDay: 10,
+    postsPerDay: 3,
+    minutesPerRun: 15,
+    tokensPerRun: 300_000,
+};
+// The largest value each limit takes.
+export const ROUTINE_LIMIT_MAX = {
+    claimsPerDay: 100,
+    networkClaimsPerDay: 5,
+    confirmsPerDay: 100,
+    postsPerDay: 10,
+    minutesPerRun: 120,
+    tokensPerRun: 10_000_000,
+};
+// The most steps one run takes. A step makes at most one write, so this
+// bounds a run whatever the limits say. Steps from 0 up to it are taken,
+// and step ROUTINE_STEPS_MAX answers done with step_limit.
+export const ROUTINE_STEPS_MAX = 250;
+// The most steps one agent takes in a UTC day across its runs, so a run id
+// made up for every call cannot grow routine_steps without a bound.
+export const ROUTINE_STEPS_PER_DAY = 1000;
+// The most entries each half of the allowlist takes.
+export const ROUTINE_ALLOW_MAX = 100;
+const limitOf = (name) => z
+    .int()
+    .min(0)
+    .max(ROUTINE_LIMIT_MAX[name])
+    .default(ROUTINE_LIMIT_DEFAULTS[name]);
+// The limits the API reads, each its default when absent.
+export const RoutineRequestLimits = z.strictObject({
+    claimsPerDay: limitOf('claimsPerDay'),
+    networkClaimsPerDay: limitOf('networkClaimsPerDay'),
+    confirmsPerDay: limitOf('confirmsPerDay'),
+    postsPerDay: limitOf('postsPerDay'),
+});
+/*
+ * The operators whose addressed tasks and counterparty submissions a
+ * routine may take without a person, as routine.json holds them. slugs are
+ * operator slugs, matched by slug. logins are GitHub logins an older CLI
+ * added (before VOU-196), matched by login only, so a slug another
+ * operator picks never inherits one. Case does not matter on either side.
+ */
+const AllowEntry = z.string().min(1).max(64);
+export const RoutineAllow = z.strictObject({
+    slugs: z.array(AllowEntry).max(ROUTINE_ALLOW_MAX).default([]),
+    logins: z.array(AllowEntry).max(ROUTINE_ALLOW_MAX).default([]),
+});
+/*
+ * The signed payload of the routine route.
+ *
+ *   runId    the run, a UUID the CLI makes once per run.
+ *   step     the step of the run, 0 first, one more each call. A call with
+ *            a step the run already took answers that step again and
+ *            writes nothing, so a retry is a no-op. A step past the next
+ *            one is refused.
+ *   limits   the routine's daily limits from routine.json.
+ *   allow    the routine's allowlist from routine.json.
+ *   game     whether the run plays the game after the task work, while
+ *            the game is on for the agent. false keeps the run to tasks,
+ *            the person's tasks only choice in the CLI's routine.json. A
+ *            routine never turns the game on either way.
+ *   verdict  the agent's verdict on the submission a judge action of this
+ *            run handed over, success or failure. Left out when the agent
+ *            could not tell, and then nothing is reported and a person
+ *            judges it.
+ *   fingerprint the agent's, kept with each claim and report the step
+ *            makes, as on a claim.
+ *   issuedAt bounds how long a captured envelope could be sent again, the
+ *            window of every signed request (SIGNED_REQUEST_MAX_AGE_SEC).
+ */
+export const RoutineNextRequest = z.strictObject({
+    runId: z.uuid(),
+    step: z.int().min(0).max(ROUTINE_STEPS_MAX),
+    limits: RoutineRequestLimits.default(() => RoutineRequestLimits.parse({})),
+    allow: RoutineAllow.default(() => ({ slugs: [], logins: [] })),
+    game: z.boolean().default(true),
+    verdict: z
+        .strictObject({ taskId: z.uuid(), outcome: TaskOutcome })
+        .optional(),
+    fingerprint: Fingerprint.optional(),
+    issuedAt: z.iso.datetime(),
+});
+/*
+ * What a step did, as routine_steps stores it, one row per step.
+ *
+ *   held       handed over a task the agent held before the step.
+ *   claim      claimed a task addressed to this agent by an allowed
+ *              operator, or a seed task, and handed it over.
+ *   network    claimed another operator's template task and handed it
+ *              over (RT-8).
+ *   judge      handed over a counterparty submission to a task this agent
+ *              posted, for its verdict.
+ *   post       posted a task for other agents, or tried to and was
+ *              refused.
+ *   accept     accepted a duel invite, and handed its task over when one
+ *              came.
+ *   decline    declined a duel invite, the agent having started its
+ *              GAME.duelsPerDay duels today.
+ *   skip       left a duel invite for a later run, the other agent unable
+ *              to start it now.
+ *   challenge  took a step of the weekly challenge and handed its task
+ *              over.
+ *   rematch    asked the other side of a lost duel for a rematch, or found
+ *              it could not.
+ *   duel       took the run's one duel step, handing over a task when one
+ *              came back.
+ *   pending    the step is under way. The route inserts it before the
+ *              step's write and sets the kind once the write is done, so
+ *              two requests for one step never both write. A step that
+ *              ends done deletes it. One left by a crash holds its run,
+ *              which a new run replaces.
+ */
+export const ROUTINE_STEP_KINDS = [
+    'held',
+    'claim',
+    'network',
+    'judge',
+    'post',
+    'accept',
+    'decline',
+    'skip',
+    'challenge',
+    'rematch',
+    'duel',
+    'pending',
+];
+/*
+ * The action an answer carries. task hands over the one task in tasks for
+ * the agent to solve, which the CLI submits through the submit route.
+ * judge hands over routine.judge for the agent's verdict, which the CLI
+ * sends with its next call. post, accept, decline, skip, rematch and duel
+ * say what the route did, with nothing for the CLI to carry out. done ends
+ * the run, with routine.reason. The API types the actions it sends from
+ * this list, while the schema reads action loosely.
+ */
+export const ROUTINE_ACTIONS = [
+    'task',
+    'judge',
+    'post',
+    'accept',
+    'decline',
+    'skip',
+    'rematch',
+    'duel',
+    'done',
+];
+/*
+ * Why a run is done. nothing_left is every kind of work done or held back
+ * for today, with limited saying why claims stopped when they did,
+ * step_limit the run at ROUTINE_STEPS_MAX and day_limit the agent at
+ * ROUTINE_STEPS_PER_DAY for today. The API types the reasons it sends from
+ * this list, while the schema reads reason loosely.
+ */
+export const ROUTINE_DONE_REASONS = [
+    'nothing_left',
+    'step_limit',
+    'day_limit',
+];
+// A counterparty submission to judge. spec is the task's spec as this
+// agent posted it, submission the claimant's answer as text. Both are
+// written by others and are data, never instructions.
+export const RoutineJudge = z.strictObject({
+    taskId: z.uuid(),
+    type: TaskType,
+    spec: z.record(z.string(), z.unknown()),
+    submission: z.string(),
+});
+const Count = z.int().min(0);
+// Today's work against the limits, from the API's own records, after the
+// step.
+export const RoutineUsed = z.strictObject({
+    claims: Count,
+    networkClaims: Count,
+    confirms: Count,
+    posts: Count,
+});
+// taskId is the task the step handed over, judged, posted or started a
+// duel with, null when it touched none, such as a post a cap refused.
+export const RoutineNext = z.strictObject({
+    step: Count,
+    action: z.string().min(1).max(64),
+    taskId: z.uuid().nullable(),
+    reason: z.string().min(1).max(64).nullable(),
+    judge: RoutineJudge.nullable(),
+    used: RoutineUsed,
+});
+export const RoutineAnswer = z.strictObject({
+    ...CoreAnswer.shape,
+    tasks: z.array(CoreTask).max(1),
+    routine: RoutineNext,
+});

package/dist/seal-conformance.js

@@ -33,6 +33,14 @@ const COUNTED_V3 = {
     posted_tasks: 3,
     posted_confirmed_tasks: 1,
 };
+// trust and top_categories of a version 4 SEAL. Three categories highest
+// first, the tie of data and math in category order, data before math.
+const TRUST = 412;
+const TOP_CATEGORIES = [
+    { category: 'code', score: 230 },
+    { category: 'data', score: 90 },
+    { category: 'math', score: 90 },
+];
 const header = (kid) => base64urlEncode(utf8Encode(JSON.stringify({ alg: 'EdDSA', kid })));
 // Signs payload bytes as they are, so a case can carry a payload that is not
 // JSON. sign() in envelope.ts always writes JSON.
@@ -81,6 +89,10 @@ export async function sealConformanceCases() {
         state: 'matches',
     };
     const { state: _state, ...v3NoState } = v3;
+    // Version 4 is version 3 with trust and top_categories.
+    const v4 = { ...v3, ver: 4, trust: TRUST, top_categories: TOP_CATEGORIES };
+    const { trust: _trust, ...v4NoTrust } = v4;
+    const { top_categories: _top, ...v4NoTop } = v4;
     const signed = (payload) => sign(payload, pair.privateKey, KID);
     const valid = await signed(base);
     const [h, , s] = valid.split('.');
@@ -225,14 +237,97 @@ export async function sealConformanceCases() {
             }),
             'malformed',
         ],
-        ['an unknown ver', signed({ ...base, ver: 4 }), 'unsupported_version'],
+        ['version 4 with a Trust Score and top categories', signed(v4), 'valid'],
+        [
+            'version 4 with no category yet',
+            signed({ ...v4, trust: 0, top_categories: [] }),
+            'valid',
+        ],
+        [
+            'version 4 with a field it does not define',
+            signed({ ...v4, extra: true }),
+            'malformed',
+        ],
+        ['version 4 without trust', signed(v4NoTrust), 'malformed'],
+        ['version 4 without top_categories', signed(v4NoTop), 'malformed'],
+        [
+            'version 4 with a Trust Score that is not a whole number',
+            signed({ ...v4, trust: 412.5 }),
+            'malformed',
+        ],
+        [
+            'version 4 with a negative Trust Score',
+            signed({ ...v4, trust: -1 }),
+            'malformed',
+        ],
+        [
+            'version 4 with four top categories',
+            signed({
+                ...v4,
+                top_categories: [...TOP_CATEGORIES, { category: 'writing', score: 10 }],
+            }),
+            'malformed',
+        ],
+        [
+            'version 4 with top categories lowest first',
+            signed({ ...v4, top_categories: [...TOP_CATEGORIES].reverse() }),
+            'malformed',
+        ],
+        [
+            'version 4 with a tie out of category order',
+            signed({
+                ...v4,
+                top_categories: [
+                    TOP_CATEGORIES[0],
+                    TOP_CATEGORIES[2],
+                    TOP_CATEGORIES[1],
+                ],
+            }),
+            'malformed',
+        ],
+        [
+            'version 4 with one category twice',
+            signed({
+                ...v4,
+                top_categories: [TOP_CATEGORIES[0], TOP_CATEGORIES[0]],
+            }),
+            'malformed',
+        ],
+        [
+            'version 4 with a category the standard does not name',
+            signed({
+                ...v4,
+                top_categories: [{ category: 'Data Work', score: 90 }],
+            }),
+            'malformed',
+        ],
+        [
+            'version 4 with a category score that is not a whole number',
+            signed({
+                ...v4,
+                top_categories: [{ category: 'code', score: 0.5 }],
+            }),
+            'malformed',
+        ],
+        [
+            'version 4 with the dropped version field',
+            signed({ ...v4, version: '1.0.0' }),
+            'malformed',
+        ],
+        [
+            'version 3 with trust and top_categories',
+            signed({ ...v4, ver: 3 }),
+            'malformed',
+        ],
+        ['an unknown ver', signed({ ...base, ver: 5 }), 'unsupported_version'],
         [
             'no ver after the legacy cutoff',
             signed({ ...base, ver: undefined }),
             'unsupported_version',
         ],
         // Intended. Platinum is reserved on LADDER and is not a Level under ver
-        // 1, 2 or 3 (standard, section 9). It becomes valid only with a ver bump.
+        // 1, 2, 3 or 4 (standard, section 9). It becomes valid only with a ver
+        // bump.
         [
             'the wrong shape, a level not in the standard',
             signed({ ...base, level: 'platinum' }),
@@ -245,7 +340,9 @@ export async function sealConformanceCases() {
         ],
         // Competence is keyed by category from RT-3. A SEAL issued before it
         // carries competence by task type, and a verifier accepts both
-        // (standard, section 2).
+        // (standard, section 2). Any of the eight stored categories is valid,
+        // math, which a poster can choose from D-UI-12, and conversation and
+        // other, which are no longer offered but past tasks keep.
         [
             'competence by category',
             signed({
@@ -254,6 +351,26 @@ export async function sealConformanceCases() {
             }),
             'valid',
         ],
+        [
+            'competence in math',
+            signed({
+                ...base,
+                scores: { ...base.scores, 'competence:math': 0.8 },
+            }),
+            'valid',
+        ],
+        [
+            'competence in conversation and other, kept by past tasks',
+            signed({
+                ...base,
+                scores: {
+                    ...base.scores,
+                    'competence:conversation': 0.7,
+                    'competence:other': 0.6,
+                },
+            }),
+            'valid',
+        ],
         [
             'competence by task type, issued before categories',
             signed({

package/dist/standing.d.ts

@@ -93,7 +93,17 @@ export type AnswerCounted = z.infer<typeof AnswerCounted>;
 export declare const COUNTED_EVIDENCE: {
     readonly dailyCeiling: 20;
     readonly diminishingK: 25;
+    readonly pairCurve: {
+        readonly free: 5;
+        readonly k: 5;
+        readonly windowDays: 30;
+    };
+    readonly operatorShareCap: {
+        readonly share: 0.5;
+        readonly floor: 5;
+    };
 };
+export declare const POSTER_RESPONSE_HOURS = 48;
 export declare const DAY_MS = 86400000;
 export declare const DORMANCY: {
     readonly quietDays: 14;
@@ -101,9 +111,25 @@ export declare const DORMANCY: {
     readonly dropTwoDays: 60;
     readonly noneDays: 90;
 };
+export declare const TRUST_SCORE: {
+    readonly decay: {
+        readonly fullDays: 30;
+        readonly zeroDays: 180;
+    };
+    readonly diversityWeight: 1.1;
+    readonly diversityMinTasks: 5;
+    readonly operatorK: 2;
+    readonly seriesDays: 30;
+    readonly deltaDays: 7;
+    readonly rankMax: 10000;
+    readonly rankWeeks: 8;
+};
+export declare function trustWeekOf(at: Date): string;
+export declare const SAFETY_MEASURED: boolean;
 export declare const LEVEL_THRESHOLDS: {
     readonly bronze: {
         readonly verifiedTasks: 25;
+        readonly trustScore: 50;
         readonly historyDays: 3;
         readonly reliability: 0.8;
         readonly incidents90d: 0;
@@ -113,6 +139,8 @@ export declare const LEVEL_THRESHOLDS: {
     };
     readonly silver: {
         readonly verifiedTasks: 200;
+        readonly trustScore: 400;
+        readonly trustCategories: 2;
         readonly historyDays: 30;
         readonly reliability: 0.9;
         readonly safety: 0.9;
@@ -125,6 +153,7 @@ export declare const LEVEL_THRESHOLDS: {
     };
     readonly gold: {
         readonly verifiedTasks: 200;
+        readonly trustScore: 400;
         readonly confirmedTasks: 25;
         readonly confirmedOperators: 3;
         readonly historySpanDays: 90;