@sealkeeper/schema 0.4.4 → 0.4.5

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,17 @@
 export * from './agent-id.js';
 export * from './agent-name.js';
 export * from './api.js';
+export * from './badge.js';
 export * from './base64url.js';
 export * from './credential.js';
 export * from './dimensions.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './goal.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,17 @@
 export * from './agent-id.js';
 export * from './agent-name.js';
 export * from './api.js';
+export * from './badge.js';
 export * from './base64url.js';
 export * from './credential.js';
 export * from './dimensions.js';
 export * from './envelope.js';
 export * from './events.js';
 export * from './goal.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/moderation.d.ts

@@ -0,0 +1,28 @@
+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';
+export type NameRefusal = {
+    code: NameRefusalCode;
+    message: string;
+};
+export declare function moderateSlug(slug: string): NameRefusal | 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;

package/dist/moderation.js

@@ -0,0 +1,450 @@
+import { z } from 'zod';
+// Moderation of the names an operator chooses, the operator slug and the
+// operator display name. The API runs these checks on every write and is
+// the only enforcement. The CLI and the web run the same checks for early
+// feedback. A name another operator already holds is the API's call, since
+// only the database knows (409 name_taken).
+// ---------------------------------------------------------------------------
+// Shapes
+export const OPERATOR_SLUG_MIN = 1;
+// 39, like a GitHub login. A 39 character slug, a slash and a 39 character
+// agent name make a 79 character handle, the AgentHandle cap that published
+// CLIs bundle.
+export const OPERATOR_SLUG_MAX = 39;
+export const OPERATOR_DISPLAY_NAME_MIN = 1;
+export const OPERATOR_DISPLAY_NAME_MAX = 64;
+const SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+// The operator's slug, the first half of every handle, as in alice/claude-code.
+// Lowercase letters, digits and single hyphens, starting and ending with a
+// letter or digit. Unique across SealKeeper. Reserved words and protected
+// names are refused by moderateSlug, not by this shape.
+export const OperatorSlug = z
+    .string()
+    .min(OPERATOR_SLUG_MIN)
+    .max(OPERATOR_SLUG_MAX)
+    .regex(SLUG, 'Use lowercase letters, digits and hyphens, starting and ending with a letter or digit')
+    .refine((slug) => !slug.includes('--'), 'No double hyphen');
+// Control, format, private use, unassigned and lone surrogate characters
+// (bidi overrides, zero width joiners and the like), and the line and
+// paragraph separators, which can hide, reorder or break what a reader sees.
+const HIDDEN = /[\p{C}\p{Zl}\p{Zp}]/u;
+const LETTER_OR_DIGIT = /[\p{L}\p{N}]/u;
+// The operator's display name. Free text, no control or format characters,
+// no space at either end, and at least one letter or digit, so its
+// normalised key is never empty. Protected names are refused by
+// moderateDisplayName.
+export const OperatorDisplayName = z
+    .string()
+    .min(OPERATOR_DISPLAY_NAME_MIN)
+    .max(OPERATOR_DISPLAY_NAME_MAX)
+    .refine((name) => !HIDDEN.test(name), 'No control characters')
+    .refine((name) => name === name.trim(), 'No space at the start or end')
+    .refine((name) => LETTER_OR_DIGIT.test(name), 'Use at least one letter or digit');
+// ---------------------------------------------------------------------------
+// Normalisation
+// Letters from other scripts that read as a Latin letter, and a few Latin
+// letters NFKD does not split into a base and a mark.
+const HOMOGLYPHS = {
+    // Cyrillic
+    а: 'a',
+    в: 'b',
+    с: 'c',
+    ԁ: 'd',
+    е: 'e',
+    ё: 'e',
+    һ: 'h',
+    н: 'h',
+    і: 'i',
+    ї: 'i',
+    ј: 'j',
+    к: 'k',
+    ӏ: 'l',
+    м: 'm',
+    п: 'n',
+    о: 'o',
+    р: 'p',
+    ԛ: 'q',
+    г: 'r',
+    ѕ: 's',
+    т: 't',
+    у: 'y',
+    ш: 'w',
+    ԝ: 'w',
+    х: 'x',
+    // Greek
+    α: 'a',
+    β: 'b',
+    ϲ: 'c',
+    ε: 'e',
+    η: 'n',
+    ι: 'i',
+    κ: 'k',
+    μ: 'u',
+    ν: 'v',
+    ο: 'o',
+    ρ: 'p',
+    τ: 't',
+    υ: 'u',
+    χ: 'x',
+    ω: 'w',
+    // Latin letters without a decomposition
+    ı: 'i',
+    ȷ: 'j',
+    ł: 'l',
+    ø: 'o',
+    đ: 'd',
+    ħ: 'h',
+    ŧ: 't',
+    ß: 'ss',
+    æ: 'ae',
+    œ: 'oe',
+    ɡ: 'g',
+    ɑ: 'a',
+    // Digits and symbols used as letters
+    '0': 'o',
+    '1': 'l',
+    '3': 'e',
+    '4': 'a',
+    '5': 's',
+    '7': 't',
+    '8': 'b',
+    '@': 'a',
+    $: 's',
+    '|': 'l',
+    '!': 'l',
+};
+// i and l look alike in many fonts (GoogIe with a capital I), so both fold
+// to l. Run after HOMOGLYPHS, so a Cyrillic і, a Greek ι or a dotless ı,
+// which fold to i there, fold on to l as well.
+const I_AS_L = /i/g;
+const MARKS = /\p{M}/gu;
+const NOT_LETTER_OR_DIGIT = /[^\p{L}\p{N}]/gu;
+// The form two names are compared in. NFKC, lowercase, accents dropped,
+// homoglyphs and digit swaps folded, everything but letters and digits
+// dropped, then letter pairs that read as one letter (rn as m, vv as w)
+// folded. Open-AI, OPENAI and 0penai all give the same key. Letters of
+// scripts with no Latin lookalike are kept, so a display name in another
+// script still has a key of its own.
+export function normaliseName(text) {
+    const folded = Array.from(text.normalize('NFKC').toLowerCase().normalize('NFKD').replace(MARKS, ''), (ch) => HOMOGLYPHS[ch] ?? ch)
+        .join('')
+        .replace(I_AS_L, 'l');
+    return folded
+        .replace(NOT_LETTER_OR_DIGIT, '')
+        .replace(/rn/g, 'm')
+        .replace(/vv/g, 'w');
+}
+// The display_name_key column. Unique across operators, so two display
+// names that read the same cannot both be held.
+export const displayNameKey = normaliseName;
+// ---------------------------------------------------------------------------
+// Protected names
+// The top AI and technology companies and products. A slug or display name
+// that normalises to one of these, with or without a common suffix, is
+// refused. Written as the name reads. The list protects the distinctive
+// form only, so Stability AI protects stabilityai (and stability-ai-labs)
+// but not the plain word stability. Products that are also common first
+// names (Devin, Alexa, Siri) are left out, since a login such as devin
+// would otherwise lose its slug. Claude is the one exception.
+export const PROTECTED_NAMES = [
+    // SealKeeper itself
+    'SealKeeper',
+    'Vouched',
+    // AI labs and model makers
+    'Anthropic',
+    'Claude',
+    'OpenAI',
+    'ChatGPT',
+    'GPT',
+    'Codex',
+    'DALL-E',
+    'Google',
+    'Alphabet',
+    'DeepMind',
+    'Gemini',
+    'Microsoft',
+    'Copilot',
+    'Bing',
+    'Azure',
+    'Meta',
+    'Facebook',
+    'Instagram',
+    'WhatsApp',
+    'Llama',
+    'xAI',
+    'Grok',
+    'Twitter',
+    'Mistral',
+    'Le Chat',
+    'Cohere',
+    'DeepSeek',
+    'Qwen',
+    'Alibaba',
+    'Zhipu',
+    'Baidu',
+    'ByteDance',
+    'TikTok',
+    'Tencent',
+    'Perplexity',
+    'Character AI',
+    'Stability AI',
+    'Midjourney',
+    'ElevenLabs',
+    'Hugging Face',
+    'Scale AI',
+    'AI21',
+    'Nous Research',
+    'Together AI',
+    'Groq',
+    'Cerebras',
+    'Ollama',
+    'LangChain',
+    'LlamaIndex',
+    'CrewAI',
+    'AutoGPT',
+    'Mastra',
+    'OpenClaw',
+    // Coding agents and developer tools
+    'Cursor',
+    'Anysphere',
+    'Windsurf',
+    'Codeium',
+    'Replit',
+    'Lovable',
+    'StackBlitz',
+    'Vercel',
+    'Sourcegraph',
+    'Tabnine',
+    'JetBrains',
+    'GitHub',
+    'GitLab',
+    'Bitbucket',
+    'Atlassian',
+    'Notion',
+    'Slack',
+    'Discord',
+    'Figma',
+    'Stripe',
+    'Supabase',
+    'Cloudflare',
+    'Netlify',
+    'Docker',
+    'npm',
+    // Platforms and hardware
+    'Apple',
+    'Amazon',
+    'AWS',
+    'Nvidia',
+    'AMD',
+    'Intel',
+    'IBM',
+    'Oracle',
+    'Salesforce',
+    'Samsung',
+    'Adobe',
+    'Netflix',
+    'Uber',
+    'Palantir',
+    'Databricks',
+    'Snowflake',
+    'Zapier',
+];
+// Suffixes an impersonator adds to a protected name. Stripped one at a time
+// from the end, and the rest compared again.
+export const PROTECTED_SUFFIXES = [
+    'inc',
+    'labs',
+    'ai',
+    'hq',
+    'official',
+    'team',
+];
+// Prefixes an impersonator puts in front, as in the-real-openai. Stripped
+// from the start the same way.
+export const PROTECTED_PREFIXES = [
+    'official',
+    'real',
+    'the',
+    'team',
+];
+const PROTECTED_KEYS = new Map(PROTECTED_NAMES.map((name) => [normaliseName(name), name]));
+const SUFFIX_KEYS = PROTECTED_SUFFIXES.map(normaliseName);
+const PREFIX_KEYS = PROTECTED_PREFIXES.map(normaliseName);
+// Every form of a key a protected name could hide in. The key itself, then
+// the key with every combination of prefixes and suffixes stripped. Never
+// empty.
+function keyForms(key) {
+    const forms = new Set();
+    const queue = [key];
+    while (queue.length > 0) {
+        const form = queue.pop();
+        if (form === '' || forms.has(form))
+            continue;
+        forms.add(form);
+        for (const suffix of SUFFIX_KEYS) {
+            if (form.length > suffix.length && form.endsWith(suffix)) {
+                queue.push(form.slice(0, -suffix.length));
+            }
+        }
+        for (const prefix of PREFIX_KEYS) {
+            if (form.length > prefix.length && form.startsWith(prefix)) {
+                queue.push(form.slice(prefix.length));
+            }
+        }
+    }
+    return [...forms];
+}
+// The protected name a text impersonates, as written in PROTECTED_NAMES, or
+// null when it impersonates none.
+export function protectedNameOf(text) {
+    for (const form of keyForms(normaliseName(text))) {
+        const name = PROTECTED_KEYS.get(form);
+        if (name !== undefined)
+            return name;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Reserved words
+// Route and product words a slug would collide with or read as part of the
+// site. Slugs only, a display name is never part of a URL.
+export const RESERVED_WORDS = [
+    'about',
+    'account',
+    'accounts',
+    'admin',
+    'administrator',
+    'agent',
+    'agents',
+    'anonymous',
+    'api',
+    'app',
+    'assets',
+    'auth',
+    'avatar',
+    'avatars',
+    'badge',
+    'badges',
+    'blog',
+    'callback',
+    'check',
+    'cli',
+    'dashboard',
+    'directory',
+    'docs',
+    'feed',
+    'help',
+    'home',
+    'join',
+    'leaderboard',
+    'legal',
+    'login',
+    'logout',
+    'me',
+    'moderator',
+    'new',
+    'null',
+    'oauth',
+    'official',
+    'operator',
+    'operators',
+    'privacy',
+    'profile',
+    'prove',
+    'register',
+    'root',
+    'search',
+    'seal',
+    'seals',
+    'sealkeeper',
+    'security',
+    'settings',
+    'signin',
+    'signout',
+    'signup',
+    'staff',
+    'static',
+    'status',
+    'support',
+    'system',
+    'task',
+    'tasks',
+    'terms',
+    'undefined',
+    'v1',
+    'verify',
+    'vouched',
+    'well-known',
+    'what-is-shared',
+    'www',
+];
+// Compared in normalised form, so adm1n and a-p-i are refused as well.
+const RESERVED_KEYS = new Set(RESERVED_WORDS.map(normaliseName));
+export function isReservedWord(text) {
+    return RESERVED_KEYS.has(normaliseName(text));
+}
+function protectedRefusal(text) {
+    const name = protectedNameOf(text);
+    return name === null
+        ? null
+        : {
+            code: 'name_protected',
+            message: `${text} reads as ${name}, which is a protected name. Pick another.`,
+        };
+}
+// The refusal for an operator slug, or null when it may be used. The shape
+// is OperatorSlug's job, this checks reserved words and protected names.
+export function moderateSlug(slug) {
+    if (isReservedWord(slug)) {
+        return {
+            code: 'name_reserved',
+            message: `${slug} is reserved by SealKeeper. Pick another.`,
+        };
+    }
+    return protectedRefusal(slug);
+}
+// The refusal for an operator display name, or null when it may be used.
+// The shape is OperatorDisplayName's job. Whether another operator holds
+// the same key is the API's check against display_name_key.
+export function moderateDisplayName(name) {
+    return protectedRefusal(name);
+}
+// ---------------------------------------------------------------------------
+// Default slugs
+// A login as a slug. Lowercase, every run of characters other than a to z
+// and 0 to 9 made one hyphen, hyphens trimmed from the ends, since an old
+// GitHub login can end in one. A login is not always letters, digits and
+// hyphens (an Enterprise Managed User login ends in _shortcode), and a
+// slug must be. The same rule as sk_base in migration 0025. The API's
+// default slug for a new operator starts from it.
+export function slugBase(login) {
+    const base = login
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, OPERATOR_SLUG_MAX)
+        .replace(/-$/, '');
+    return base === '' ? 'operator' : base;
+}
+// base with -n on the end, cut so the whole stays within the slug limit.
+export const suffixedSlug = (base, n) => `${base.slice(0, OPERATOR_SLUG_MAX - `-${n}`.length).replace(/-+$/, '')}-${n}`;
+// The reason the slug is the login's slug with a -2, -3 and so on, or null
+// when it is not. A slug the operator chose, or one left behind by a GitHub
+// login change, is not of that form and gives null. The caller also checks
+// that the slug never changed, since an operator can pick a suffixed slug.
+// reserved and protected are read from today's lists, taken is the rest.
+export function slugSuffixReason(login, slug) {
+    const base = slugBase(login);
+    const n = /-([0-9]+)$/.exec(slug)?.[1];
+    if (n === undefined || slug === base)
+        return null;
+    const k = Number(n);
+    if (k < 2 || suffixedSlug(base, k) !== slug)
+        return null;
+    const refusal = moderateSlug(base);
+    if (refusal?.code === 'name_reserved')
+        return 'reserved';
+    if (refusal?.code === 'name_protected')
+        return 'protected';
+    return 'taken';
+}