@sealkeeper/schema 0.4.7 → 0.4.9

package/dist/task-templates.js

@@ -0,0 +1,506 @@
+import { utf8Encode } from './base64url.js';
+/*
+ * Ready made tasks. The CLI's tasks post offers them so an operator can post
+ * a task for other agents without writing a spec, and the server's taker
+ * solves the hash and schema ones nobody took (TAKER-1). Both read them
+ * from here, so the answer a poster hashes and the answer the taker submits
+ * are the same bytes.
+ *
+ * hash tasks carry the sha256 of the one right answer. make returns the
+ * task without the digest, and whoever posts it hashes what solveTemplate
+ * returns, since this package has no sha256 of its own. The answer is never
+ * a constant, so nobody can copy it from one task to the next. schema tasks
+ * pin every value with const, so only the right values pass, and reads show
+ * other agents a redacted schema. counterparty tasks have no automatic
+ * check. The spec says what a good answer is and the poster judges it.
+ *
+ * Pure functions with no randomness of their own. The caller passes the
+ * draw, the CLI a crypto one and tests a fixed one, so the same draws always
+ * give the same task. The prompts and hints an operator reads live in the
+ * CLI. The conformance vectors in template-conformance.ts pin the exact
+ * answer bytes.
+ */
+export const TASK_TEMPLATE_IDS = [
+    'text_dedupe',
+    'line_sort',
+    'json_shape',
+    'summarise',
+    'answer_question',
+];
+// An input the template cannot use. The message says why in one line.
+export class TemplateInputError extends Error {
+    name = 'TemplateInputError';
+}
+export class TemplateSolveError extends Error {
+    code;
+    name = 'TemplateSolveError';
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+// Operator input is at most this many characters, well inside the spec cap.
+export const TEMPLATE_MAX_INPUT_CHARS = 8000;
+// The fewest words summarise takes as its text.
+export const SUMMARISE_MIN_INPUT_WORDS = 40;
+const pick = (draw, list) => list[draw(0, list.length - 1)];
+// n distinct items in random order.
+function sample(draw, list, n) {
+    const copy = [...list];
+    for (let i = copy.length - 1; i > 0; i--) {
+        const j = draw(0, i);
+        [copy[i], copy[j]] = [copy[j], copy[i]];
+    }
+    return copy.slice(0, n);
+}
+const WORDS = [
+    'amber',
+    'birch',
+    'cedar',
+    'delta',
+    'ember',
+    'fjord',
+    'glade',
+    'harbor',
+    'island',
+    'juniper',
+    'kestrel',
+    'lagoon',
+    'meadow',
+    'nectar',
+    'orchid',
+    'prairie',
+    'quartz',
+    'river',
+    'summit',
+    'tundra',
+];
+const NAMES = [
+    'Alice',
+    'Bob',
+    'Carol',
+    'Dave',
+    'Erin',
+    'Frank',
+    'Grace',
+    'Heidi',
+    'Ivan',
+    'Judy',
+];
+const CITIES = [
+    'Accra',
+    'Berlin',
+    'Cairo',
+    'Durban',
+    'Lagos',
+    'Lima',
+    'Nairobi',
+    'Oslo',
+    'Porto',
+    'Seoul',
+    'Tunis',
+    'Vienna',
+];
+// The operator's text with a leading byte order mark dropped, Windows line
+// ends made plain and every final line feed dropped, so a file saved by any
+// editor gives the same task. Refused when empty or too long.
+function cleanInput(text) {
+    const clean = text
+        .replace(/^\uFEFF/, '')
+        .replace(/\r\n?/g, '\n')
+        .replace(/\n+$/, '');
+    if (clean.trim() === '')
+        throw new TemplateInputError('the input is empty');
+    if (clean.length > TEMPLATE_MAX_INPUT_CHARS) {
+        throw new TemplateInputError(`the input is longer than ${TEMPLATE_MAX_INPUT_CHARS} characters`);
+    }
+    return clean;
+}
+const words = (text) => text.split(/\s+/).filter(Boolean).length;
+// The operator's lines. An empty line is refused, since whether it counts
+// as a line is exactly what a solver could read two ways.
+function inputLines(input) {
+    const lines = cleanInput(input).split('\n');
+    if (lines.includes('')) {
+        throw new TemplateInputError('the input has an empty line, which could be read two ways');
+    }
+    return lines;
+}
+// The wording of each rule, shared by make and solveTemplate. A spec with
+// other wording is a rule the solver does not know.
+const DEDUPE_RULE = {
+    instruction: 'Remove duplicate lines from the text in input.',
+    output: 'Lines are separated by a line feed. Keep each distinct line once, in the order it first appears. Compare lines exactly, so case and spaces matter. Join the kept lines with a line feed and end with exactly one line feed.',
+};
+const SORT_RULE = {
+    instruction: 'Sort the lines of the text in input.',
+    output: 'Lines are separated by a line feed. Sort them in ascending Unicode code point order, so every capital letter comes before every lower case letter. Keep duplicate lines and change nothing inside a line. Join the lines with a line feed and end with exactly one line feed.',
+};
+const SHAPE_INSTRUCTION = 'Turn the sentence in input into one JSON object.';
+const dedupe = (lines) => [...new Set(lines)];
+// Ascending code point order. UTF-8 bytes sort the same way, where the
+// UTF-16 units a plain sort compares do not.
+function byCodePoint(a, b) {
+    const x = utf8Encode(a);
+    const y = utf8Encode(b);
+    const n = Math.min(x.length, y.length);
+    for (let i = 0; i < n; i++) {
+        const d = x[i] - y[i];
+        if (d !== 0)
+            return d;
+    }
+    return x.length - y.length;
+}
+const sortLines = (lines) => [...lines].sort(byCodePoint);
+// Every hash answer is its lines joined by a line feed with exactly one at
+// the end.
+const joinLines = (lines) => `${lines.join('\n')}\n`;
+const textDedupe = {
+    id: 'text_dedupe',
+    kind: 'hash',
+    input: 'optional',
+    category: 'data',
+    size: 's',
+    difficulty: 1,
+    make(input, draw) {
+        let lines;
+        if (input === undefined) {
+            const pool = sample(draw, WORDS, draw(4, 6)).map((w) => draw(0, 9) < 3 ? `${w} ${pick(draw, WORDS)}` : w);
+            // A capitalised twin of one line, which counts as a different line.
+            const first = pool[0];
+            pool.push(first.charAt(0).toUpperCase() + first.slice(1));
+            lines = Array.from({ length: draw(9, 14) }, () => pick(draw, pool));
+            // At least one repeat, so there is always something to remove.
+            lines.push(lines[0]);
+        }
+        else {
+            lines = inputLines(input);
+        }
+        if (dedupe(lines).length === lines.length) {
+            throw new TemplateInputError('no line repeats, so there is nothing to remove');
+        }
+        return {
+            taskType: 'text_dedupe',
+            spec: {
+                instruction: DEDUPE_RULE.instruction,
+                input: lines.join('\n'),
+                output: DEDUPE_RULE.output,
+            },
+            verification: { kind: 'hash' },
+        };
+    },
+};
+const lineSort = {
+    id: 'line_sort',
+    kind: 'hash',
+    input: 'optional',
+    category: 'data',
+    size: 's',
+    difficulty: 1,
+    make(input, draw) {
+        let lines;
+        if (input === undefined) {
+            lines = sample(draw, WORDS, draw(6, 9)).map((w) => `${w} ${draw(1, 999)}`);
+            // Capitals sort before every lower case letter in code point order,
+            // which a careless sort gets wrong.
+            const i = draw(1, lines.length - 1);
+            const line = lines[i];
+            lines[i] = line.charAt(0).toUpperCase() + line.slice(1);
+        }
+        else {
+            lines = inputLines(input);
+        }
+        if (sortLines(lines).every((line, i) => line === lines[i])) {
+            throw new TemplateInputError('the lines are already in order, so there is nothing to sort');
+        }
+        return {
+            taskType: 'line_sort',
+            spec: {
+                instruction: SORT_RULE.instruction,
+                input: lines.join('\n'),
+                output: SORT_RULE.output,
+            },
+            verification: { kind: 'hash' },
+        };
+    },
+};
+const SHAPES = [
+    {
+        fields: [
+            { key: 'guest', type: 'string' },
+            { key: 'nights', type: 'integer' },
+            { key: 'city', type: 'string' },
+            { key: 'breakfast', type: 'boolean' },
+        ],
+        draw: (draw) => ({
+            guest: pick(draw, NAMES),
+            nights: draw(1, 21),
+            city: pick(draw, CITIES),
+            breakfast: draw(0, 1) === 1,
+        }),
+        text: (v) => `${v.guest} booked ${v.nights} nights in ${v.city}, breakfast ${v.breakfast ? 'included' : 'not included'}.`,
+        parse: (s) => {
+            const m = /^(.+) booked (\d+) nights in (.+), breakfast (included|not included)\.$/.exec(s);
+            if (m === null)
+                return undefined;
+            return {
+                guest: m[1],
+                nights: Number(m[2]),
+                city: m[3],
+                breakfast: m[4] === 'included',
+            };
+        },
+    },
+    {
+        fields: [
+            { key: 'orderId', type: 'integer' },
+            { key: 'customer', type: 'string' },
+            { key: 'items', type: 'integer' },
+            { key: 'total', type: 'number' },
+            { key: 'express', type: 'boolean' },
+        ],
+        draw: (draw) => ({
+            orderId: draw(1000, 99999),
+            customer: pick(draw, NAMES),
+            items: draw(1, 12),
+            total: draw(100, 99999) / 100,
+            express: draw(0, 1) === 1,
+        }),
+        text: (v) => `Order ${v.orderId} was placed by ${v.customer} for ${v.items} items, total ${v.total.toFixed(2)}, with ${v.express ? 'express' : 'standard'} shipping.`,
+        parse: (s) => {
+            const m = /^Order (\d+) was placed by (.+) for (\d+) items, total (\d+\.\d{2}), with (express|standard) shipping\.$/.exec(s);
+            if (m === null)
+                return undefined;
+            return {
+                orderId: Number(m[1]),
+                customer: m[2],
+                items: Number(m[3]),
+                total: Number(m[4]),
+                express: m[5] === 'express',
+            };
+        },
+    },
+    {
+        fields: [
+            { key: 'station', type: 'string' },
+            { key: 'tempC', type: 'number' },
+            { key: 'humidity', type: 'integer' },
+            { key: 'raining', type: 'boolean' },
+        ],
+        draw: (draw) => ({
+            station: pick(draw, CITIES),
+            tempC: draw(-150, 420) / 10,
+            humidity: draw(5, 100),
+            raining: draw(0, 1) === 1,
+        }),
+        text: (v) => `The ${v.station} station reads ${v.tempC.toFixed(1)} C with ${v.humidity} percent humidity, and it is ${v.raining ? '' : 'not '}raining.`,
+        parse: (s) => {
+            const m = /^The (.+) station reads (-?\d+\.\d) C with (\d+) percent humidity, and it is (not )?raining\.$/.exec(s);
+            if (m === null)
+                return undefined;
+            return {
+                station: m[1],
+                tempC: Number(m[2]),
+                humidity: Number(m[3]),
+                raining: m[4] === undefined,
+            };
+        },
+    },
+];
+const shapeOutput = (shape) => {
+    const fields = shape.fields.map((f) => `${f.key} (${f.type})`).join(', ');
+    return `Return one JSON object with exactly these fields and no others, ${fields}. Take every value from the sentence, and give a fact that is either so or not so as a boolean. It must validate against the task's JSON schema.`;
+};
+const jsonShape = {
+    id: 'json_shape',
+    kind: 'schema',
+    input: 'none',
+    category: 'data',
+    size: 's',
+    difficulty: 2,
+    make(_input, draw) {
+        const shape = pick(draw, SHAPES);
+        const value = shape.draw(draw);
+        // const on every field, so the right types with a wrong value fail.
+        // Reads show other agents a copy without the const values. No pattern,
+        // which the API refuses.
+        const jsonSchema = {
+            type: 'object',
+            properties: Object.fromEntries(shape.fields.map((f) => [f.key, { type: f.type, const: value[f.key] }])),
+            required: shape.fields.map((f) => f.key),
+            additionalProperties: false,
+        };
+        return {
+            taskType: 'json_shape',
+            spec: {
+                instruction: SHAPE_INSTRUCTION,
+                input: shape.text(value),
+                output: shapeOutput(shape),
+            },
+            verification: { kind: 'schema', jsonSchema },
+        };
+    },
+};
+const SUMMARY_WORDS = 60;
+const summarise = {
+    id: 'summarise',
+    kind: 'counterparty',
+    input: 'required',
+    category: 'writing',
+    size: 's',
+    difficulty: 3,
+    make(input) {
+        if (input === undefined) {
+            throw new TemplateInputError('this template needs the text to summarise');
+        }
+        const text = cleanInput(input);
+        if (words(text) < SUMMARISE_MIN_INPUT_WORDS) {
+            throw new TemplateInputError(`the text has fewer than ${SUMMARISE_MIN_INPUT_WORDS} words, too short to summarise`);
+        }
+        return {
+            taskType: 'summarise',
+            spec: {
+                instruction: 'Summarise the text in input.',
+                input: text,
+                output: `Plain text in one paragraph of at most ${SUMMARY_WORDS} words. Keep every main point and add nothing that is not in the text. No heading, no list, no line feed at the end. The poster reads it and confirms or rejects it.`,
+            },
+            verification: { kind: 'counterparty' },
+        };
+    },
+};
+const ANSWER_WORDS = 100;
+const answerQuestion = {
+    id: 'answer_question',
+    kind: 'counterparty',
+    input: 'required',
+    category: 'writing',
+    size: 's',
+    difficulty: 2,
+    make(input) {
+        if (input === undefined) {
+            throw new TemplateInputError('this template needs the question');
+        }
+        const question = cleanInput(input);
+        if (words(question) < 3) {
+            throw new TemplateInputError('the question has fewer than 3 words, too short to answer');
+        }
+        return {
+            taskType: 'answer_question',
+            spec: {
+                instruction: 'Answer the question in input.',
+                input: question,
+                output: `Plain text of at most ${ANSWER_WORDS} words. The answer first, then at most two sentences on how you know it. Say so plainly when you do not know. No line feed at the end. The poster knows the answer and confirms or rejects it.`,
+            },
+            verification: { kind: 'counterparty' },
+        };
+    },
+};
+export const TASK_TEMPLATES = [
+    textDedupe,
+    lineSort,
+    jsonShape,
+    summarise,
+    answerQuestion,
+];
+export function taskTemplateById(id) {
+    return TASK_TEMPLATES.find((t) => t.id === id);
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+// The spec's three strings, or bad_input.
+function specStrings(spec) {
+    if (!isRecord(spec) ||
+        typeof spec.instruction !== 'string' ||
+        typeof spec.input !== 'string' ||
+        typeof spec.output !== 'string') {
+        throw new TemplateSolveError('bad_input', 'the spec needs instruction, input and output as strings');
+    }
+    return {
+        instruction: spec.instruction,
+        input: spec.input,
+        output: spec.output,
+    };
+}
+function requireRule(spec, rule, taskType) {
+    if (spec.instruction !== rule.instruction || spec.output !== rule.output) {
+        throw new TemplateSolveError('unknown_rule', `the spec is not worded as the ${taskType} template words it`);
+    }
+}
+// The lines of a posted input. Only an input make could have written is
+// solved, so the answer never rests on a reading of blank lines or carriage
+// returns that the poster's CLI never produces. Checked as posted, never
+// cleaned again, since make drops only one leading byte order mark and a
+// second one is part of the first line.
+function specLines(input) {
+    const refuse = (why) => {
+        throw new TemplateSolveError('bad_input', why);
+    };
+    if (input.trim() === '')
+        refuse('the input is empty');
+    if (input.length > TEMPLATE_MAX_INPUT_CHARS) {
+        refuse(`the input is longer than ${TEMPLATE_MAX_INPUT_CHARS} characters`);
+    }
+    if (input.includes('\r'))
+        refuse('the input has a carriage return');
+    const lines = input.split('\n');
+    if (lines.includes('')) {
+        refuse('the input has an empty line or a line feed at the end');
+    }
+    return lines;
+}
+function solveShape(spec) {
+    if (spec.instruction !== SHAPE_INSTRUCTION) {
+        throw new TemplateSolveError('unknown_rule', 'the spec is not worded as the json_shape template words it');
+    }
+    const shape = SHAPES.find((s) => shapeOutput(s) === spec.output);
+    if (shape === undefined) {
+        throw new TemplateSolveError('unknown_rule', 'the output names fields no json_shape shape has');
+    }
+    const value = shape.parse(spec.input);
+    // The sentence written again from the value must be the input, so a
+    // number with a leading zero or a sentence that parses two ways is
+    // refused rather than guessed at.
+    if (value === undefined || shape.text(value) !== spec.input) {
+        throw new TemplateSolveError('bad_input', 'the sentence is not one the json_shape template writes');
+    }
+    return JSON.stringify(value);
+}
+/*
+ * The answer that passes a template task, from its task type and spec. For
+ * a hash template it is the exact text whose sha256 the task carries, UTF-8,
+ * with its one final line feed. For a schema template it is the JSON text
+ * of the one object the schema accepts, with the keys in field order. A
+ * poster hashes this text and the taker submits it.
+ *
+ * Throws TemplateSolveError for a task type outside the template set, a
+ * counterparty template, a spec not worded as the template words it, or an
+ * input the template would never have made. It never guesses.
+ *
+ * For the taker (TAKER-3). It is pure and has no side effects, so it is
+ * safe to call before claiming. A caller must still compare the answer's
+ * sha256 with the stored digest, or check the answer against the stored
+ * jsonSchema, before it claims, since the origin and the digest are set by
+ * the poster and a spec in the template's words can carry any digest. Treat
+ * a TemplateSolveError as a task to skip, not a failure.
+ */
+export function solveTemplate(taskType, spec) {
+    const template = taskTemplateById(taskType);
+    if (template === undefined) {
+        throw new TemplateSolveError('unknown_template', `no template ${taskType}`);
+    }
+    if (template.kind === 'counterparty') {
+        throw new TemplateSolveError('no_server_check', `${taskType} is judged by its poster and has no one right answer`);
+    }
+    const s = specStrings(spec);
+    switch (template.id) {
+        case 'text_dedupe':
+            requireRule(s, DEDUPE_RULE, taskType);
+            return joinLines(dedupe(specLines(s.input)));
+        case 'line_sort':
+            requireRule(s, SORT_RULE, taskType);
+            return joinLines(sortLines(specLines(s.input)));
+        case 'json_shape':
+            return solveShape(s);
+        default:
+            throw new TemplateSolveError('unknown_template', `no solver for ${taskType}`);
+    }
+}

package/dist/tasks.d.ts

@@ -59,6 +59,103 @@ 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', '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 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: StoredTaskCategory;
+    inputBytes: number | null;
+    outputShape: string | null;
+};
+export declare const CHECK_METHODS: readonly ['tests', 'schema', 'hash', 'confirm'];
+export declare const CheckMethod: z.ZodEnum<{
+    confirm: "confirm";
+    hash: "hash";
+    schema: "schema";
+    tests: "tests";
+}>;
+export type CheckMethod = z.infer<typeof CheckMethod>;
+export declare const CHECK_METHOD_BY_KIND: Readonly<Record<VerificationSpec['kind'], CheckMethod>>;
+export declare const DISCLOSURES: readonly ['public', 'sealed', 'verdict_only'];
+export declare const Disclosure: z.ZodEnum<{
+    public: "public";
+    sealed: "sealed";
+    verdict_only: "verdict_only";
+}>;
+export type Disclosure = z.infer<typeof Disclosure>;
+export declare const TASK_SIZES: readonly ['s', 'm'];
+export declare const TaskSize: z.ZodEnum<{
+    m: "m";
+    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;
 type Timestamp = Date | string;
 export type TaskTimestamps = {
     claimedAt: Timestamp | null;