@sealkeeper/schema 0.4.1 → 0.4.3

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,38 +169,46 @@ 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}$/);
-const CURSOR_TEXT = /^(\d{1,18})\.([A-Za-z0-9_-]{43})$/;
-export function encodeAgentsCursor(cursor) {
-    return base64urlEncode(utf8Encode(`${cursor.createdAtMicros}.${cursor.id}`));
-}
-// Null for anything that is not a cursor this API made.
-export function decodeAgentsCursor(raw) {
-    let text;
-    try {
-        text = utf8Decode(base64urlDecode(raw));
-    }
-    catch {
-        return null;
-    }
-    const m = CURSOR_TEXT.exec(text);
-    if (!m?.[1] || !m[2] || !AgentId.safeParse(m[2]).success)
-        return null;
-    return { createdAtMicros: m[1], id: m[2] };
+function keysetCursor(id, isId = () => true) {
+    const text = new RegExp(`^(\\d{1,18})\\.(${id.source})$`);
+    const encode = (c) => base64urlEncode(utf8Encode(`${c.micros}.${c.id}`));
+    // Null for anything that is not a cursor this API made.
+    const decode = (raw) => {
+        let decoded;
+        try {
+            decoded = utf8Decode(base64urlDecode(raw));
+        }
+        catch {
+            return null;
+        }
+        const m = text.exec(decoded);
+        if (!m?.[1] || !m[2] || !isId(m[2]))
+            return null;
+        return { micros: m[1], id: m[2] };
+    };
+    return { encode, decode };
 }
-export const AgentsCursorParam = z
+// A query parameter that holds a cursor, 400 for one the API did not make.
+const cursorParam = (decode) => z
     .string()
     .max(128)
     .transform((raw, ctx) => {
-    const cursor = decodeAgentsCursor(raw);
+    const cursor = decode(raw);
     if (cursor)
         return cursor;
     ctx.addIssue({ code: 'custom', message: 'Invalid cursor' });
     return z.NEVER;
 });
+const agentsKeyset = keysetCursor(/[A-Za-z0-9_-]{43}/, (id) => AgentId.safeParse(id).success);
+export function encodeAgentsCursor(cursor) {
+    return agentsKeyset.encode({ micros: cursor.createdAtMicros, id: cursor.id });
+}
+// Null for anything that is not a cursor this API made.
+export function decodeAgentsCursor(raw) {
+    const c = agentsKeyset.decode(raw);
+    return c && { createdAtMicros: c.micros, id: c.id };
+}
+export const AgentsCursorParam = cursorParam(decodeAgentsCursor);
 export const AgentsListQuery = z.strictObject({
     limit: Limit,
     cursor: AgentsCursorParam.optional(),
@@ -261,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,
@@ -303,14 +339,104 @@ export const TaskOutcomeRequest = z.strictObject({
     outcome: TaskOutcome,
     evidenceHash: Sha256Hex.optional(),
 });
+// POST /v1/tasks/:id/submission, the poster's signed read of its task with
+// the submission and both outcome reports. The public GET leaves the
+// submission out. issuedAt bounds how long a captured envelope could be sent
+// again, the same window as rename.
+export const TASK_READ_MAX_AGE_SEC = RENAME_MAX_AGE_SEC;
+export const TaskSubmissionRequest = z.strictObject({
+    taskId: z.uuid(),
+    issuedAt: Timestamp,
+});
+// The outcome each side has reported, null until it reports. A new report
+// replaces the old one, so this is the current one.
+export const TaskReports = z.strictObject({
+    poster: TaskOutcome.nullable(),
+    claimant: TaskOutcome.nullable(),
+});
+// task.submission is absent until the claimant submits.
+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({
     tasks: z.array(TaskResponse),
 });
+const tasksKeyset = keysetCursor(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/);
+export function encodeTasksCursor(cursor) {
+    return tasksKeyset.encode({ micros: cursor.atMicros, id: cursor.id });
+}
+// Null for anything that is not a cursor this API made.
+export function decodeTasksCursor(raw) {
+    const c = tasksKeyset.decode(raw);
+    return c && { atMicros: c.micros, id: c.id };
+}
+const TasksCursorParam = cursorParam(decodeTasksCursor);
+// GET /v1/tasks/board. Open tasks, newest first, addressed ones included
+// with their assignee.
+export const TaskBoardQuery = z.strictObject({
+    taskType: TaskType.optional(),
+    limit: Limit,
+    cursor: TasksCursorParam.optional(),
+});
+// GET /v1/agents/:id/tasks. claimant is the tasks the agent completed,
+// verified, newest verified first. poster is every task it posted, newest
+// posted first.
+export const AgentTaskRole = z.enum(['claimant', 'poster']);
+export const AgentTasksQuery = z.strictObject({
+    role: AgentTaskRole,
+    limit: Limit,
+    cursor: TasksCursorParam.optional(),
+});
+// One side of a task, as it is now.
+export const TaskParty = z.strictObject({
+    id: AgentId,
+    handle: AgentHandle,
+    // True for an agent SealKeeper runs itself, the seed agent.
+    operatedBySealKeeper: z.boolean(),
+});
+export const TaskView = z.strictObject({
+    id: z.uuid(),
+    taskType: TaskType,
+    spec: z.record(z.string(), z.unknown()),
+    // The public spec, never the full schema.
+    verification: VerificationSpec,
+    state: TaskState,
+    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 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(),
+    verifiedAt: Timestamp.nullable(),
+    expiresAt: Timestamp,
+});
+// nextCursor is null on the last page.
+export const TaskViewsResponse = z.strictObject({
+    tasks: z.array(TaskView),
+    nextCursor: z.string().nullable(),
+});
 // The body of a signed rating. A rating payload is small, so it takes the
 // event envelope cap.
 export const SignedRatingRequest = z.strictObject({
@@ -429,12 +555,22 @@ export const LeaderboardResponse = z.strictObject({
 export const FeedKind = z.enum([
     'registration',
     'task_verified',
+    // No longer written since VOU-125. Kept so old rows still parse and render.
     'score_change',
     'flag',
     'version_change',
+    'level_change',
+    'milestone',
 ]);
 // The one flag code today. Two sides of a counterparty task disagreed.
 export const FeedFlagCode = z.enum(['outcome_disagreement']);
+// Milestones an agent passes once. Its first SEAL level above none, then
+// 100 and 1,000 verified tasks.
+export const FeedMilestone = z.enum([
+    'first_seal',
+    'verified_100',
+    'verified_1000',
+]);
 // name is the agent's name when the item was written. The item's handle
 // is the agent as it is now.
 const FeedAgent = {
@@ -447,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,
@@ -468,6 +607,21 @@ export const FeedPayloads = {
         old: Version,
         new: Version,
     }),
+    // The scoring run moved the level of the agent's current version, up or
+    // down. The first move above none is a first_seal milestone instead.
+    level_change: z.strictObject({
+        ...FeedAgent,
+        version: Version,
+        old: Level,
+        new: Level,
+    }),
+    // level is the current version's level when the milestone was passed.
+    milestone: z.strictObject({
+        ...FeedAgent,
+        version: Version,
+        milestone: FeedMilestone,
+        level: Level,
+    }),
 };
 const feedItemOf = (kind) => z.strictObject({
     // The SSE event id. Ascending in insert order.
@@ -487,6 +641,8 @@ export const FeedItem = z.discriminatedUnion('kind', [
     feedItemOf('score_change'),
     feedItemOf('flag'),
     feedItemOf('version_change'),
+    feedItemOf('level_change'),
+    feedItemOf('milestone'),
 ]);
 export const FEED_RECENT_MAX = 200;
 export const FeedRecentQuery = z.strictObject({

package/dist/db/agent-milestones.d.ts

@@ -0,0 +1,75 @@
+export declare const agentMilestones: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "agent_milestones";
+    schema: undefined;
+    columns: {
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "agent_milestones";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "updated_at";
+            tableName: "agent_milestones";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        agentId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "agent_id";
+            tableName: "agent_milestones";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        milestone: import("drizzle-orm/pg-core").PgColumn<{
+            name: "milestone";
+            tableName: "agent_milestones";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>;

package/dist/db/agent-milestones.js

@@ -0,0 +1,16 @@
+import { pgTable, primaryKey, text } from 'drizzle-orm/pg-core';
+import { agents } from './agents.js';
+import { timestamps } from './timestamps.js';
+// The feed milestones an agent has reached, one row per (agent, milestone).
+// The scoring run writes a milestone to the feed only when it has no row
+// here, so each is written once per agent, ever. Migration 0019 seeded it
+// from standing, so an agent that already stood above none, or already
+// passed a verified task count, before milestones existed is not told it
+// did so for the first time.
+export const agentMilestones = pgTable('agent_milestones', {
+    agentId: text('agent_id')
+        .notNull()
+        .references(() => agents.id),
+    milestone: text('milestone').notNull(),
+    ...timestamps,
+}, (t) => [primaryKey({ columns: [t.agentId, t.milestone] })]);

package/dist/db/agents.d.ts

@@ -138,6 +138,57 @@ export declare const agents: import("drizzle-orm/pg-core").PgTableWithColumns<{
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        dirtySince: import("drizzle-orm/pg-core").PgColumn<{
+            name: "dirty_since";
+            tableName: "agents";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        dirtyGen: import("drizzle-orm/pg-core").PgColumn<{
+            name: "dirty_gen";
+            tableName: "agents";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        recomputeAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "recompute_at";
+            tableName: "agents";
+            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;
+        }, {}, {}>;
     };
     dialect: 'pg';
 }>;

package/dist/db/agents.js

@@ -1,5 +1,5 @@
 import { sql } from 'drizzle-orm';
-import { check, jsonb, pgTable, text, timestamp, uniqueIndex, uuid, } from 'drizzle-orm/pg-core';
+import { bigint, check, index, jsonb, pgTable, text, timestamp, uniqueIndex, uuid, } from 'drizzle-orm/pg-core';
 import { operators } from './operators.js';
 import { timestamps } from './timestamps.js';
 // How a Drizzle table is declared.
@@ -31,10 +31,31 @@ export const agents = pgTable('agents', {
     // sent again cannot move the version back.
     versionIssuedAt: timestamp('version_issued_at', { withTimezone: true }),
     card: jsonb('card'),
+    // When the agent was first marked dirty since the scoring run last
+    // cleared it. Every write that can move the agent's standing marks it,
+    // in the same transaction as that write, but a mark sets this only when
+    // it is null, so an agent that keeps being marked keeps its place in the
+    // run's queue. defaultNow, so a new agent starts dirty and migration
+    // 0018 backfilled every existing agent. Not a row timestamp, the scoring
+    // run owns it.
+    dirtySince: timestamp('dirty_since', { withTimezone: true }).defaultNow(),
+    // Bumped by every mark. The run reads it when it selects the agent and
+    // clears dirty_since only where it is unchanged, so a mark that commits
+    // mid run survives (migration 0019).
+    dirtyGen: bigint('dirty_gen', { mode: 'number' }).notNull().default(0),
+    // The earliest future moment time alone can change this agent's
+    // standing, a dormancy rung or evidence leaving the window. Written by
+    // the scoring run only, null when nothing is due.
+    recomputeAt: timestamp('recompute_at', { withTimezone: true }),
     ...timestamps,
 }, (t) => [
     check('agents_id_length', sql `length(${t.id}) = 43`),
     // The handle login/name points at one agent. Names are lowercase, so a
     // plain unique index is enough.
     uniqueIndex('agents_operator_name_unique').on(t.operatorId, t.name),
+    // The scoring run selects agents that are dirty or due.
+    index('agents_recompute_at_idx').on(t.recomputeAt),
+    index('agents_dirty_since_idx')
+        .on(t.dirtySince)
+        .where(sql `${t.dirtySince} is not null`),
 ]);