@sealkeeper/schema 0.4.6 → 0.4.8

package/dist/fingerprint.d.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod';
+export declare const FINGERPRINT_PARTS: readonly ['model_set', 'prompt', 'tools', 'framework'];
+export type FingerprintPartName = (typeof FINGERPRINT_PARTS)[number];
+export declare const FINGERPRINT_NOT_DECLARED = "not_declared";
+export declare const FINGERPRINT_UNSTABLE = "unstable";
+export declare const FINGERPRINT_UNSTABLE_CAPTURES = 5;
+export declare const Sha256Base64url: z.ZodString;
+export declare const FingerprintPart: z.ZodUnion<readonly [z.ZodObject<{
+    hash: z.ZodString;
+}, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+export type FingerprintPart = z.infer<typeof FingerprintPart>;
+export declare const FingerprintParts: z.ZodObject<{
+    model_set: z.ZodUnion<readonly [z.ZodObject<{
+        hash: z.ZodString;
+    }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+    prompt: z.ZodUnion<readonly [z.ZodObject<{
+        hash: z.ZodString;
+    }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+    tools: z.ZodUnion<readonly [z.ZodObject<{
+        hash: z.ZodString;
+    }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+    framework: z.ZodUnion<readonly [z.ZodObject<{
+        hash: z.ZodString;
+    }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+}, z.core.$strict>;
+export type FingerprintParts = z.infer<typeof FingerprintParts>;
+export declare const FINGERPRINT_MAX_CAPTURED_AT = 253402300799;
+export declare const Fingerprint: z.ZodObject<{
+    parts: z.ZodObject<{
+        model_set: z.ZodUnion<readonly [z.ZodObject<{
+            hash: z.ZodString;
+        }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+        prompt: z.ZodUnion<readonly [z.ZodObject<{
+            hash: z.ZodString;
+        }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+        tools: z.ZodUnion<readonly [z.ZodObject<{
+            hash: z.ZodString;
+        }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+        framework: z.ZodUnion<readonly [z.ZodObject<{
+            hash: z.ZodString;
+        }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+    }, z.core.$strict>;
+    hash: z.ZodString;
+    captured_at: z.ZodNumber;
+}, z.core.$strict>;
+export type Fingerprint = z.infer<typeof Fingerprint>;
+export declare function fingerprintPartText(part: FingerprintPart): string;
+export declare function fingerprintCanonical(parts: FingerprintParts): Uint8Array;
+export declare function fingerprintHash(parts: FingerprintParts): Promise<string>;
+export declare function partHash(agentId: string, content: Uint8Array | string): Promise<string>;
+export declare function makeFingerprint(parts: FingerprintParts, capturedAt: number): Promise<Fingerprint>;
+export declare function fingerprintProblem(value: unknown): Promise<'malformed' | 'hash_mismatch' | null>;
+export declare const FINGERPRINT_DECLARED = "declared";
+export declare const FingerprintPartState: z.ZodEnum<{
+    declared: "declared";
+    not_declared: "not_declared";
+    unstable: "unstable";
+}>;
+export type FingerprintPartState = z.infer<typeof FingerprintPartState>;
+export declare const FingerprintStates: z.ZodObject<{
+    model_set: z.ZodEnum<{
+        declared: "declared";
+        not_declared: "not_declared";
+        unstable: "unstable";
+    }>;
+    prompt: z.ZodEnum<{
+        declared: "declared";
+        not_declared: "not_declared";
+        unstable: "unstable";
+    }>;
+    tools: z.ZodEnum<{
+        declared: "declared";
+        not_declared: "not_declared";
+        unstable: "unstable";
+    }>;
+    framework: z.ZodEnum<{
+        declared: "declared";
+        not_declared: "not_declared";
+        unstable: "unstable";
+    }>;
+}, z.core.$strict>;
+export type FingerprintStates = z.infer<typeof FingerprintStates>;
+export declare const AgentFingerprint: z.ZodObject<{
+    hash: z.ZodString;
+    at: z.ZodISODateTime;
+    parts: z.ZodObject<{
+        model_set: z.ZodEnum<{
+            declared: "declared";
+            not_declared: "not_declared";
+            unstable: "unstable";
+        }>;
+        prompt: z.ZodEnum<{
+            declared: "declared";
+            not_declared: "not_declared";
+            unstable: "unstable";
+        }>;
+        tools: z.ZodEnum<{
+            declared: "declared";
+            not_declared: "not_declared";
+            unstable: "unstable";
+        }>;
+        framework: z.ZodEnum<{
+            declared: "declared";
+            not_declared: "not_declared";
+            unstable: "unstable";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type AgentFingerprint = z.infer<typeof AgentFingerprint>;
+export declare function fingerprintPartState(part: FingerprintPart): FingerprintPartState;
+export declare function agentFingerprintOf(fingerprint: Fingerprint): AgentFingerprint;
+export declare const FingerprintDeclaration: z.ZodObject<{
+    fingerprint: z.ZodObject<{
+        parts: z.ZodObject<{
+            model_set: z.ZodUnion<readonly [z.ZodObject<{
+                hash: z.ZodString;
+            }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+            prompt: z.ZodUnion<readonly [z.ZodObject<{
+                hash: z.ZodString;
+            }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+            tools: z.ZodUnion<readonly [z.ZodObject<{
+                hash: z.ZodString;
+            }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+            framework: z.ZodUnion<readonly [z.ZodObject<{
+                hash: z.ZodString;
+            }, z.core.$strict>, z.ZodLiteral<"not_declared">, z.ZodLiteral<"unstable">]>;
+        }, z.core.$strict>;
+        hash: z.ZodString;
+        captured_at: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type FingerprintDeclaration = z.infer<typeof FingerprintDeclaration>;

package/dist/fingerprint.js

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+import { AgentId } from './agent-id.js';
+import { base64urlEncode, utf8Encode } from './base64url.js';
+/*
+ * The fingerprint of what an agent runs now, beside its version and never in
+ * place of it (D-VB-1). The version stays the operator's label and the
+ * scoring key. The fingerprint records the model, prompt, tools and
+ * framework the agent ran under, each as a SHA-256 hash the CLI computed on
+ * the machine. What a part is hashed from never leaves the machine.
+ *
+ * A part is its hash, not_declared when the adapter cannot see it, or
+ * unstable when its hash changed on every one of the last captures, so a
+ * part that churns does not make every fingerprint look new.
+ *
+ * The hash rule. A part's hash is SHA-256 over the agent id, one newline,
+ * then the content, in base64url (partHash). The agent id keeps a part from
+ * being a dictionary lookup, since a model id or a framework version is
+ * easy to guess, and a fingerprint is only ever compared with the same
+ * agent's. The fingerprint hash is SHA-256 over the four parts in the fixed
+ * order model_set, prompt, tools, framework, each as its hash or its state
+ * string, joined by one newline with no newline at the end, UTF-8
+ * (fingerprintHash). No JSON canonicalisation anywhere.
+ */
+// The parts in the fixed order the canonical bytes use. Adding a part is a
+// new fingerprint format, since it changes every hash.
+export const FINGERPRINT_PARTS = [
+    'model_set',
+    'prompt',
+    'tools',
+    'framework',
+];
+export const FINGERPRINT_NOT_DECLARED = 'not_declared';
+export const FINGERPRINT_UNSTABLE = 'unstable';
+// A part whose hash differed from the capture before it on each of the last
+// this many captures reads unstable (D-VB-4). The CLI keeps this many, and
+// the profile's help names the number.
+export const FINGERPRINT_UNSTABLE_CAPTURES = 5;
+// A SHA-256 digest in base64url without padding, 43 characters. 256 bits
+// leave 4 bits in the last character, so only the 16 characters whose low
+// two bits are zero can end it, which keeps one spelling per digest.
+export const Sha256Base64url = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/, 'SHA-256, base64url');
+export const FingerprintPart = z.union([
+    z.strictObject({ hash: Sha256Base64url }),
+    z.literal(FINGERPRINT_NOT_DECLARED),
+    z.literal(FINGERPRINT_UNSTABLE),
+]);
+export const FingerprintParts = z.strictObject({
+    model_set: FingerprintPart,
+    prompt: FingerprintPart,
+    tools: FingerprintPart,
+    framework: FingerprintPart,
+});
+// The last second of 9999-12-31 UTC, the latest captured_at a fingerprint
+// may carry. A capture past it is refused at the edge with the rest of the
+// shape, rather than failing in the database.
+export const FINGERPRINT_MAX_CAPTURED_AT = 253402300799;
+// hash is fingerprintHash(parts). The schema checks the shape only. A reader
+// that relies on hash recomputes it, see fingerprintProblem.
+export const Fingerprint = z.strictObject({
+    parts: FingerprintParts,
+    hash: Sha256Base64url,
+    // When the CLI captured it, Unix seconds, at most the last second of
+    // year 9999, so every value is a timestamp Postgres and Date can hold.
+    captured_at: z.number().int().min(0).max(FINGERPRINT_MAX_CAPTURED_AT),
+});
+// A part as it appears in the canonical bytes, its hash or its state.
+export function fingerprintPartText(part) {
+    return typeof part === 'string' ? part : part.hash;
+}
+// The canonical bytes of the parts. Each part as its hash or its state
+// string, in the order of FINGERPRINT_PARTS, joined by one newline with no
+// newline at the end, UTF-8. No JSON and no canonicalisation library, the
+// same stance as the JWS.
+export function fingerprintCanonical(parts) {
+    return utf8Encode(FINGERPRINT_PARTS.map((name) => fingerprintPartText(parts[name])).join('\n'));
+}
+// WebCrypto, so the same code runs in Node, the browser and edge runtimes.
+async function sha256(bytes) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new Uint8Array(bytes));
+    return base64urlEncode(new Uint8Array(digest));
+}
+// The fingerprint hash, SHA-256 of the canonical bytes, base64url.
+export function fingerprintHash(parts) {
+    return sha256(fingerprintCanonical(parts));
+}
+// A part's hash under the hash rule above, for the agent agentId. A string
+// is hashed as its UTF-8 bytes. Every adapter hashes through this, so one
+// input gives one hash wherever it is computed. Throws on an agent id that
+// is not one, as a rejected promise.
+export async function partHash(agentId, content) {
+    const id = AgentId.parse(agentId);
+    const body = typeof content === 'string' ? utf8Encode(content) : content;
+    const prefix = utf8Encode(`${id}\n`);
+    const bytes = new Uint8Array(prefix.length + body.length);
+    bytes.set(prefix);
+    bytes.set(body, prefix.length);
+    return sha256(bytes);
+}
+// A whole fingerprint from its parts, with its hash.
+export async function makeFingerprint(parts, capturedAt) {
+    return Fingerprint.parse({
+        parts,
+        hash: await fingerprintHash(parts),
+        captured_at: capturedAt,
+    });
+}
+// Why a value is not a fingerprint to rely on, or null when it is one. The
+// shape comes first, then the hash, which must be the hash of its parts.
+export async function fingerprintProblem(value) {
+    const parsed = Fingerprint.safeParse(value);
+    if (!parsed.success)
+        return 'malformed';
+    const hash = await fingerprintHash(parsed.data.parts);
+    return hash === parsed.data.hash ? null : 'hash_mismatch';
+}
+/*
+ * The agent's current fingerprint as the agent answer shows it (VB-4). Its
+ * hash, when it was captured, and each part as its state alone, declared,
+ * not_declared or unstable. The part hashes stay out, since they are
+ * salted with the agent id and serve no reader. The handshake (VB-6)
+ * compares the fingerprint hash.
+ */
+export const FINGERPRINT_DECLARED = 'declared';
+export const FingerprintPartState = z.enum([
+    FINGERPRINT_DECLARED,
+    FINGERPRINT_NOT_DECLARED,
+    FINGERPRINT_UNSTABLE,
+]);
+export const FingerprintStates = z.strictObject({
+    model_set: FingerprintPartState,
+    prompt: FingerprintPartState,
+    tools: FingerprintPartState,
+    framework: FingerprintPartState,
+});
+// at is captured_at as an ISO 8601 timestamp.
+export const AgentFingerprint = z.strictObject({
+    hash: Sha256Base64url,
+    at: z.iso.datetime(),
+    parts: FingerprintStates,
+});
+// A part's state, declared when it is a hash.
+export function fingerprintPartState(part) {
+    return typeof part === 'string' ? part : FINGERPRINT_DECLARED;
+}
+// The answer's view of a stored fingerprint, never a part hash.
+export function agentFingerprintOf(fingerprint) {
+    const { parts } = fingerprint;
+    return {
+        hash: fingerprint.hash,
+        at: new Date(fingerprint.captured_at * 1000).toISOString(),
+        parts: {
+            model_set: fingerprintPartState(parts.model_set),
+            prompt: fingerprintPartState(parts.prompt),
+            tools: fingerprintPartState(parts.tools),
+            framework: fingerprintPartState(parts.framework),
+        },
+    };
+}
+// The signed payload of the fingerprint a sync declares (VB-4). A batch's
+// envelopes are events, so the fingerprint travels as its own JWS, signed
+// by the same agent, under fingerprint on EventsBatchRequest.
+export const FingerprintDeclaration = z.strictObject({
+    fingerprint: Fingerprint,
+});

package/dist/goal.d.ts

@@ -1,5 +1,5 @@
 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 GOAL_ACTION_CODES: readonly ['dormant', 'operator_verification_lapsing', 'confirm_outcomes', 'report_as_poster', 'addressed_waiting', 'claim_seed_tasks', 'post_task', 'post_confirmed_task', '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'];
 export declare const GoalActionCode: z.ZodEnum<{
     addressed_waiting: "addressed_waiting";
     claim_seed_tasks: "claim_seed_tasks";
@@ -15,6 +15,8 @@ export declare const GoalActionCode: z.ZodEnum<{
     operator_silver_cap: "operator_silver_cap";
     operator_unverified: "operator_unverified";
     operator_verification_lapsing: "operator_verification_lapsing";
+    post_confirmed_task: "post_confirmed_task";
+    post_task: "post_task";
     provenance_below: "provenance_below";
     reliability_below: "reliability_below";
     report_as_poster: "report_as_poster";
@@ -83,6 +85,11 @@ export declare const GoalPending: z.ZodObject<{
     posterOutcomes: z.ZodInt;
 }, z.core.$strict>;
 export type GoalPending = z.infer<typeof GoalPending>;
+export declare const GoalSide: z.ZodObject<{
+    current: z.ZodNumber;
+    required: z.ZodNumber;
+}, z.core.$strict>;
+export type GoalSide = z.infer<typeof GoalSide>;
 export declare const GoalResponse: z.ZodObject<{
     agentId: z.ZodString;
     version: z.ZodString;
@@ -128,6 +135,14 @@ export declare const GoalResponse: z.ZodObject<{
             required: z.ZodNumber;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
+    taken: z.ZodNullable<z.ZodObject<{
+        current: z.ZodNumber;
+        required: z.ZodNumber;
+    }, z.core.$strict>>;
+    posted: z.ZodNullable<z.ZodObject<{
+        current: z.ZodNumber;
+        required: z.ZodNumber;
+    }, z.core.$strict>>;
     actions: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         count: z.ZodNullable<z.ZodInt>;

package/dist/goal.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { AgentId } from './agent-id.js';
-import { Version } from './events.js';
+import { StoredVersion } 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
@@ -24,12 +24,28 @@ export const GOAL_ACTION_CODES = [
     // confirmed task counts for its claimant, so this counts toward the
     // agent's own level. count is how many.
     'confirm_outcomes',
+    // Counterparty tasks this agent posted wait for its outcome report. It
+    // confirms the task for the claimant, and since POST-3 the confirmed task
+    // counts in this agent's posted tasks too, so it comes beside
+    // confirm_outcomes. count is how many.
+    'report_as_poster',
     // 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',
+    // Posted tasks that other operators' agents complete still needed, for
+    // the posted tasks or posted operators of the next level (POST-3). count
+    // is the posts at least still needed. It comes before claim_seed_tasks
+    // when posting is further behind than taking (POST-6), else where the
+    // posted rows come in the table.
+    'post_task',
+    // Posted confirmed tasks still needed (POST-6). Only a counterparty task
+    // the agent posted by hand, completed by another operator's agent and
+    // confirmed by both outcome reports, counts, so a template or adopted
+    // post never closes it. count is how many.
+    'post_confirmed_task',
     // 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.
@@ -65,10 +81,6 @@ export const GOAL_ACTION_CODES = [
     // 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
@@ -156,14 +168,25 @@ export const GoalPending = z.strictObject({
     outcomes: Count,
     posterOutcomes: Count,
 });
+// One side of the agent's work toward the next level (POST-6), current
+// against required, in counted units. taken is the verified_tasks
+// threshold, the tasks the agent took. posted is the posted_tasks
+// threshold, the tasks it posted that other operators' agents completed.
+export const GoalSide = z.strictObject({
+    current: z.number(),
+    required: z.number(),
+});
 export const GoalResponse = z.strictObject({
     agentId: AgentId,
-    version: Version,
+    version: StoredVersion,
     level: Level,
     nextLevel: Level.nullable(),
     ladder: z.array(GoalLadderStep),
     thresholds: z.array(GoalThreshold),
     steps: z.array(GoalStep),
+    // Taken and posted toward nextLevel, null when nextLevel is null.
+    taken: GoalSide.nullable(),
+    posted: GoalSide.nullable(),
     actions: z.array(GoalAction),
     pending: GoalPending,
     today: GoalToday,

package/dist/handshake-conformance.d.ts

@@ -0,0 +1,18 @@
+import { type WellKnown } from './credential.js';
+import { type HandshakeRefusal, type HandshakeResult } from './handshake.js';
+export type HandshakeConformanceCase = {
+    name: string;
+    jws: string;
+    expected: Exclude<HandshakeResult, 'no_fingerprint'> | HandshakeRefusal;
+    nonce?: string;
+    nowSeconds?: number;
+};
+export type HandshakeConformance = {
+    nowSeconds: number;
+    sub: string;
+    fingerprint: string;
+    seal: string;
+    wellKnown: WellKnown;
+    cases: HandshakeConformanceCase[];
+};
+export declare function handshakeConformanceCases(): Promise<HandshakeConformance>;