@sealkeeper/schema 0.4.4 → 0.4.6

package/dist/goal.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { AgentId } from './agent-id.js';
 import { Version } from './events.js';
-import { Level } from './standing.js';
+import { LADDER, Level } from './standing.js';
 // GET /v1/agents/:id/goal. What the agent's current version needs for its
 // next level, threshold by threshold, and what to do next. The API sends
 // these strictly. A client parses them loosely (packages/cli/src/responses.ts),
@@ -15,6 +15,11 @@ export const GOAL_ACTION_CODES = [
     // The agent has sent nothing accepted for a while and its level drops.
     // count is the dormant days.
     'dormant',
+    // The operator's verified domain was missing at its last check and the
+    // grace is running (VOU-185). operator_verified, which gold needs, goes
+    // false when it ends. count is the whole days left and until the moment
+    // it ends. Sent at any level.
+    'operator_verification_lapsing',
     // Counterparty tasks this agent claimed wait for its outcome report. A
     // confirmed task counts for its claimant, so this counts toward the
     // agent's own level. count is how many.
@@ -22,10 +27,12 @@ export const GOAL_ACTION_CODES = [
     // Tasks addressed to this agent are waiting to be claimed. count is how
     // many.
     'addressed_waiting',
-    // Verified seed tasks still needed for bronze. Only ever toward bronze.
+    // Verified tasks still needed. Seed tasks count toward it at every level
+    // (VOU-172). count is how many.
     'claim_seed_tasks',
-    // Verified tasks from other operators' agents still needed. count is the
-    // larger gap of the task thresholds it covers.
+    // Verified tasks from other operators' agents still needed. No threshold
+    // sends it since VOU-172, where seed tasks count at every level. Kept so
+    // a client that knows it keeps working.
     'claim_tasks',
     // Confirmed counterparty tasks with other operators still needed.
     'counterparty_tasks',
@@ -38,11 +45,15 @@ export const GOAL_ACTION_CODES = [
     'safety_below',
     // An incident in the window. count is the incidents counted.
     'safety_incident_window',
+    // Gold's clean record, days since the later of the first accepted event
+    // and the last incident, is short. count is the days still to go.
+    'clean_days',
     // The version's share of the agent's events is under the threshold.
     'provenance_below',
     // No model declared on the card or in a usage event.
     'declare_model',
-    // Operator identity not verified beyond a GitHub login.
+    // Operator identity not verified beyond a GitHub login. The operator
+    // verifies a domain on the account page (VOU-185).
     'operator_unverified',
     // Ratings from silver or gold agents still needed.
     'need_ratings',
@@ -50,6 +61,10 @@ export const GOAL_ACTION_CODES = [
     // version, and the new version's level is capped one below that
     // version's until its own record earns it.
     'version_cap',
+    // Every silver threshold holds, and the operator's silver slots are all
+    // taken (OPERATOR_SILVER_CAP), so the agent is held at bronze. count is
+    // the whole days until the next slot frees and until the moment it does.
+    'operator_silver_cap',
     // Counterparty tasks this agent posted wait for its outcome report. It
     // helps the claimant, the other agent, and adds nothing to this agent's
     // level, so it comes after every step that does. count is how many.
@@ -71,17 +86,59 @@ export const GoalThreshold = z.strictObject({
     raw: z.number().nullable(),
 });
 // One next step. code is machine readable, count what is left where a
-// number says it, else null.
+// number says it, else null. until is when the step clears by itself, sent
+// only with operator_silver_cap. Clients parse actions loosely, so one
+// that does not know until ignores it.
 export const GoalAction = z.strictObject({
     code: z.string().min(1).max(64),
     count: Count.nullable(),
+    until: z.iso.datetime().optional(),
+});
+// Where one level of LADDER stands for the agent. reached is the stored
+// level and every level below it. next is the issued level above it, the
+// same as nextLevel. locked is an issued level above next. reserved is a
+// level the standard names and does not issue yet (platinum), whatever the
+// agent has, so a client shows it as coming later.
+export const GOAL_LADDER_STATES = [
+    'reached',
+    'next',
+    'locked',
+    'reserved',
+];
+export const GoalLadderState = z.enum(GOAL_LADDER_STATES);
+// One entry per LADDER level, lowest first.
+export const GoalLadderStep = z.strictObject({
+    level: z.enum(LADDER.map((s) => s.level)),
+    state: GoalLadderState,
+});
+// One item of gold's checklist. code is the name of the gold threshold it
+// stands for (GoalThreshold.name), done whether it holds. progress is
+// current of required where the rule has a number, null for a flag such as
+// operator_verified. For clean_days that reads as "Safety record, 72 of 180
+// days", for history_days as "Active on 41 of 60 days".
+export const GoalStep = z.strictObject({
+    code: z.string().min(1).max(64),
+    done: z.boolean(),
+    progress: z
+        .strictObject({
+        current: z.number(),
+        required: z.number(),
+    })
+        .nullable(),
 });
 // level and the thresholds come from the standing row of the current
-// version, so they match the SEAL. nextLevel is null at gold, with no
-// thresholds. pending is live (GoalPending). asOf is the scoring run the numbers come from, null before
-// the first. today is live too, the agent's verified tasks of the current
-// UTC day that count toward its level, at most ceiling, and what is left.
-// A task past the ceiling still verifies and shows, and counts for nothing.
+// version, so they match the SEAL. nextLevel is the issued level above
+// level. null means no issued level is above it, not that level is the top
+// of the ladder, since a reserved level (platinum) can sit above. A client
+// from before the ladder (CLI 0.4.x) reads null as nothing left to do, so
+// null stays at gold. thresholds are every rule of nextLevel, none when it
+// is null. ladder is every LADDER level with its state. steps is gold's
+// checklist, sent when nextLevel is gold and empty otherwise, the step-ups
+// first. pending is live (GoalPending). asOf is the scoring run the numbers
+// come from, null before the first. today is live too, the agent's verified
+// tasks of the current UTC day that count toward its level, at most
+// ceiling, and what is left. A task past the ceiling still verifies and
+// shows, and counts for nothing.
 export const GoalToday = z.strictObject({
     // The UTC day, YYYY-MM-DD, so a cached answer from another day is known.
     day: z.iso.date(),
@@ -104,7 +161,9 @@ export const GoalResponse = z.strictObject({
     version: Version,
     level: Level,
     nextLevel: Level.nullable(),
+    ladder: z.array(GoalLadderStep),
     thresholds: z.array(GoalThreshold),
+    steps: z.array(GoalStep),
     actions: z.array(GoalAction),
     pending: GoalPending,
     today: GoalToday,

package/dist/index.d.ts

@@ -1,12 +1,19 @@
 export * from './agent-id.js';
 export * from './agent-name.js';
 export * from './api.js';
+export * from './badge.js';
 export * from './base64url.js';
+export * from './client-address.js';
 export * from './credential.js';
 export * from './dimensions.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './goal.js';
+export * from './json-shape.js';
+export * from './moderation.js';
+export * from './operator-domains.js';
+export * from './policy.js';
+export * from './runtime.js';
 export * from './standing.js';
 export * from './tasks.js';
 export * from './top-dimensions.js';

package/dist/index.js

@@ -1,12 +1,19 @@
 export * from './agent-id.js';
 export * from './agent-name.js';
 export * from './api.js';
+export * from './badge.js';
 export * from './base64url.js';
+export * from './client-address.js';
 export * from './credential.js';
 export * from './dimensions.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './goal.js';
+export * from './json-shape.js';
+export * from './moderation.js';
+export * from './operator-domains.js';
+export * from './policy.js';
+export * from './runtime.js';
 export * from './standing.js';
 export * from './tasks.js';
 export * from './top-dimensions.js';

package/dist/json-shape.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export type JsonShapeLimits = {
+    readonly maxDepth: number;
+    readonly maxKeys: number;
+    readonly maxBytes: number;
+};
+export type JsonShapeIssue = 'too_deep' | 'too_many_keys';
+export declare function jsonShapeIssue(value: unknown, limits: Pick<JsonShapeLimits, 'maxDepth' | 'maxKeys'>): JsonShapeIssue | null;
+export declare function boundedJsonObject(name: string, limits: JsonShapeLimits): z.ZodRecord<z.ZodString, z.ZodUnknown>;

package/dist/json-shape.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { utf8Encode } from './base64url.js';
+/*
+ * The first depth or key count limit a JSON value breaks, or null when it
+ * keeps to both.
+ *
+ * Walks with its own stack rather than recursing, so a value nested
+ * thousands deep cannot overflow the call stack, and stops at the first
+ * breach. Run it before JSON.stringify on anything a caller sent.
+ * stringify recurses and throws RangeError past about 7,700 levels, and
+ * indented output grows with the square of the depth (VOU-214).
+ */
+export function jsonShapeIssue(value, limits) {
+    const stack = [];
+    const push = (v, depth) => {
+        if (typeof v === 'object' && v !== null)
+            stack.push({ node: v, depth });
+    };
+    push(value, 1);
+    let keys = 0;
+    for (let top = stack.pop(); top !== undefined; top = stack.pop()) {
+        if (top.depth > limits.maxDepth)
+            return 'too_deep';
+        let children;
+        if (Array.isArray(top.node)) {
+            children = top.node;
+        }
+        else {
+            children = Object.values(top.node);
+            keys += children.length;
+            if (keys > limits.maxKeys)
+                return 'too_many_keys';
+        }
+        for (const child of children)
+            push(child, top.depth + 1);
+    }
+    return null;
+}
+/*
+ * A JSON object held to the limits. The depth and key checks run first, so
+ * the byte check only ever stringifies a value that cannot throw, and a
+ * breach is a Zod issue (a 400 at the API), never a RangeError (a 500).
+ * superRefine is used rather than refine so each breach gets its own
+ * message and the byte check can be skipped once one is found.
+ */
+export function boundedJsonObject(name, limits) {
+    return z.record(z.string(), z.unknown()).superRefine((value, ctx) => {
+        const issue = jsonShapeIssue(value, limits);
+        if (issue === 'too_deep') {
+            ctx.addIssue({
+                code: 'custom',
+                message: `${name} must nest at most ${limits.maxDepth} levels deep`,
+            });
+            return;
+        }
+        if (issue === 'too_many_keys') {
+            ctx.addIssue({
+                code: 'custom',
+                message: `${name} must have at most ${limits.maxKeys} keys`,
+            });
+            return;
+        }
+        if (utf8Encode(JSON.stringify(value)).length > limits.maxBytes) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `${name} must be at most ${limits.maxBytes} bytes`,
+            });
+        }
+    });
+}

package/dist/moderation.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export declare const OPERATOR_SLUG_MIN = 1;
+export declare const OPERATOR_SLUG_MAX = 39;
+export declare const OPERATOR_DISPLAY_NAME_MIN = 1;
+export declare const OPERATOR_DISPLAY_NAME_MAX = 64;
+export declare const OperatorSlug: z.ZodString;
+export type OperatorSlug = z.infer<typeof OperatorSlug>;
+export declare const OperatorDisplayName: z.ZodString;
+export type OperatorDisplayName = z.infer<typeof OperatorDisplayName>;
+export declare function normaliseName(text: string): string;
+export declare const displayNameKey: typeof normaliseName;
+export declare const PROTECTED_NAMES: readonly string[];
+export declare const PROTECTED_SUFFIXES: readonly string[];
+export declare const PROTECTED_PREFIXES: readonly string[];
+export declare function protectedNameOf(text: string): string | null;
+export declare const RESERVED_WORDS: readonly string[];
+export declare function isReservedWord(text: string): boolean;
+export type NameRefusalCode = 'name_protected' | 'name_reserved' | 'name_mixed_script';
+export type NameRefusal = {
+    code: NameRefusalCode;
+    message: string;
+};
+export declare function moderateSlug(slug: string): NameRefusal | null;
+export declare function mixedScriptOf(text: string): string | null;
+export declare function moderateDisplayName(name: string): NameRefusal | null;
+export declare function slugBase(login: string): string;
+export declare const suffixedSlug: (base: string, n: number) => string;
+export type SlugSuffixReason = 'reserved' | 'protected' | 'taken';
+export declare function slugSuffixReason(login: string, slug: string): SlugSuffixReason | null;