@sealkeeper/schema 0.4.1 → 0.4.2

package/dist/api.d.ts

@@ -330,6 +330,65 @@ export declare const TaskOutcomeRequest: z.ZodObject<{
     evidenceHash: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type TaskOutcomeRequest = z.infer<typeof TaskOutcomeRequest>;
+export declare const TASK_READ_MAX_AGE_SEC = 300;
+export declare const TaskSubmissionRequest: z.ZodObject<{
+    taskId: z.ZodUUID;
+    issuedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type TaskSubmissionRequest = z.infer<typeof TaskSubmissionRequest>;
+export declare const TaskReports: z.ZodObject<{
+    poster: z.ZodNullable<z.ZodEnum<{
+        failure: "failure";
+        success: "success";
+    }>>;
+    claimant: z.ZodNullable<z.ZodEnum<{
+        failure: "failure";
+        success: "success";
+    }>>;
+}, z.core.$strict>;
+export type TaskReports = z.infer<typeof TaskReports>;
+export declare const TaskSubmissionResponse: z.ZodObject<{
+    task: z.ZodObject<{
+        id: z.ZodUUID;
+        posterAgentId: z.ZodString;
+        claimantAgentId: z.ZodNullable<z.ZodString>;
+        taskType: z.ZodString;
+        spec: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        verification: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"hash">;
+            sha256: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"schema">;
+            jsonSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"counterparty">;
+        }, z.core.$strict>], "kind">;
+        state: z.ZodEnum<{
+            claimed: "claimed";
+            expired: "expired";
+            open: "open";
+            submitted: "submitted";
+            verified: "verified";
+        }>;
+        postedAt: z.ZodISODateTime;
+        claimedAt: z.ZodNullable<z.ZodISODateTime>;
+        submittedAt: z.ZodNullable<z.ZodISODateTime>;
+        verifiedAt: z.ZodNullable<z.ZodISODateTime>;
+        expiresAt: z.ZodISODateTime;
+        submission: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    reports: z.ZodObject<{
+        poster: z.ZodNullable<z.ZodEnum<{
+            failure: "failure";
+            success: "success";
+        }>>;
+        claimant: z.ZodNullable<z.ZodEnum<{
+            failure: "failure";
+            success: "success";
+        }>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type TaskSubmissionResponse = z.infer<typeof TaskSubmissionResponse>;
 export declare const ListTasksQuery: z.ZodObject<{
     state: z.ZodDefault<z.ZodEnum<{
         claimed: "claimed";
@@ -374,6 +433,117 @@ export declare const ListTasksResponse: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ListTasksResponse = z.infer<typeof ListTasksResponse>;
+export type TasksCursor = {
+    atMicros: string;
+    id: string;
+};
+export declare function encodeTasksCursor(cursor: TasksCursor): string;
+export declare function decodeTasksCursor(raw: string): TasksCursor | null;
+export declare const TaskBoardQuery: z.ZodObject<{
+    taskType: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<TasksCursor, string>>>;
+}, z.core.$strict>;
+export type TaskBoardQuery = z.infer<typeof TaskBoardQuery>;
+export declare const AgentTaskRole: z.ZodEnum<{
+    claimant: "claimant";
+    poster: "poster";
+}>;
+export type AgentTaskRole = z.infer<typeof AgentTaskRole>;
+export declare const AgentTasksQuery: z.ZodObject<{
+    role: z.ZodEnum<{
+        claimant: "claimant";
+        poster: "poster";
+    }>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<TasksCursor, string>>>;
+}, z.core.$strict>;
+export type AgentTasksQuery = z.infer<typeof AgentTasksQuery>;
+export declare const TaskParty: z.ZodObject<{
+    id: z.ZodString;
+    handle: z.ZodString;
+    operatedBySealKeeper: z.ZodBoolean;
+}, z.core.$strict>;
+export type TaskParty = z.infer<typeof TaskParty>;
+export declare const TaskView: z.ZodObject<{
+    id: z.ZodUUID;
+    taskType: z.ZodString;
+    spec: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    verification: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"hash">;
+        sha256: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"schema">;
+        jsonSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"counterparty">;
+    }, z.core.$strict>], "kind">;
+    state: z.ZodEnum<{
+        claimed: "claimed";
+        expired: "expired";
+        open: "open";
+        submitted: "submitted";
+        verified: "verified";
+    }>;
+    poster: z.ZodObject<{
+        id: z.ZodString;
+        handle: z.ZodString;
+        operatedBySealKeeper: z.ZodBoolean;
+    }, z.core.$strict>;
+    claimant: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        handle: z.ZodString;
+        operatedBySealKeeper: z.ZodBoolean;
+    }, z.core.$strict>>;
+    countsForTrust: z.ZodNullable<z.ZodBoolean>;
+    postedAt: z.ZodISODateTime;
+    claimedAt: z.ZodNullable<z.ZodISODateTime>;
+    submittedAt: z.ZodNullable<z.ZodISODateTime>;
+    verifiedAt: z.ZodNullable<z.ZodISODateTime>;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type TaskView = z.infer<typeof TaskView>;
+export declare const TaskViewsResponse: z.ZodObject<{
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        taskType: z.ZodString;
+        spec: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        verification: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"hash">;
+            sha256: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"schema">;
+            jsonSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"counterparty">;
+        }, z.core.$strict>], "kind">;
+        state: z.ZodEnum<{
+            claimed: "claimed";
+            expired: "expired";
+            open: "open";
+            submitted: "submitted";
+            verified: "verified";
+        }>;
+        poster: z.ZodObject<{
+            id: z.ZodString;
+            handle: z.ZodString;
+            operatedBySealKeeper: z.ZodBoolean;
+        }, z.core.$strict>;
+        claimant: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            handle: z.ZodString;
+            operatedBySealKeeper: z.ZodBoolean;
+        }, z.core.$strict>>;
+        countsForTrust: z.ZodNullable<z.ZodBoolean>;
+        postedAt: z.ZodISODateTime;
+        claimedAt: z.ZodNullable<z.ZodISODateTime>;
+        submittedAt: z.ZodNullable<z.ZodISODateTime>;
+        verifiedAt: z.ZodNullable<z.ZodISODateTime>;
+        expiresAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type TaskViewsResponse = z.infer<typeof TaskViewsResponse>;
 export declare const SignedRatingRequest: z.ZodObject<{
     envelope: z.ZodString;
 }, z.core.$strict>;
@@ -703,6 +873,8 @@ export declare const LeaderboardResponse: z.ZodObject<{
 export type LeaderboardResponse = z.infer<typeof LeaderboardResponse>;
 export declare const FeedKind: z.ZodEnum<{
     flag: "flag";
+    level_change: "level_change";
+    milestone: "milestone";
     registration: "registration";
     score_change: "score_change";
     task_verified: "task_verified";
@@ -713,6 +885,12 @@ export declare const FeedFlagCode: z.ZodEnum<{
     outcome_disagreement: "outcome_disagreement";
 }>;
 export type FeedFlagCode = z.infer<typeof FeedFlagCode>;
+export declare const FeedMilestone: z.ZodEnum<{
+    first_seal: "first_seal";
+    verified_100: "verified_100";
+    verified_1000: "verified_1000";
+}>;
+export type FeedMilestone = z.infer<typeof FeedMilestone>;
 export declare const FeedPayloads: {
     registration: z.ZodObject<{
         agentId: z.ZodString;
@@ -752,6 +930,39 @@ export declare const FeedPayloads: {
         old: z.ZodString;
         new: z.ZodString;
     }, z.core.$strict>;
+    level_change: z.ZodObject<{
+        agentId: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodString;
+        old: z.ZodEnum<{
+            bronze: "bronze";
+            gold: "gold";
+            none: "none";
+            silver: "silver";
+        }>;
+        new: z.ZodEnum<{
+            bronze: "bronze";
+            gold: "gold";
+            none: "none";
+            silver: "silver";
+        }>;
+    }, z.core.$strict>;
+    milestone: z.ZodObject<{
+        agentId: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodString;
+        milestone: z.ZodEnum<{
+            first_seal: "first_seal";
+            verified_100: "verified_100";
+            verified_1000: "verified_1000";
+        }>;
+        level: z.ZodEnum<{
+            bronze: "bronze";
+            gold: "gold";
+            none: "none";
+            silver: "silver";
+        }>;
+    }, z.core.$strict>;
 };
 export type FeedPayload<K extends FeedKind> = z.infer<(typeof FeedPayloads)[K]>;
 export declare const FeedItem: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -837,6 +1048,57 @@ export declare const FeedItem: z.ZodDiscriminatedUnion<[z.ZodObject<{
         new: z.ZodString;
     }, z.core.$strict>;
     createdAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodInt;
+    kind: z.ZodLiteral<"level_change">;
+    agentId: z.ZodNullable<z.ZodString>;
+    operator: z.ZodObject<{
+        login: z.ZodString;
+    }, z.core.$strict>;
+    handle: z.ZodString;
+    payload: z.ZodObject<{
+        agentId: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodString;
+        old: z.ZodEnum<{
+            bronze: "bronze";
+            gold: "gold";
+            none: "none";
+            silver: "silver";
+        }>;
+        new: z.ZodEnum<{
+            bronze: "bronze";
+            gold: "gold";
+            none: "none";
+            silver: "silver";
+        }>;
+    }, z.core.$strict>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodInt;
+    kind: z.ZodLiteral<"milestone">;
+    agentId: z.ZodNullable<z.ZodString>;
+    operator: z.ZodObject<{
+        login: z.ZodString;
+    }, z.core.$strict>;
+    handle: z.ZodString;
+    payload: z.ZodObject<{
+        agentId: z.ZodString;
+        name: z.ZodString;
+        version: z.ZodString;
+        milestone: z.ZodEnum<{
+            first_seal: "first_seal";
+            verified_100: "verified_100";
+            verified_1000: "verified_1000";
+        }>;
+        level: z.ZodEnum<{
+            bronze: "bronze";
+            gold: "gold";
+            none: "none";
+            silver: "silver";
+        }>;
+    }, z.core.$strict>;
+    createdAt: z.ZodISODateTime;
 }, z.core.$strict>], "kind">;
 export type FeedItem = z.infer<typeof FeedItem>;
 export declare const FEED_RECENT_MAX = 200;
@@ -928,6 +1190,57 @@ export declare const FeedRecentResponse: z.ZodObject<{
             new: z.ZodString;
         }, z.core.$strict>;
         createdAt: z.ZodISODateTime;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodInt;
+        kind: z.ZodLiteral<"level_change">;
+        agentId: z.ZodNullable<z.ZodString>;
+        operator: z.ZodObject<{
+            login: z.ZodString;
+        }, z.core.$strict>;
+        handle: z.ZodString;
+        payload: z.ZodObject<{
+            agentId: z.ZodString;
+            name: z.ZodString;
+            version: z.ZodString;
+            old: z.ZodEnum<{
+                bronze: "bronze";
+                gold: "gold";
+                none: "none";
+                silver: "silver";
+            }>;
+            new: z.ZodEnum<{
+                bronze: "bronze";
+                gold: "gold";
+                none: "none";
+                silver: "silver";
+            }>;
+        }, z.core.$strict>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodInt;
+        kind: z.ZodLiteral<"milestone">;
+        agentId: z.ZodNullable<z.ZodString>;
+        operator: z.ZodObject<{
+            login: z.ZodString;
+        }, z.core.$strict>;
+        handle: z.ZodString;
+        payload: z.ZodObject<{
+            agentId: z.ZodString;
+            name: z.ZodString;
+            version: z.ZodString;
+            milestone: z.ZodEnum<{
+                first_seal: "first_seal";
+                verified_100: "verified_100";
+                verified_1000: "verified_1000";
+            }>;
+            level: z.ZodEnum<{
+                bronze: "bronze";
+                gold: "gold";
+                none: "none";
+                silver: "silver";
+            }>;
+        }, z.core.$strict>;
+        createdAt: z.ZodISODateTime;
     }, z.core.$strict>], "kind">>;
 }, z.core.$strict>;
 export type FeedRecentResponse = z.infer<typeof FeedRecentResponse>;

package/dist/api.js

@@ -169,34 +169,46 @@ export const AgentRenamedResponse = z.strictObject({
 // 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(),
@@ -303,6 +315,26 @@ 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,
+});
 export const ListTasksQuery = z.strictObject({
     state: TaskState.default('open'),
     taskType: TaskType.optional(),
@@ -311,6 +343,63 @@ export const ListTasksQuery = z.strictObject({
 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.
+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 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.
+    countsForTrust: z.boolean().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 +518,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 = {
@@ -468,6 +567,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 +601,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`),
 ]);

package/dist/db/client.d.ts

@@ -252,6 +252,57 @@ export declare function createDb(url: string, options?: DbOptions): import("driz
                 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';
     }>;
@@ -1814,6 +1865,81 @@ export declare function createDb(url: string, options?: DbOptions): import("driz
         };
         dialect: 'pg';
     }>;
+    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';
+    }>;
     deletedOperators: import("drizzle-orm/pg-core").PgTableWithColumns<{
         name: "deleted_operators";
         schema: undefined;

package/dist/db/client.js

@@ -1,5 +1,6 @@
 import { drizzle } from 'drizzle-orm/postgres-js';
 import postgres from 'postgres';
+import { agentMilestones } from './agent-milestones.js';
 import { agentRenames } from './agent-renames.js';
 import { agents } from './agents.js';
 import { credentials } from './credentials.js';
@@ -27,6 +28,7 @@ const schema = {
     quotaCounters,
     feedItems,
     agentRenames,
+    agentMilestones,
     deletedOperators,
 };
 export function createDb(url, options = {}) {

package/dist/db/feed-items.js

@@ -13,4 +13,9 @@ export const feedItems = pgTable('feed_items', {
     agentId: text('agent_id').references(() => agents.id),
     payload: jsonb('payload').notNull(),
     ...timestamps,
-}, (t) => [index('feed_items_created_at_idx').on(t.createdAt)]);
+}, (t) => [
+    index('feed_items_created_at_idx').on(t.createdAt),
+    // Milestones are written once per agent, and deleting an agent removes
+    // its items. Both look up by agent and kind.
+    index('feed_items_agent_id_kind_idx').on(t.agentId, t.kind),
+]);

package/dist/db/index.d.ts

@@ -1,3 +1,4 @@
+import type { agentMilestones } from './agent-milestones.js';
 import type { agentRenames } from './agent-renames.js';
 import type { credentials } from './credentials.js';
 import type { deletedOperators } from './deleted-operators.js';
@@ -10,8 +11,9 @@ import type { scores } from './scores.js';
 import type { standing } from './standing.js';
 import type { taskOutcomes } from './task-outcomes.js';
 import type { tasks } from './tasks.js';
-export { and, asc, desc, eq, gt, inArray, isNotNull, isNull, lt, lte, max, ne, notInArray, or, sql, } from 'drizzle-orm';
+export { and, asc, desc, eq, gt, inArray, isNotNull, isNull, lt, lte, max, ne, notInArray, or, type SQL, sql, } from 'drizzle-orm';
 export { DrizzleQueryError } from 'drizzle-orm/errors';
+export { agentMilestones } from './agent-milestones.js';
 export { agentRenames } from './agent-renames.js';
 export type { Agent, NewAgent } from './agents.js';
 export { agents } from './agents.js';
@@ -52,5 +54,7 @@ export type AgentRename = typeof agentRenames.$inferSelect;
 export type NewAgentRename = typeof agentRenames.$inferInsert;
 export type FeedItem = typeof feedItems.$inferSelect;
 export type NewFeedItem = typeof feedItems.$inferInsert;
+export type AgentMilestone = typeof agentMilestones.$inferSelect;
+export type NewAgentMilestone = typeof agentMilestones.$inferInsert;
 export type DeletedOperator = typeof deletedOperators.$inferSelect;
 export type NewDeletedOperator = typeof deletedOperators.$inferInsert;

package/dist/db/index.js

@@ -4,6 +4,7 @@ export { and, asc, desc, eq, gt, inArray, isNotNull, isNull, lt, lte, max, ne, n
 // What every failed query throws. Its message holds the SQL and every bound
 // param, so the API error log must never print it.
 export { DrizzleQueryError } from 'drizzle-orm/errors';
+export { agentMilestones } from './agent-milestones.js';
 export { agentRenames } from './agent-renames.js';
 export { agents } from './agents.js';
 export { createDb } from './client.js';

package/dist/envelope.d.ts

@@ -14,3 +14,14 @@ export declare function verify(jws: string, publicKey: Uint8Array): Promise<{
     header: JwsHeader;
     payload: unknown;
 }>;
+export declare const Audience: z.ZodString;
+export declare function audienceOf(apiUrl: string): string;
+export declare function withAudience<T extends object>(payload: T, aud: string): T & {
+    aud: string;
+};
+export declare function signRequest(payload: object, privateKey: Uint8Array, kid: string, aud: string): Promise<string>;
+export type AudienceCheck = {
+    result: 'match' | 'missing' | 'wrong';
+    payload: unknown;
+};
+export declare function readAudience(payload: unknown, accepted: readonly string[]): AudienceCheck;

package/dist/envelope.js

@@ -68,3 +68,73 @@ export async function verify(jws, publicKey) {
     const header = parseHeader(parts.header);
     return { header, payload: parseJson(parts.payload, 'payload') };
 }
+// Signed request audience (VOU-111). Every agent-signed request names the
+// API it is meant for with `aud`, a top level key inside the signed payload,
+// so a request captured for one API cannot be replayed to another. SEALs
+// carry `iss` instead and do not use this.
+function isHttpOrigin(v) {
+    try {
+        const url = new URL(v);
+        return ((url.protocol === 'http:' || url.protocol === 'https:') &&
+            url.origin === v);
+    }
+    catch {
+        return false;
+    }
+}
+// An origin with no trailing slash, no path, a lowercase host and no default
+// port, such as https://api.sealkeeper.run.
+export const Audience = z
+    .string()
+    .max(256)
+    .refine(isHttpOrigin, 'aud must be an origin such as https://api.sealkeeper.run');
+// The audience for an API base URL, its origin.
+export function audienceOf(apiUrl) {
+    let url;
+    try {
+        url = new URL(apiUrl);
+    }
+    catch {
+        throw new EnvelopeError('API URL is not a URL');
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new EnvelopeError('API URL must be http or https');
+    }
+    if (url.origin === 'null') {
+        throw new EnvelopeError('API URL has no origin');
+    }
+    return url.origin;
+}
+// A copy of the payload with `aud` added. Never mutates the input.
+export function withAudience(payload, aud) {
+    if (!Audience.safeParse(aud).success) {
+        throw new EnvelopeError('aud must be an origin');
+    }
+    if (Array.isArray(payload)) {
+        throw new EnvelopeError('A signed request payload must be an object');
+    }
+    if (Object.hasOwn(payload, 'aud')) {
+        throw new EnvelopeError('Payload already has an aud');
+    }
+    return { ...payload, aud };
+}
+// How every agent-signed request is signed. The payload gains `aud` inside
+// the signed bytes. `sign` stays for SEALs, which carry `iss`.
+export async function signRequest(payload, privateKey, kid, aud) {
+    return sign(withAudience(payload, aud), privateKey, kid);
+}
+// Read `aud` off a verified payload. Call only after `verify`. The compare
+// is exact, the received value is never normalised. A payload that is not a
+// plain object comes back unchanged as missing, so the request schema still
+// rejects it.
+export function readAudience(payload, accepted) {
+    if (typeof payload !== 'object' ||
+        payload === null ||
+        Array.isArray(payload) ||
+        !Object.hasOwn(payload, 'aud')) {
+        return { result: 'missing', payload };
+    }
+    const { aud, ...rest } = payload;
+    const match = typeof aud === 'string' && accepted.includes(aud);
+    return { result: match ? 'match' : 'wrong', payload: rest };
+}

package/package.json

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