@sealkeeper/schema 0.4.9 → 0.5.1

package/dist/task-templates.js

@@ -1,24 +1,15 @@
-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.
+ * Ready made tasks, what is public about them. The CLI's post offers them so
+ * an operator can post a task for other agents without writing a spec, and
+ * the API makes, solves and stores each one (TAKER-1, VOU-640). This package
+ * holds the ids, the kind of check, the input each takes, the category,
+ * size and difficulty a post carries and the rules an operator's input must
+ * meet, so the CLI and the web read them from one place.
  *
- * 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.
+ * The generators that write a spec and the solver that answers one live in
+ * the API alone (apps/api/src/template-tasks.ts), never in this package, so
+ * the public CLI hands nobody a script that solves a template task. The
+ * prompts and hints an operator reads live in the CLI.
  */
 export const TASK_TEMPLATE_IDS = [
     'text_dedupe',
@@ -31,476 +22,118 @@ export const TASK_TEMPLATE_IDS = [
 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 = [
+// The fewest words answer_question takes as its question.
+export const QUESTION_MIN_INPUT_WORDS = 3;
+export const TASK_TEMPLATES = [
     {
-        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',
-            };
-        },
+        id: 'text_dedupe',
+        kind: 'hash',
+        input: 'optional',
+        category: 'data',
+        size: 's',
+        difficulty: 1,
     },
     {
-        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',
-            };
-        },
+        id: 'line_sort',
+        kind: 'hash',
+        input: 'optional',
+        category: 'data',
+        size: 's',
+        difficulty: 1,
     },
     {
-        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 },
-        };
+        id: 'json_shape',
+        kind: 'schema',
+        input: 'none',
+        category: 'data',
+        size: 's',
+        difficulty: 2,
     },
-};
-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' },
-        };
+    {
+        id: 'summarise',
+        kind: 'counterparty',
+        input: 'required',
+        category: 'writing',
+        size: 's',
+        difficulty: 3,
     },
-};
-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' },
-        };
+    {
+        id: 'answer_question',
+        kind: 'counterparty',
+        input: 'required',
+        category: 'writing',
+        size: 's',
+        difficulty: 2,
     },
-};
-export const TASK_TEMPLATES = [
-    textDedupe,
-    lineSort,
-    jsonShape,
-    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);
 }
-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);
-}
+// What a required input is, for the refusal when it is missing.
+const NEEDS = {
+    summarise: 'the text to summarise',
+    answer_question: 'the question',
+};
+const words = (text) => text.split(/\s+/).filter(Boolean).length;
 /*
- * 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.
+ * The operator's input to a template as the template uses it, or undefined
+ * when the template draws its own. A leading byte order mark is dropped,
+ * Windows line ends made plain and every final line feed dropped, so a file
+ * saved by any editor gives the same task. Throws TemplateInputError with
+ * the reason in one line for an input the template cannot take. That is an
+ * input to a template that takes none, a missing one a template needs, an
+ * empty one, one longer than TEMPLATE_MAX_INPUT_CHARS, an empty line in the
+ * lines of a hash template, since whether it counts as a line is exactly
+ * what a solver could read two ways, or too few words.
  *
- * 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.
+ * The CLI checks with it before it asks for a yes, and the API's generators
+ * run it on what the CLI sent, so these rules live in one place. Whether
+ * the lines leave anything to remove or sort is the API's to say, since it
+ * takes the solver to know.
  */
-export function solveTemplate(taskType, spec) {
-    const template = taskTemplateById(taskType);
-    if (template === undefined) {
-        throw new TemplateSolveError('unknown_template', `no template ${taskType}`);
+export function cleanTemplateInput(id, input) {
+    const template = taskTemplateById(id);
+    if (template.input === 'none') {
+        if (input !== undefined) {
+            throw new TemplateInputError(`${id} takes no input, it makes its own`);
+        }
+        return undefined;
+    }
+    if (input === undefined) {
+        if (template.input === 'required') {
+            throw new TemplateInputError(`this template needs ${NEEDS[id]}`);
+        }
+        return undefined;
+    }
+    const clean = input
+        .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`);
     }
-    if (template.kind === 'counterparty') {
-        throw new TemplateSolveError('no_server_check', `${taskType} is judged by its poster and has no one right answer`);
+    if (template.kind === 'hash' && clean.split('\n').includes('')) {
+        throw new TemplateInputError('the input has an empty line, which could be read two ways');
     }
-    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}`);
+    if (id === 'summarise' && words(clean) < SUMMARISE_MIN_INPUT_WORDS) {
+        throw new TemplateInputError(`the text has fewer than ${SUMMARISE_MIN_INPUT_WORDS} words, too short to summarise`);
     }
+    if (id === 'answer_question' && words(clean) < QUESTION_MIN_INPUT_WORDS) {
+        throw new TemplateInputError(`the question has fewer than ${QUESTION_MIN_INPUT_WORDS} words, too short to answer`);
+    }
+    return clean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealkeeper/schema",
-  "version": "0.4.9",
+  "version": "0.5.1",
   "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"
   }
 }

package/dist/template-conformance.d.ts

@@ -1,10 +0,0 @@
-import type { TemplateSpec } from './task-templates.js';
-export type TemplateVector = {
-    name: string;
-    taskType: string;
-    spec: TemplateSpec;
-    answer: string;
-    sha256: string;
-    jsonSchema?: Record<string, unknown>;
-};
-export declare const TEMPLATE_VECTORS: readonly TemplateVector[];