@sealkeeper/schema 0.4.2 → 0.4.3

package/dist/api.d.ts

@@ -111,6 +111,7 @@ export declare const DeleteAgentBody: z.ZodUnion<readonly [z.ZodObject<{
     envelope: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{}, z.core.$strict>]>;
 export type DeleteAgentBody = z.infer<typeof DeleteAgentBody>;
+export declare const GithubLogin: z.ZodString;
 export declare const AgentHandleParams: z.ZodObject<{
     login: z.ZodString;
     name: z.ZodString;
@@ -125,7 +126,6 @@ export declare const AgentRenamedResponse: z.ZodObject<{
     handle: z.ZodString;
 }, z.core.$strict>;
 export type AgentRenamedResponse = z.infer<typeof AgentRenamedResponse>;
-export declare const GithubLogin: z.ZodString;
 export type AgentsCursor = {
     createdAtMicros: string;
     id: string;
@@ -266,6 +266,8 @@ export declare const EventsBatchResponse: z.ZodObject<{
     duplicates: z.ZodInt;
 }, z.core.$strict>;
 export type EventsBatchResponse = z.infer<typeof EventsBatchResponse>;
+export declare const AgentRef: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+export type AgentRef = z.infer<typeof AgentRef>;
 export declare const PostTaskRequest: z.ZodObject<{
     taskId: z.ZodUUID;
     taskType: z.ZodString;
@@ -280,12 +282,22 @@ export declare const PostTaskRequest: z.ZodObject<{
         kind: z.ZodLiteral<"counterparty">;
     }, z.core.$strict>], "kind">;
     expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    assignee: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString]>>;
 }, z.core.$strict>;
 export type PostTaskRequest = z.infer<typeof PostTaskRequest>;
+export declare const TaskAssignee: z.ZodObject<{
+    id: z.ZodString;
+    handle: z.ZodString;
+}, z.core.$strict>;
+export type TaskAssignee = z.infer<typeof TaskAssignee>;
 export declare const TaskResponse: z.ZodObject<{
     id: z.ZodUUID;
     posterAgentId: z.ZodString;
     claimantAgentId: z.ZodNullable<z.ZodString>;
+    assignee: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        handle: z.ZodString;
+    }, z.core.$strict>>>;
     taskType: z.ZodString;
     spec: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     verification: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -352,6 +364,10 @@ export declare const TaskSubmissionResponse: z.ZodObject<{
         id: z.ZodUUID;
         posterAgentId: z.ZodString;
         claimantAgentId: z.ZodNullable<z.ZodString>;
+        assignee: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            handle: z.ZodString;
+        }, z.core.$strict>>>;
         taskType: z.ZodString;
         spec: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         verification: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -398,6 +414,7 @@ export declare const ListTasksQuery: z.ZodObject<{
         verified: "verified";
     }>>;
     taskType: z.ZodOptional<z.ZodString>;
+    assignee: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
 export type ListTasksQuery = z.infer<typeof ListTasksQuery>;
@@ -406,6 +423,10 @@ export declare const ListTasksResponse: z.ZodObject<{
         id: z.ZodUUID;
         posterAgentId: z.ZodString;
         claimantAgentId: z.ZodNullable<z.ZodString>;
+        assignee: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            handle: z.ZodString;
+        }, z.core.$strict>>>;
         taskType: z.ZodString;
         spec: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         verification: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -495,7 +516,13 @@ export declare const TaskView: z.ZodObject<{
         handle: z.ZodString;
         operatedBySealKeeper: z.ZodBoolean;
     }, z.core.$strict>>;
+    assignee: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        handle: z.ZodString;
+        operatedBySealKeeper: z.ZodBoolean;
+    }, z.core.$strict>>;
     countsForTrust: z.ZodNullable<z.ZodBoolean>;
+    evidenceWeight: z.ZodNullable<z.ZodNumber>;
     postedAt: z.ZodISODateTime;
     claimedAt: z.ZodNullable<z.ZodISODateTime>;
     submittedAt: z.ZodNullable<z.ZodISODateTime>;
@@ -534,7 +561,13 @@ export declare const TaskViewsResponse: z.ZodObject<{
             handle: z.ZodString;
             operatedBySealKeeper: z.ZodBoolean;
         }, z.core.$strict>>;
+        assignee: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            handle: z.ZodString;
+            operatedBySealKeeper: z.ZodBoolean;
+        }, z.core.$strict>>;
         countsForTrust: z.ZodNullable<z.ZodBoolean>;
+        evidenceWeight: z.ZodNullable<z.ZodNumber>;
         postedAt: z.ZodISODateTime;
         claimedAt: z.ZodNullable<z.ZodISODateTime>;
         submittedAt: z.ZodNullable<z.ZodISODateTime>;
@@ -902,6 +935,7 @@ export declare const FeedPayloads: {
         name: z.ZodString;
         taskId: z.ZodUUID;
         taskType: z.ZodString;
+        addressed: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>;
     score_change: z.ZodObject<{
         agentId: z.ZodString;
@@ -992,6 +1026,7 @@ export declare const FeedItem: z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodString;
         taskId: z.ZodUUID;
         taskType: z.ZodString;
+        addressed: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strict>;
     createdAt: z.ZodISODateTime;
 }, z.core.$strict>, z.ZodObject<{
@@ -1134,6 +1169,7 @@ export declare const FeedRecentResponse: z.ZodObject<{
             name: z.ZodString;
             taskId: z.ZodUUID;
             taskType: z.ZodString;
+            addressed: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strict>;
         createdAt: z.ZodISODateTime;
     }, z.core.$strict>, z.ZodObject<{

package/dist/api.js

@@ -51,8 +51,10 @@ const Count = z.int().min(0);
 // incidents the incident events. verifiedTasks counts tasks the agent claimed
 // that reached verified and that count toward trust, meaning the poster is
 // an agent of another operator or the seed agent. Same rule as scoring.
-// seedTasks is how many of those the seed agent posted. GET by id and GET
-// by handle both send it. Optional so an answer from an older API parses.
+// Each weighs as it does in the evidence counts and the sum is rounded
+// down, so a task addressed to the agent counts as half. seedTasks is how
+// many of those the seed agent posted. GET by id and GET by handle both
+// send it. Optional so an answer from an older API parses.
 // These are live, all time counts. The standing counts on the same answer
 // are the scoring window's, as of the last run.
 export const AgentCounts = z.strictObject({
@@ -148,10 +150,12 @@ export const DeleteAgentBody = z.union([
     z.strictObject({ envelope: Jws.max(MAX_ENVELOPE_CHARS) }),
     z.strictObject({}),
 ]);
+// A GitHub login. Letters, digits and hyphens, at most 39 characters.
+export const GithubLogin = z.string().regex(/^[A-Za-z0-9-]{1,39}$/);
 // GET /v1/agents/:login/:name. Case does not matter in the login, as on
 // GitHub. Names are lowercase.
 export const AgentHandleParams = z.strictObject({
-    login: z.string().regex(/^[A-Za-z0-9-]{1,39}$/),
+    login: GithubLogin,
     name: AgentName,
 });
 // The 404 for a handle an agent gave up in a rename in the last
@@ -165,10 +169,6 @@ export const AgentRenamedResponse = z.strictObject({
     id: AgentId,
     handle: AgentHandle,
 });
-// The public agents directory, GET /v1/agents. Newest registration first,
-// ties broken by id, paged with an opaque cursor.
-// A GitHub login. Letters, digits and hyphens, at most 39 characters.
-export const GithubLogin = z.string().regex(/^[A-Za-z0-9-]{1,39}$/);
 function keysetCursor(id, isId = () => true) {
     const text = new RegExp(`^(\\d{1,18})\\.(${id.source})$`);
     const encode = (c) => base64urlEncode(utf8Encode(`${c.micros}.${c.id}`));
@@ -273,20 +273,44 @@ export const EventsBatchResponse = z.strictObject({
 const TaskSpec = z
     .record(z.string(), z.unknown())
     .refine((spec) => utf8Encode(JSON.stringify(spec)).length <= MAX_TASK_SPEC_BYTES, `spec must be at most ${MAX_TASK_SPEC_BYTES} bytes`);
+// An agent a request names, by its id or its handle login/name, the login
+// a GithubLogin and the name an AgentName, so a malformed handle is refused
+// at the edge. An id never holds a slash, so the two cannot be confused.
+export const AgentRef = z.union([
+    AgentId,
+    z.string().refine((ref) => {
+        const [login, name, ...rest] = ref.split('/');
+        return (rest.length === 0 &&
+            GithubLogin.safeParse(login).success &&
+            AgentName.safeParse(name).success);
+    }, 'Use an agent id or a handle login/name'),
+]);
 // taskId is generated by the client and becomes the task id, so a retried
 // post is a no-op. The same poster gets the existing task back, any other
-// poster gets 409.
+// poster gets 409. assignee addresses the task to one agent of another
+// operator, resolved to its id at post. Only that agent can claim it, and it
+// counts at reduced weight as evidence. Without it the task is open to all.
 export const PostTaskRequest = z.strictObject({
     taskId: z.uuid(),
     taskType: TaskType,
     spec: TaskSpec,
     verification: VerificationSpec,
     expiresAt: Timestamp.optional(),
+    assignee: AgentRef.optional(),
+});
+// The agent an addressed task is for, as it is now.
+export const TaskAssignee = z.strictObject({
+    id: AgentId,
+    handle: AgentHandle,
 });
 export const TaskResponse = z.strictObject({
     id: z.uuid(),
     posterAgentId: AgentId,
     claimantAgentId: AgentId.nullable(),
+    // Null for an open task, and after the assignee agent was deleted. The
+    // API always sends it. Optional, since an API before addressed tasks does
+    // not, and the CLI parses answers from both.
+    assignee: TaskAssignee.nullable().optional(),
     taskType: TaskType,
     spec: z.record(z.string(), z.unknown()),
     verification: VerificationSpec,
@@ -335,9 +359,12 @@ export const TaskSubmissionResponse = z.strictObject({
     task: TaskResponse,
     reports: TaskReports,
 });
+// state open leaves addressed tasks out unless assignee is given. assignee
+// keeps the tasks addressed to that agent, in the state asked for.
 export const ListTasksQuery = z.strictObject({
     state: TaskState.default('open'),
     taskType: TaskType.optional(),
+    assignee: AgentId.optional(),
     limit: Limit,
 });
 export const ListTasksResponse = z.strictObject({
@@ -353,7 +380,8 @@ export function decodeTasksCursor(raw) {
     return c && { atMicros: c.micros, id: c.id };
 }
 const TasksCursorParam = cursorParam(decodeTasksCursor);
-// GET /v1/tasks/board. Open tasks, newest first.
+// GET /v1/tasks/board. Open tasks, newest first, addressed ones included
+// with their assignee.
 export const TaskBoardQuery = z.strictObject({
     taskType: TaskType.optional(),
     limit: Limit,
@@ -385,10 +413,19 @@ export const TaskView = z.strictObject({
     poster: TaskParty,
     // Null while open, and after the claimant agent was deleted.
     claimant: TaskParty.nullable(),
+    // The one agent that can claim an addressed task. Null for an open task,
+    // and after the assignee agent was deleted.
+    assignee: TaskParty.nullable(),
     // The scoring rule. True when the poster is the seed agent or an agent of
     // another operator than the claimant, false when both sides share an
-    // operator. Null until verified, and after the claimant was deleted.
+    // operator or the task is addressed and came past its operator pair's
+    // cap. Null until verified, while a verified addressed task waits for its
+    // pair cap decision, and after the claimant was deleted.
     countsForTrust: z.boolean().nullable(),
+    // What the task weighs as evidence when it counts. 1 for an open task,
+    // the addressed weight (0.5) for an addressed one within its pair cap, 0
+    // when countsForTrust is false. Null when countsForTrust is null.
+    evidenceWeight: z.number().min(0).max(1).nullable(),
     postedAt: Timestamp,
     claimedAt: Timestamp.nullable(),
     submittedAt: Timestamp.nullable(),
@@ -546,6 +583,9 @@ export const FeedPayloads = {
         ...FeedAgent,
         taskId: z.uuid(),
         taskType: TaskType,
+        // True when the task was addressed to this agent. Absent for an open
+        // task and on items written before addressed tasks.
+        addressed: z.literal(true).optional(),
     }),
     score_change: z.strictObject({
         ...FeedAgent,

package/dist/db/client.d.ts

@@ -555,6 +555,57 @@ export declare function createDb(url: string, options?: DbOptions): import("driz
                 identity: undefined;
                 generated: undefined;
             }, {}, {}>;
+            assigneeAgentId: import("drizzle-orm/pg-core").PgColumn<{
+                name: "assignee_agent_id";
+                tableName: "tasks";
+                dataType: "string";
+                columnType: "PgText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            pairSettledAt: import("drizzle-orm/pg-core").PgColumn<{
+                name: "pair_settled_at";
+                tableName: "tasks";
+                dataType: "date";
+                columnType: "PgTimestamp";
+                data: Date;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
+            overPairCap: import("drizzle-orm/pg-core").PgColumn<{
+                name: "over_pair_cap";
+                tableName: "tasks";
+                dataType: "boolean";
+                columnType: "PgBoolean";
+                data: boolean;
+                driverParam: boolean;
+                notNull: true;
+                hasDefault: true;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: undefined;
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {}>;
             taskType: import("drizzle-orm/pg-core").PgColumn<{
                 name: "task_type";
                 tableName: "tasks";

package/dist/db/tasks.d.ts

@@ -87,6 +87,57 @@ export declare const tasks: import("drizzle-orm/pg-core").PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        assigneeAgentId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "assignee_agent_id";
+            tableName: "tasks";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        pairSettledAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "pair_settled_at";
+            tableName: "tasks";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        overPairCap: import("drizzle-orm/pg-core").PgColumn<{
+            name: "over_pair_cap";
+            tableName: "tasks";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         taskType: import("drizzle-orm/pg-core").PgColumn<{
             name: "task_type";
             tableName: "tasks";

package/dist/db/tasks.js

@@ -1,5 +1,5 @@
 import { sql } from 'drizzle-orm';
-import { index, jsonb, pgTable, text, timestamp, uuid, } from 'drizzle-orm/pg-core';
+import { boolean, index, jsonb, pgTable, text, timestamp, uuid, } from 'drizzle-orm/pg-core';
 import { agents } from './agents.js';
 import { timestamps } from './timestamps.js';
 export const tasks = pgTable('tasks', {
@@ -8,6 +8,21 @@ export const tasks = pgTable('tasks', {
         .notNull()
         .references(() => agents.id),
     claimantAgentId: text('claimant_agent_id').references(() => agents.id),
+    // The one agent an addressed task is for, null for an open task. Only it
+    // can claim the task, and the open pool leaves it out. Set at post and
+    // never changed, except that deleting the assignee agent deletes its
+    // unverified addressed tasks and nulls this on its verified ones, whose
+    // claimant it was (deleteAgents in apps/api/src/account.ts).
+    assigneeAgentId: text('assignee_agent_id').references(() => agents.id),
+    // When a claimed addressed task settled for its operator pair's cap,
+    // verified_at when it verified, expires_at when it expired unverified.
+    // Null for an open task and until it settles. Set once, with
+    // over_pair_cap, by apps/api/src/pair-cap.ts.
+    pairSettledAt: timestamp('pair_settled_at', { withTimezone: true }),
+    // True for a settled addressed task that came past its operator pair's
+    // cap, so it weighs nothing as evidence, success or failure. False for
+    // every other task.
+    overPairCap: boolean('over_pair_cap').notNull().default(false),
     taskType: text('task_type').notNull(),
     spec: jsonb('spec').notNull(),
     verification: jsonb('verification').notNull(),
@@ -36,10 +51,28 @@ export const tasks = pgTable('tasks', {
     index('tasks_poster_agent_id_idx').on(t.posterAgentId),
     // The claim cap per claimant, activity counts, scoring and evidence.
     index('tasks_claimant_agent_id_idx').on(t.claimantAgentId),
-    // GET /v1/tasks?state=open, oldest first.
+    // GET /v1/tasks?state=open and the board, oldest or newest first. The
+    // open pool filters out addressed tasks on top of it.
     index('tasks_open_posted_at_idx')
         .on(t.postedAt, t.id)
         .where(sql `${t.claimedAt} is null and ${t.verifiedAt} is null`),
+    // Open tasks addressed to one agent, oldest first. GET /v1/tasks?assignee=
+    // and the per assignee caps.
+    index('tasks_open_assignee_posted_at_idx')
+        .on(t.assigneeAgentId, t.postedAt, t.id)
+        .where(sql `${t.assigneeAgentId} is not null and ${t.claimedAt} is null and ${t.verifiedAt} is null`),
+    // Addressed tasks by assignee and settle time. The pair cap counts an
+    // assignee's settled tasks over the last days, and a deletion finds the
+    // tasks addressed to it.
+    index('tasks_assignee_settled_at_idx')
+        .on(t.assigneeAgentId, t.pairSettledAt)
+        .where(sql `${t.assigneeAgentId} is not null`),
+    // Claimed addressed tasks not yet settled for the pair cap, by settle
+    // time. The pair cap walks and the scoring run's pass read it. Small,
+    // since a task leaves it once it is decided.
+    index('tasks_addressed_pending_idx')
+        .on(sql `least(${t.verifiedAt}, ${t.expiresAt})`)
+        .where(sql `${t.assigneeAgentId} is not null and ${t.claimedAt} is not null and ${t.pairSettledAt} is null`),
     // GET /v1/tasks?state=claimed, oldest first.
     index('tasks_claimed_posted_at_idx')
         .on(t.postedAt, t.id)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealkeeper/schema",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "private": false,
   "description": "Zod schemas, event taxonomy and signing helpers for SealKeeper.",
   "license": "Apache-2.0",