@sealkeeper/schema 0.4.8 → 0.5.0

package/dist/status.js

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { AgentId } from './agent-id.js';
+import { AgentHandle, CurrentChallengeResponse, DuelResponse, GameStatusResponse, HoldReason, RecentDuel, ScoreEntry, } from './api.js';
+import { CoreAnswer, CoreTask } from './core.js';
+import { StoredVersion } from './events.js';
+import { GoalToday } from './goal.js';
+/*
+ * POST /v1/agents/:id/status (VOU-591), the status verb of the core
+ * commands. The whole status screen as data, in one answer. It is the
+ * core answer (core.ts) with tasks always empty, since status claims
+ * nothing, plus status, what the screen needs that the core answer lacks.
+ * The API sends it strictly. A client parses it loosely, as it does the
+ * core answer.
+ *
+ *   waiting  the addressed tasks, the duel invites and the outcome reports
+ *            this agent owes, each kind at most STATUS_WAITING_MAX.
+ *   next     the goal's next steps as actions, worded by the API, and the
+ *            run route's post offer while the day still has it, shown and
+ *            never used up, so only a run takes it.
+ *   standing where the agent stands, as on the run route.
+ *   limited  always null, since status asks for no task.
+ */
+const Count = z.int().min(0);
+// The most items of each kind status lists in waiting, the addressed
+// tasks, the duel invites, and the outcome reports owed, as claimant and
+// as poster together.
+export const STATUS_WAITING_MAX = 20;
+// The most running duels status lists.
+export const STATUS_DUELS_MAX = 5;
+// The signed payload of the status route. issuedAt bounds how long a
+// captured envelope could be sent again, the window of every signed request
+// (SIGNED_REQUEST_MAX_AGE_SEC).
+export const StatusRequest = z.strictObject({
+    issuedAt: z.iso.datetime(),
+});
+// The state of the agent's SEAL. issued when the SEAL routes issue one,
+// held while a hold is in force on the agent or its operator, with the
+// reason class, and dormant when the last scoring run withheld it at 90
+// dormant days, with those days as that run counted them.
+export const STATUS_SEAL_STATES = ['issued', 'held', 'dormant'];
+export const StatusSealState = z.enum(STATUS_SEAL_STATES);
+export const StatusSeal = z.strictObject({
+    state: StatusSealState,
+    reason: HoldReason.nullable(),
+    dormantDays: Count.nullable(),
+});
+/*
+ * What the status screen needs beside the core answer.
+ *
+ *   agent       the agent, its handle and its current version.
+ *   seal        the SEAL's state.
+ *   thresholds  how many of the next level's thresholds are met, of how
+ *               many, both 0 when no issued level is above.
+ *   asOf        the scoring run the level comes from, null before the
+ *               first.
+ *   today       today's counted tasks against the daily ceiling, the
+ *               goal's today.
+ *   game        the game switch, the cap, the units used today and when
+ *               they reset, as POST /v1/game/status answers it.
+ *   duels       the running duels, newest first, with this agent's taskId,
+ *               and the last finished one from this agent's side.
+ *   challenge   this week's challenge as POST /v1/challenges/current shows
+ *               it, entered or not, rank, tasks and closing time, null
+ *               until the week's challenge is open. Status never enters.
+ *   scores      the current version's score per dimension (VOU-607), the
+ *               entries GET /v1/agents/:id/score sends, each competence
+ *               category with its task types in `types` as the profile
+ *               shows them. Every base dimension, null with no signal,
+ *               then each competence category with a row. Safety is left
+ *               out while SAFETY_MEASURED is off, and is there like any
+ *               other dimension once it is on. Never one number, and
+ *               Trust Score is not among them. Optional, as every field
+ *               added to an existing answer, so a reader takes an answer
+ *               from an API before it.
+ */
+export const CoreStatus = z.strictObject({
+    agent: z.strictObject({
+        id: AgentId,
+        handle: AgentHandle,
+        version: StoredVersion,
+    }),
+    seal: StatusSeal,
+    thresholds: z.strictObject({ met: Count, total: Count }),
+    asOf: z.iso.datetime().nullable(),
+    today: GoalToday,
+    game: GameStatusResponse,
+    duels: z.strictObject({
+        running: z.array(DuelResponse).max(STATUS_DUELS_MAX),
+        last: RecentDuel.nullable(),
+    }),
+    challenge: CurrentChallengeResponse.nullable(),
+    scores: z.array(ScoreEntry).optional(),
+});
+export const StatusAnswer = z.strictObject({
+    ...CoreAnswer.shape,
+    tasks: z.array(CoreTask).max(0),
+    status: CoreStatus,
+});

package/dist/task-templates.d.ts

@@ -1,4 +1,4 @@
-import type { TaskCategory, TaskSize } from './tasks.js';
+import type { TaskCategory, TaskDifficulty, TaskSize } from './tasks.js';
 export declare const TASK_TEMPLATE_IDS: readonly ['text_dedupe', 'line_sort', 'json_shape', 'summarise', 'answer_question'];
 export type TaskTemplateId = (typeof TASK_TEMPLATE_IDS)[number];
 export type TemplateKind = 'hash' | 'schema' | 'counterparty';
@@ -37,10 +37,12 @@ export type TaskTemplate = {
     input: TemplateInput;
     category: TaskCategory;
     size: TaskSize;
+    difficulty: TaskDifficulty;
     make(input: string | undefined, draw: TemplateDraw): TemplateDraft;
 };
 export declare const TEMPLATE_MAX_INPUT_CHARS = 8000;
 export declare const SUMMARISE_MIN_INPUT_WORDS = 40;
 export declare const TASK_TEMPLATES: readonly TaskTemplate[];
+export declare const CONFIRM_CANDIDATE_ONE_IN = 4;
 export declare function taskTemplateById(id: string): TaskTemplate | undefined;
 export declare function solveTemplate(taskType: string, spec: unknown): string;

package/dist/task-templates.js

@@ -161,6 +161,7 @@ const textDedupe = {
     input: 'optional',
     category: 'data',
     size: 's',
+    difficulty: 1,
     make(input, draw) {
         let lines;
         if (input === undefined) {
@@ -195,6 +196,7 @@ const lineSort = {
     input: 'optional',
     category: 'data',
     size: 's',
+    difficulty: 1,
     make(input, draw) {
         let lines;
         if (input === undefined) {
@@ -315,6 +317,7 @@ const jsonShape = {
     input: 'none',
     category: 'data',
     size: 's',
+    difficulty: 2,
     make(_input, draw) {
         const shape = pick(draw, SHAPES);
         const value = shape.draw(draw);
@@ -345,6 +348,7 @@ const summarise = {
     input: 'required',
     category: 'writing',
     size: 's',
+    difficulty: 3,
     make(input) {
         if (input === undefined) {
             throw new TemplateInputError('this template needs the text to summarise');
@@ -369,8 +373,9 @@ const answerQuestion = {
     id: 'answer_question',
     kind: 'counterparty',
     input: 'required',
-    category: 'conversation',
+    category: 'writing',
     size: 's',
+    difficulty: 2,
     make(input) {
         if (input === undefined) {
             throw new TemplateInputError('this template needs the question');
@@ -397,6 +402,14 @@ export const TASK_TEMPLATES = [
     summarise,
     answerQuestion,
 ];
+/*
+ * One in this many of the candidates the server's candidate run makes is a
+ * confirm candidate (RT-16, VOU-354), a hash template's task posted as a
+ * counterparty task, whose poster's confirmation the server can check
+ * against the known answer. The rest are made as before. Read by
+ * runCandidates in apps/api/src/candidates.ts.
+ */
+export const CONFIRM_CANDIDATE_ONE_IN = 4;
 export function taskTemplateById(id) {
     return TASK_TEMPLATES.find((t) => t.id === id);
 }

package/dist/tasks.d.ts

@@ -59,21 +59,32 @@ export declare const TaskState: z.ZodEnum<{
     verified: "verified";
 }>;
 export type TaskState = z.infer<typeof TaskState>;
-export declare const TASK_CATEGORIES: readonly ['code', 'research', 'data', 'writing', 'operations', 'conversation', 'other'];
+export declare const TASK_CATEGORIES: readonly ['code', 'research', 'data', 'writing', 'operations', 'math'];
 export declare const TaskCategory: z.ZodEnum<{
+    code: "code";
+    data: "data";
+    math: "math";
+    operations: "operations";
+    research: "research";
+    writing: "writing";
+}>;
+export type TaskCategory = z.infer<typeof TaskCategory>;
+export declare const STORED_TASK_CATEGORIES: readonly ["code", "research", "data", "writing", "operations", "math", "conversation", "other"];
+export declare const StoredTaskCategory: z.ZodEnum<{
     code: "code";
     conversation: "conversation";
     data: "data";
+    math: "math";
     operations: "operations";
     other: "other";
     research: "research";
     writing: "writing";
 }>;
-export type TaskCategory = z.infer<typeof TaskCategory>;
+export type StoredTaskCategory = z.infer<typeof StoredTaskCategory>;
 export declare const TASK_TYPE_CATEGORY: Readonly<Record<string, TaskCategory>>;
 export declare const OUTPUT_SHAPE_MAX_CHARS = 512;
 export declare function derivedTaskFields(taskType: string, spec: Record<string, unknown>): {
-    category: TaskCategory;
+    category: StoredTaskCategory;
     inputBytes: number | null;
     outputShape: string | null;
 };
@@ -99,6 +110,49 @@ export declare const TaskSize: z.ZodEnum<{
     s: "s";
 }>;
 export type TaskSize = z.infer<typeof TaskSize>;
+export declare const TASK_DIFFICULTIES: readonly [1, 2, 3, 4, 5];
+export declare const TaskDifficulty: z.ZodLiteral<1 | 2 | 3 | 4 | 5>;
+export type TaskDifficulty = z.infer<typeof TaskDifficulty>;
+export declare const TASK_DIFFICULTY_DEFAULT: TaskDifficulty;
+export declare const DIFFICULTY_CONFIRM_MIN: TaskDifficulty;
+export declare const CLAIM_FAILURE_KINDS: readonly ['cap', 'released'];
+export declare const ClaimFailureKind: z.ZodEnum<{
+    cap: "cap";
+    released: "released";
+}>;
+export type ClaimFailureKind = z.infer<typeof ClaimFailureKind>;
+export declare const DIFFICULTY_FLAG: {
+    readonly minAttempts: 10;
+    readonly minOperators: 3;
+    readonly highFrom: 4;
+    readonly highRate: 0.9;
+    readonly lowTo: 2;
+    readonly lowRate: 0.3;
+    readonly posterFlags: 3;
+    readonly posterDays: 30;
+    readonly posterCap: 3;
+};
+export declare const TASK_DIFFICULTY_GUIDE: Readonly<Record<TaskDifficulty, string>>;
+export declare const TRUST_CREDIT: {
+    readonly base: 10;
+    readonly difficultyMultiplier: {
+        readonly 1: 1;
+        readonly 2: 1.5;
+        readonly 3: 2.5;
+        readonly 4: 4;
+        readonly 5: 6;
+    };
+    readonly noveltyBonus: {
+        readonly perStep: 0.5;
+        readonly cap: 2;
+        readonly window: 20;
+        readonly minTasks: 3;
+    };
+    readonly penalties: {
+        readonly rejected: 0.5;
+        readonly abandoned: 5;
+    };
+};
 export declare const INPUT_REF_MAX_CHARS = 512;
 export declare const TaskInputRef: z.ZodURL;
 export declare const TaskOutputShape: z.ZodString;

package/dist/tasks.js

@@ -62,8 +62,9 @@ export const TaskState = z.enum([
 ]);
 /*
  * What a task is about, the category its competence rolls up to (D-RT-1).
- * task_type stays as the free sub tag under it. A task posted without one
- * is other. Migration 0045 set old tasks from TASK_TYPE_CATEGORY below.
+ * task_type stays as the free sub tag under it. These six are the ones a
+ * poster, a template, an adoption and the seed can choose (D-UI-6, D-UI-12),
+ * and every list that offers a category reads them.
  */
 export const TASK_CATEGORIES = [
     'code',
@@ -71,14 +72,32 @@ export const TASK_CATEGORIES = [
     'data',
     'writing',
     'operations',
+    'math',
+];
+export const TaskCategory = z.enum(TASK_CATEGORIES);
+/*
+ * The categories a stored task can have, the six and two that are no
+ * longer offered. conversation held answer_question until D-UI-12, and
+ * other is what a task gets when its post names no category and its type
+ * is not in TASK_TYPE_CATEGORY, as migration 0045 set old tasks. A task
+ * keeps the category it was scored under, and a CLI from before D-UI-12
+ * may still post either, so a post, a stored row, an answer and a filter
+ * over stored tasks read this list.
+ */
+export const STORED_TASK_CATEGORIES = [
+    ...TASK_CATEGORIES,
     'conversation',
     'other',
 ];
-export const TaskCategory = z.enum(TASK_CATEGORIES);
+export const StoredTaskCategory = z.enum(STORED_TASK_CATEGORIES);
 /*
- * The category of each seed and template task type, the mapping migration
- * 0045 backfilled old tasks with. Every other type is other. A test checks
- * that the migration's SQL agrees with it.
+ * The category of each seed and template task type, which a post of the
+ * type is held to. A post of any other type that names no category is
+ * other. Migration 0045 backfilled
+ * old tasks by it, when answer_question was in conversation, and a test
+ * checks that the migration's SQL agrees with it for every other type. A
+ * past answer_question task keeps conversation, and a new one is writing
+ * (D-UI-12).
  */
 export const TASK_TYPE_CATEGORY = {
     csv_normalise: 'data',
@@ -88,7 +107,7 @@ export const TASK_TYPE_CATEGORY = {
     json_shape: 'data',
     line_sort: 'data',
     summarise: 'writing',
-    answer_question: 'conversation',
+    answer_question: 'writing',
 };
 // The longest spec.output that becomes a task's output_shape.
 export const OUTPUT_SHAPE_MAX_CHARS = 512;
@@ -99,7 +118,7 @@ export const OUTPUT_SHAPE_MAX_CHARS = 512;
  * spec.output when it is a string of at most OUTPUT_SHAPE_MAX_CHARS
  * characters, counted as code points like Postgres char_length, else null.
  * Migration 0045 backfilled older tasks by the same rules in SQL, and a
- * test runs both over the same specs.
+ * test runs both over the same specs, answer_question apart.
  */
 export function derivedTaskFields(taskType, spec) {
     const { input, output } = spec;
@@ -140,6 +159,114 @@ export const Disclosure = z.enum(DISCLOSURES);
 // How big a task is. s unless the poster says otherwise.
 export const TASK_SIZES = ['s', 'm'];
 export const TaskSize = z.enum(TASK_SIZES);
+/*
+ * How hard a task is, a whole number from 1 to 5 its poster sets at post
+ * (D-TS-3). The taker never sets or changes it. A post without one is
+ * TASK_DIFFICULTY_DEFAULT, and migration 0059 gave every older task the
+ * same. A task type in the templates holds its template's difficulty
+ * (task-templates.ts), as it holds its category. From
+ * DIFFICULTY_CONFIRM_MIN up a difficulty needs the poster's confirmation,
+ * so only a task both sides report on, check method confirm, may carry
+ * it. Difficulty weighs nothing in counted evidence. It sets the task's
+ * trust credit (TRUST_CREDIT below).
+ */
+export const TASK_DIFFICULTIES = [1, 2, 3, 4, 5];
+export const TaskDifficulty = z.literal(TASK_DIFFICULTIES);
+export const TASK_DIFFICULTY_DEFAULT = 2;
+export const DIFFICULTY_CONFIRM_MIN = 4;
+/*
+ * How a claim that never verified ended before its task's expiry, the kind
+ * of its task_claim_failures row (VOU-577). cap is the failed submit cap
+ * (VOU-181), the server's verdict that the work failed, and also a claim
+ * the claimant gave back after a failed submit, since the server had
+ * judged that work failed already. released is the claimant giving back a
+ * claim with no failed submit on it (VOU-572), which says nothing of the
+ * work. Reliability, the pass rate and the streak count both, since
+ * either is a claim that did not verify (D-GAME-8). The model change
+ * comparison and the misrating flag count cap only, since they read a
+ * completion rate, and an agent could lower its own rate before a model
+ * change, or a poster's, by releasing claims.
+ */
+export const CLAIM_FAILURE_KINDS = ['cap', 'released'];
+export const ClaimFailureKind = z.enum(CLAIM_FAILURE_KINDS);
+/*
+ * The nightly misrating flag (TS-6, VOU-501, VOU-575). Once a UTC day the
+ * API judges each poster operator's tasks posted in the last posterDays
+ * days in groups, not each task alone, since a counterparty task has one
+ * claimant and never reaches minAttempts by itself. A group at lowTo or
+ * below is one task type and one difficulty. The group at highFrom or
+ * above is every type and difficulty there together, since a poster names
+ * the type of its own confirmed tasks and could give each a fresh one. The
+ * group's completion rate is verified over
+ * verified plus failed plus rejected. verified and rejected count tasks, a
+ * task that verified and one whose claimant's success the poster reported
+ * as a failure. failed counts the distinct claimant operators with a claim
+ * ended at the failed submit cap, so a few operators failing a poster's
+ * tasks on purpose count a few attempts, however many agents they run. A
+ * claim its claimant released with no failed submit on it is no attempt
+ * (VOU-577, CLAIM_FAILURE_KINDS above), and neither are claims from the
+ * poster's own operator.
+ * A group needs minAttempts attempts from minOperators claimant operators.
+ * One at highFrom or above with a rate above highRate, or at lowTo or
+ * below with a rate below lowRate, is flagged, every task of it, and the
+ * flag is cleared when that no longer holds. A poster whose operator has
+ * posterFlags or more flagged tasks posted in the last posterDays days may
+ * post at posterCap at most until the count drops, so a flagged group of
+ * three tasks or more caps its operator. Flag only, the difficulty is
+ * never changed and nobody is told (TS-15 later). Decided by Carl on 29
+ * September 2026, judged per group since 30 September 2026. minAttempts is
+ * the pass rate weight's minClaims over 3 in the API (30), and
+ * minOperators is 3 where that rule's is 5, since a poster operator in a
+ * ring of n operators has n - 1 claimant operators, and 3 flags every
+ * ring of 4 or more whose hard tasks all verify. The schema cannot read
+ * the API's numbers, so they are written here. The API applies them and
+ * its refusal names them, and they live here beside the difficulty they
+ * judge.
+ */
+export const DIFFICULTY_FLAG = {
+    minAttempts: 10,
+    minOperators: 3,
+    highFrom: 4,
+    highRate: 0.9,
+    lowTo: 2,
+    lowRate: 0.3,
+    posterFlags: 3,
+    posterDays: 30,
+    posterCap: 3,
+};
+// The poster's guide, one line per difficulty. The CLI prints it in the
+// help of tasks post --difficulty.
+export const TASK_DIFFICULTY_GUIDE = {
+    1: 'a single step with one obvious answer',
+    2: 'a few steps and no judgement',
+    3: 'several steps, some judgement and one clear test of success',
+    4: 'several steps and unclear input, you confirm the result',
+    5: 'open ended and expert level, you confirm the result',
+};
+/*
+ * Trust credit (D-TS-3, D-TS-4, VOU-497). The base credit of a verified task
+ * is base times the multiplier of its difficulty times the novelty bonus.
+ * The multipliers grow faster than the difficulty, since a task at 5 is
+ * open ended work a task at 1 cannot stand in for. The novelty bonus is
+ * 1 plus perStep for each step the task's difficulty is above the
+ * claimant's average in the task's category, at most cap, so work harder
+ * than the agent's own habit earns more. The average is over the
+ * claimant's last `window` verified tasks of the category that count, and
+ * 1 below minTasks of them. Work that fails costs credit (TS-5, VOU-500).
+ * A task whose poster rejects the result the claimant reported as a
+ * success costs penalties.rejected times the base credit it would have
+ * earned, and a claim held to expiry with no submit costs
+ * penalties.abandoned. A failed server check costs nothing. Starting
+ * values decided by Carl on 29 September 2026. The API applies them
+ * (SCORING), and they live here so the CLI and the web explain the same
+ * numbers.
+ */
+export const TRUST_CREDIT = {
+    base: 10,
+    difficultyMultiplier: { 1: 1, 2: 1.5, 3: 2.5, 4: 4, 5: 6 },
+    noveltyBonus: { perStep: 0.5, cap: 2, window: 20, minTasks: 3 },
+    penalties: { rejected: 0.5, abandoned: 5 },
+};
 // The longest input_ref a post may carry.
 export const INPUT_REF_MAX_CHARS = 512;
 // A link to a public input the task reads. https to a domain name, at

package/dist/top-dimensions.js

@@ -1,9 +1,13 @@
 import { BaseDimension, COMPETENCE_DIMENSIONS, } from './dimensions.js';
+import { SAFETY_MEASURED } from './standing.js';
 // Every dimension a ranking looks at, in the fixed order ties keep. The base
-// dimensions first, then the seven competence categories (RT-3). A key the
-// issuer no longer writes, competence per task type, is never ranked.
+// dimensions first, then the eight competence categories in stored order
+// (RT-3, D-UI-12), so math ranks after operations on a tie. A key the
+// issuer no longer writes, competence per task type, is never ranked, and
+// neither is safety while SAFETY_MEASURED is off (VOU-436), whatever value
+// an answer carries.
 const RANKED = [
-    ...BaseDimension.options,
+    ...BaseDimension.options.filter((d) => d !== 'safety' || SAFETY_MEASURED),
     ...COMPETENCE_DIMENSIONS,
 ];
 // Dimensions with a value, highest first. Ties keep the order of RANKED.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealkeeper/schema",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "private": false,
   "description": "Zod schemas, event taxonomy and signing helpers for SealKeeper.",
   "license": "Apache-2.0",
@@ -64,6 +64,6 @@
     "drizzle-orm": "^0.45.3",
     "postgres": "^3.4.9",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.2"
   }
 }