@sealkeeper/schema 0.4.3 → 0.4.5

package/dist/goal.d.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+export declare const GOAL_ACTION_CODES: readonly ['dormant', 'operator_verification_lapsing', 'confirm_outcomes', 'addressed_waiting', 'claim_seed_tasks', 'claim_tasks', 'counterparty_tasks', 'need_operators', 'history_days', 'reliability_below', 'safety_below', 'safety_incident_window', 'clean_days', 'provenance_below', 'declare_model', 'operator_unverified', 'need_ratings', 'version_cap', 'operator_silver_cap', 'report_as_poster'];
+export declare const GoalActionCode: z.ZodEnum<{
+    addressed_waiting: "addressed_waiting";
+    claim_seed_tasks: "claim_seed_tasks";
+    claim_tasks: "claim_tasks";
+    clean_days: "clean_days";
+    confirm_outcomes: "confirm_outcomes";
+    counterparty_tasks: "counterparty_tasks";
+    declare_model: "declare_model";
+    dormant: "dormant";
+    history_days: "history_days";
+    need_operators: "need_operators";
+    need_ratings: "need_ratings";
+    operator_silver_cap: "operator_silver_cap";
+    operator_unverified: "operator_unverified";
+    operator_verification_lapsing: "operator_verification_lapsing";
+    provenance_below: "provenance_below";
+    reliability_below: "reliability_below";
+    report_as_poster: "report_as_poster";
+    safety_below: "safety_below";
+    safety_incident_window: "safety_incident_window";
+    version_cap: "version_cap";
+}>;
+export type GoalActionCode = z.infer<typeof GoalActionCode>;
+export declare const GoalThreshold: z.ZodObject<{
+    name: z.ZodString;
+    current: z.ZodNumber;
+    required: z.ZodNumber;
+    met: z.ZodBoolean;
+    raw: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export type GoalThreshold = z.infer<typeof GoalThreshold>;
+export declare const GoalAction: z.ZodObject<{
+    code: z.ZodString;
+    count: z.ZodNullable<z.ZodInt>;
+    until: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type GoalAction = z.infer<typeof GoalAction>;
+export declare const GOAL_LADDER_STATES: readonly ['reached', 'next', 'locked', 'reserved'];
+export declare const GoalLadderState: z.ZodEnum<{
+    locked: "locked";
+    next: "next";
+    reached: "reached";
+    reserved: "reserved";
+}>;
+export type GoalLadderState = z.infer<typeof GoalLadderState>;
+export declare const GoalLadderStep: z.ZodObject<{
+    level: z.ZodEnum<{
+        bronze: "bronze";
+        gold: "gold";
+        none: "none";
+        platinum: "platinum";
+        silver: "silver";
+    }>;
+    state: z.ZodEnum<{
+        locked: "locked";
+        next: "next";
+        reached: "reached";
+        reserved: "reserved";
+    }>;
+}, z.core.$strict>;
+export type GoalLadderStep = z.infer<typeof GoalLadderStep>;
+export declare const GoalStep: z.ZodObject<{
+    code: z.ZodString;
+    done: z.ZodBoolean;
+    progress: z.ZodNullable<z.ZodObject<{
+        current: z.ZodNumber;
+        required: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type GoalStep = z.infer<typeof GoalStep>;
+export declare const GoalToday: z.ZodObject<{
+    day: z.ZodISODate;
+    counted: z.ZodInt;
+    ceiling: z.ZodInt;
+    remaining: z.ZodInt;
+}, z.core.$strict>;
+export type GoalToday = z.infer<typeof GoalToday>;
+export declare const GoalPending: z.ZodObject<{
+    addressed: z.ZodInt;
+    outcomes: z.ZodInt;
+    posterOutcomes: z.ZodInt;
+}, z.core.$strict>;
+export type GoalPending = z.infer<typeof GoalPending>;
+export declare const GoalResponse: z.ZodObject<{
+    agentId: z.ZodString;
+    version: z.ZodString;
+    level: z.ZodEnum<{
+        bronze: "bronze";
+        gold: "gold";
+        none: "none";
+        silver: "silver";
+    }>;
+    nextLevel: z.ZodNullable<z.ZodEnum<{
+        bronze: "bronze";
+        gold: "gold";
+        none: "none";
+        silver: "silver";
+    }>>;
+    ladder: z.ZodArray<z.ZodObject<{
+        level: z.ZodEnum<{
+            bronze: "bronze";
+            gold: "gold";
+            none: "none";
+            platinum: "platinum";
+            silver: "silver";
+        }>;
+        state: z.ZodEnum<{
+            locked: "locked";
+            next: "next";
+            reached: "reached";
+            reserved: "reserved";
+        }>;
+    }, z.core.$strict>>;
+    thresholds: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        current: z.ZodNumber;
+        required: z.ZodNumber;
+        met: z.ZodBoolean;
+        raw: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+    steps: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        done: z.ZodBoolean;
+        progress: z.ZodNullable<z.ZodObject<{
+            current: z.ZodNumber;
+            required: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    actions: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        count: z.ZodNullable<z.ZodInt>;
+        until: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    pending: z.ZodObject<{
+        addressed: z.ZodInt;
+        outcomes: z.ZodInt;
+        posterOutcomes: z.ZodInt;
+    }, z.core.$strict>;
+    today: z.ZodObject<{
+        day: z.ZodISODate;
+        counted: z.ZodInt;
+        ceiling: z.ZodInt;
+        remaining: z.ZodInt;
+    }, z.core.$strict>;
+    asOf: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type GoalResponse = z.infer<typeof GoalResponse>;

package/dist/goal.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { AgentId } from './agent-id.js';
+import { Version } from './events.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),
+// so a threshold name or an action code added later never breaks it.
+const Count = z.int().min(0);
+// The action codes the API sends today, in the order it lists them.
+// docs/architecture.md section 4.2 says what each one means. A
+// client shows a code it does not know in a generic way, it never refuses
+// the answer over one.
+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.
+    'confirm_outcomes',
+    // Tasks addressed to this agent are waiting to be claimed. count is how
+    // many.
+    'addressed_waiting',
+    // 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. 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',
+    // Other operators still needed behind the agent's tasks.
+    'need_operators',
+    // Active days (or span of days) still needed.
+    'history_days',
+    // Reliability or safety under the threshold. count is null.
+    'reliability_below',
+    '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. The operator
+    // verifies a domain on the account page (VOU-185).
+    'operator_unverified',
+    // Ratings from silver or gold agents still needed.
+    'need_ratings',
+    // Every threshold holds on the counts carried over from the previous
+    // 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.
+    'report_as_poster',
+];
+export const GoalActionCode = z.enum(GOAL_ACTION_CODES);
+// One rule of the next level. current is what the version has (0 for a
+// score with no signal yet), required the standard's number. Flags such as
+// model_declared read 1 for true and 0 for false. met is true at required
+// or above, or at required or below for incident counts. Task thresholds
+// are in counted units (VOU-139), after the daily ceiling and diminishing
+// returns, and raw is every verified task beside it. raw is null for the
+// other rules.
+export const GoalThreshold = z.strictObject({
+    name: z.string().min(1).max(64),
+    current: z.number(),
+    required: z.number(),
+    met: z.boolean(),
+    raw: z.number().nullable(),
+});
+// One next step. code is machine readable, count what is left where a
+// 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 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(),
+    counted: Count,
+    ceiling: Count,
+    remaining: Count,
+});
+// What waits for the agent, counted live. addressed is open tasks addressed
+// to it. outcomes is counterparty tasks from other operators that it
+// claimed and has not reported on, and posterOutcomes the ones it posted
+// and has not reported on. Public, like the rest of the goal. Each says only
+// that a report is missing, never what a report says.
+export const GoalPending = z.strictObject({
+    addressed: Count,
+    outcomes: Count,
+    posterOutcomes: Count,
+});
+export const GoalResponse = z.strictObject({
+    agentId: AgentId,
+    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,
+    asOf: z.iso.datetime().nullable(),
+});

package/dist/index.d.ts

@@ -1,11 +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,11 +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;