@sealkeeper/schema 0.4.7 → 0.4.8

package/dist/credential.d.ts

@@ -13,7 +13,7 @@ export declare const CREDENTIAL_EXTENSION_URI = "https://vouched.run/ext/credent
 export declare const LEGACY_SEAL_EXTENSION_URIS: readonly string[];
 export declare const SEAL_EXTENSION_URIS: readonly string[];
 export declare const SEAL_VERSION = 1;
-export declare const SEAL_VERSIONS: readonly [1, 2];
+export declare const SEAL_VERSIONS: readonly [1, 2, 3];
 export declare const IdentityKind: z.ZodUnion<readonly [z.ZodEnum<{
     kya: "kya";
     oidc: "oidc";
@@ -41,6 +41,17 @@ export type IdentityReference = z.infer<typeof IdentityReference>;
 export declare const operatorVerified: (identity: readonly IdentityReference[]) => boolean;
 export declare const SEAL_MAX_TTL_SECONDS: number;
 export declare const SEAL_CLOCK_SKEW_SECONDS = 300;
+export declare const SealState: z.ZodEnum<{
+    changed: "changed";
+    matches: "matches";
+    provisional: "provisional";
+}>;
+export type SealState = z.infer<typeof SealState>;
+export declare const SealFingerprint: z.ZodNullable<z.ZodObject<{
+    hash: z.ZodString;
+    at: z.ZodInt;
+}, z.core.$strict>>;
+export type SealFingerprint = z.infer<typeof SealFingerprint>;
 export declare const CredentialPayload: z.ZodObject<{
     iss: z.ZodLiteral<"sealkeeper.run">;
     sub: z.ZodString;
@@ -60,7 +71,7 @@ export declare const CredentialPayload: z.ZodObject<{
         provenance: "provenance";
         reliability: "reliability";
         safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
     counts: z.ZodObject<{
         events: z.ZodInt;
         history_days: z.ZodInt;
@@ -113,7 +124,7 @@ export declare const CredentialPayloadV2: z.ZodObject<{
         provenance: "provenance";
         reliability: "reliability";
         safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
     counts: z.ZodObject<{
         events: z.ZodInt;
         history_days: z.ZodInt;
@@ -153,6 +164,78 @@ export declare const CredentialPayloadV2: z.ZodObject<{
     dormant_days: z.ZodNullable<z.ZodInt>;
 }, z.core.$strict>;
 export type CredentialPayloadV2 = z.infer<typeof CredentialPayloadV2>;
+export declare const CredentialPayloadV3: z.ZodObject<{
+    iss: z.ZodLiteral<"sealkeeper.run">;
+    sub: z.ZodString;
+    ver: z.ZodLiteral<3>;
+    iat: z.ZodInt;
+    exp: z.ZodInt;
+    agent_version: z.ZodString;
+    level: z.ZodEnum<{
+        bronze: "bronze";
+        gold: "gold";
+        none: "none";
+        silver: "silver";
+    }>;
+    scores: z.ZodRecord<z.ZodUnion<readonly [z.ZodEnum<{
+        cost_latency: "cost_latency";
+        provenance: "provenance";
+        reliability: "reliability";
+        safety: "safety";
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    counts: z.ZodObject<{
+        events: z.ZodInt;
+        history_days: z.ZodInt;
+        verified_tasks: z.ZodInt;
+        seed_tasks: z.ZodInt;
+        server_checked_tasks: z.ZodInt;
+        confirmed_tasks: z.ZodInt;
+        distinct_operators: z.ZodInt;
+        safety_incidents_90d: z.ZodInt;
+        posted_tasks: z.ZodInt;
+        posted_distinct_operators: z.ZodInt;
+        posted_confirmed_tasks: z.ZodInt;
+    }, z.core.$strict>;
+    counted: z.ZodObject<{
+        verified_tasks: z.ZodInt;
+        seed_tasks: z.ZodInt;
+        server_checked_tasks: z.ZodInt;
+        confirmed_tasks: z.ZodInt;
+        posted_tasks: z.ZodInt;
+        posted_confirmed_tasks: z.ZodInt;
+    }, z.core.$strict>;
+    fingerprint: z.ZodNullable<z.ZodObject<{
+        hash: z.ZodString;
+        at: z.ZodInt;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        changed: "changed";
+        matches: "matches";
+        provisional: "provisional";
+    }>;
+    operator: z.ZodObject<{
+        verified: z.ZodBoolean;
+    }, z.core.$strict>;
+    identity: z.ZodArray<z.ZodObject<{
+        provider: z.ZodURL;
+        kind: z.ZodUnion<readonly [z.ZodEnum<{
+            kya: "kya";
+            oidc: "oidc";
+            saml: "saml";
+            verifiable_credential: "verifiable_credential";
+        }>, z.ZodURL]>;
+        ref: z.ZodString;
+        subject_hash: z.ZodString;
+        attested_at: z.ZodInt;
+        scope: z.ZodEnum<{
+            agent: "agent";
+            operator: "operator";
+        }>;
+    }, z.core.$strict>>;
+    last_active: z.ZodNullable<z.ZodInt>;
+    dormant_days: z.ZodNullable<z.ZodInt>;
+}, z.core.$strict>;
+export type CredentialPayloadV3 = z.infer<typeof CredentialPayloadV3>;
 export declare const VerifiedCredentialPayload: z.ZodObject<{
     iss: z.ZodEnum<{
         "sealkeeper.run": "sealkeeper.run";
@@ -175,7 +258,7 @@ export declare const VerifiedCredentialPayload: z.ZodObject<{
         provenance: "provenance";
         reliability: "reliability";
         safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
     counts: z.ZodObject<{
         events: z.ZodInt;
         history_days: z.ZodInt;
@@ -231,7 +314,7 @@ export declare const VerifiedCredentialPayloadV2: z.ZodObject<{
         provenance: "provenance";
         reliability: "reliability";
         safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
     counts: z.ZodObject<{
         events: z.ZodInt;
         history_days: z.ZodInt;
@@ -271,6 +354,81 @@ export declare const VerifiedCredentialPayloadV2: z.ZodObject<{
     dormant_days: z.ZodNullable<z.ZodInt>;
 }, z.core.$strict>;
 export type VerifiedCredentialPayloadV2 = z.infer<typeof VerifiedCredentialPayloadV2>;
+export declare const VerifiedCredentialPayloadV3: z.ZodObject<{
+    iss: z.ZodEnum<{
+        "sealkeeper.run": "sealkeeper.run";
+        "vouched.run": "vouched.run";
+    }>;
+    sub: z.ZodString;
+    ver: z.ZodLiteral<3>;
+    iat: z.ZodInt;
+    exp: z.ZodInt;
+    agent_version: z.ZodString;
+    level: z.ZodEnum<{
+        bronze: "bronze";
+        gold: "gold";
+        none: "none";
+        silver: "silver";
+    }>;
+    scores: z.ZodRecord<z.ZodUnion<readonly [z.ZodEnum<{
+        cost_latency: "cost_latency";
+        provenance: "provenance";
+        reliability: "reliability";
+        safety: "safety";
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    counts: z.ZodObject<{
+        events: z.ZodInt;
+        history_days: z.ZodInt;
+        verified_tasks: z.ZodInt;
+        seed_tasks: z.ZodInt;
+        server_checked_tasks: z.ZodInt;
+        confirmed_tasks: z.ZodInt;
+        distinct_operators: z.ZodInt;
+        safety_incidents_90d: z.ZodInt;
+        posted_tasks: z.ZodInt;
+        posted_distinct_operators: z.ZodInt;
+        posted_confirmed_tasks: z.ZodInt;
+    }, z.core.$strict>;
+    counted: z.ZodObject<{
+        verified_tasks: z.ZodInt;
+        seed_tasks: z.ZodInt;
+        server_checked_tasks: z.ZodInt;
+        confirmed_tasks: z.ZodInt;
+        posted_tasks: z.ZodInt;
+        posted_confirmed_tasks: z.ZodInt;
+    }, z.core.$strict>;
+    fingerprint: z.ZodNullable<z.ZodObject<{
+        hash: z.ZodString;
+        at: z.ZodInt;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        changed: "changed";
+        matches: "matches";
+        provisional: "provisional";
+    }>;
+    operator: z.ZodObject<{
+        verified: z.ZodBoolean;
+    }, z.core.$strict>;
+    identity: z.ZodArray<z.ZodObject<{
+        provider: z.ZodURL;
+        kind: z.ZodUnion<readonly [z.ZodEnum<{
+            kya: "kya";
+            oidc: "oidc";
+            saml: "saml";
+            verifiable_credential: "verifiable_credential";
+        }>, z.ZodURL]>;
+        ref: z.ZodString;
+        subject_hash: z.ZodString;
+        attested_at: z.ZodInt;
+        scope: z.ZodEnum<{
+            agent: "agent";
+            operator: "operator";
+        }>;
+    }, z.core.$strict>>;
+    last_active: z.ZodNullable<z.ZodInt>;
+    dormant_days: z.ZodNullable<z.ZodInt>;
+}, z.core.$strict>;
+export type VerifiedCredentialPayloadV3 = z.infer<typeof VerifiedCredentialPayloadV3>;
 export declare const SealPayload: z.ZodUnion<readonly [z.ZodObject<{
     iss: z.ZodEnum<{
         "sealkeeper.run": "sealkeeper.run";
@@ -293,7 +451,7 @@ export declare const SealPayload: z.ZodUnion<readonly [z.ZodObject<{
         provenance: "provenance";
         reliability: "reliability";
         safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
     counts: z.ZodObject<{
         events: z.ZodInt;
         history_days: z.ZodInt;
@@ -347,7 +505,7 @@ export declare const SealPayload: z.ZodUnion<readonly [z.ZodObject<{
         provenance: "provenance";
         reliability: "reliability";
         safety: "safety";
-    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
     counts: z.ZodObject<{
         events: z.ZodInt;
         history_days: z.ZodInt;
@@ -385,6 +543,79 @@ export declare const SealPayload: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strict>>;
     last_active: z.ZodNullable<z.ZodInt>;
     dormant_days: z.ZodNullable<z.ZodInt>;
+}, z.core.$strict>, z.ZodObject<{
+    iss: z.ZodEnum<{
+        "sealkeeper.run": "sealkeeper.run";
+        "vouched.run": "vouched.run";
+    }>;
+    sub: z.ZodString;
+    ver: z.ZodLiteral<3>;
+    iat: z.ZodInt;
+    exp: z.ZodInt;
+    agent_version: z.ZodString;
+    level: z.ZodEnum<{
+        bronze: "bronze";
+        gold: "gold";
+        none: "none";
+        silver: "silver";
+    }>;
+    scores: z.ZodRecord<z.ZodUnion<readonly [z.ZodEnum<{
+        cost_latency: "cost_latency";
+        provenance: "provenance";
+        reliability: "reliability";
+        safety: "safety";
+    }>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    counts: z.ZodObject<{
+        events: z.ZodInt;
+        history_days: z.ZodInt;
+        verified_tasks: z.ZodInt;
+        seed_tasks: z.ZodInt;
+        server_checked_tasks: z.ZodInt;
+        confirmed_tasks: z.ZodInt;
+        distinct_operators: z.ZodInt;
+        safety_incidents_90d: z.ZodInt;
+        posted_tasks: z.ZodInt;
+        posted_distinct_operators: z.ZodInt;
+        posted_confirmed_tasks: z.ZodInt;
+    }, z.core.$strict>;
+    counted: z.ZodObject<{
+        verified_tasks: z.ZodInt;
+        seed_tasks: z.ZodInt;
+        server_checked_tasks: z.ZodInt;
+        confirmed_tasks: z.ZodInt;
+        posted_tasks: z.ZodInt;
+        posted_confirmed_tasks: z.ZodInt;
+    }, z.core.$strict>;
+    fingerprint: z.ZodNullable<z.ZodObject<{
+        hash: z.ZodString;
+        at: z.ZodInt;
+    }, z.core.$strict>>;
+    state: z.ZodEnum<{
+        changed: "changed";
+        matches: "matches";
+        provisional: "provisional";
+    }>;
+    operator: z.ZodObject<{
+        verified: z.ZodBoolean;
+    }, z.core.$strict>;
+    identity: z.ZodArray<z.ZodObject<{
+        provider: z.ZodURL;
+        kind: z.ZodUnion<readonly [z.ZodEnum<{
+            kya: "kya";
+            oidc: "oidc";
+            saml: "saml";
+            verifiable_credential: "verifiable_credential";
+        }>, z.ZodURL]>;
+        ref: z.ZodString;
+        subject_hash: z.ZodString;
+        attested_at: z.ZodInt;
+        scope: z.ZodEnum<{
+            agent: "agent";
+            operator: "operator";
+        }>;
+    }, z.core.$strict>>;
+    last_active: z.ZodNullable<z.ZodInt>;
+    dormant_days: z.ZodNullable<z.ZodInt>;
 }, z.core.$strict>]>;
 export type SealPayload = z.infer<typeof SealPayload>;
 export declare const sealCounted: (p: SealPayload) => CountedCounts | null;
@@ -437,13 +668,14 @@ export declare const SealExtension: z.ZodObject<{
     description: z.ZodString;
     params: z.ZodObject<{
         credential: z.ZodString;
+        handshake: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type SealExtension = z.infer<typeof SealExtension>;
 export declare const credentialExtension: (jws: string) => CredentialExtension;
 export declare const legacySealExtension: (jws: string) => LegacySealExtension;
-export declare const sealExtension: (jws: string) => SealExtension;
-export declare const sealExtensions: (jws: string) => ({
+export declare const sealExtension: (jws: string, handshake?: string) => SealExtension;
+export declare const sealExtensions: (jws: string, handshake?: string) => ({
     uri: "https://vouched.run/ext/credential/v1";
     description: string;
     params: {
@@ -460,6 +692,7 @@ export declare const sealExtensions: (jws: string) => ({
     description: string;
     params: {
         credential: string;
+        handshake?: string | undefined;
     };
 })[];
 export declare const A2A_PROTOCOL_VERSION = "0.3.0";
@@ -483,6 +716,7 @@ export declare const AgentCard: z.ZodObject<{
             description: z.ZodString;
             params: z.ZodObject<{
                 credential: z.ZodString;
+                handshake: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>;
         }, z.core.$strict>, z.ZodObject<{
             uri: z.ZodLiteral<"https://vouched.run/ext/seal/v1">;

package/dist/credential.js

@@ -1,9 +1,10 @@
 import { z } from 'zod';
 import { AgentId, Ed25519PublicKey } from './agent-id.js';
-import { Dimension } from './dimensions.js';
+import { AcceptedDimension, Dimension } from './dimensions.js';
 import { Jws } from './envelope.js';
 import { StoredVersion } from './events.js';
-import { CountedCounts, Level, StandingCounts } from './standing.js';
+import { HANDSHAKE_MAX_CHARS } from './handshake.js';
+import { CountedCounts, CountedCountsV3, Level, StandingCounts, StandingCountsV3, } from './standing.js';
 // The issuer every SEAL carries as iss from the SealKeeper cutover on.
 export const CREDENTIAL_ISSUER = 'sealkeeper.run';
 // Issuers a verifier still accepts for a while after the cutover. A SEAL
@@ -50,11 +51,14 @@ const Count = z.int().min(0);
 // The version of the SEAL standard this issuer writes, carried as ver.
 export const SEAL_VERSION = 1;
 // Every version a verifier understands. Version 2 is version 1 plus
-// `counted`, the counted evidence the level read (VOU-139). CLIs 0.4.x
-// understand version 1 only and refuse any other ver, so the issuer keeps
-// writing version 1 until they are gone, and verifiers from this release
-// on accept both. SEAL standard section 9.
-export const SEAL_VERSIONS = [1, 2];
+// `counted`, the counted evidence the level read (VOU-139). Version 3 is
+// version 2 plus the posted counts, `fingerprint` and `state`, with the
+// deprecated `version` dropped (VOU-77). CLIs before 0.4.5 understand
+// version 1 only, and CLIs before 0.4.11 do not understand version 3, and
+// each refuses a ver it does not know. So the issuer keeps writing version
+// 1 until every CLI before 0.4.11 is gone. Verifiers accept all three from
+// CLI 0.4.11 on. SEAL standard section 9.
+export const SEAL_VERSIONS = [1, 2, 3];
 // One identity attestation reference, SEAL standard section 4a. A pointer
 // to an attestation an external provider made, never the attestation, a
 // name or a tenant id. kind is one of the four names or a URL for anything
@@ -76,8 +80,16 @@ export const IdentityReference = z.strictObject({
 // revoked, so every reference it still holds is current.
 export const operatorVerified = (identity) => identity.some((r) => r.scope === 'operator');
 // Each score is 0 to 1, or null when unearned (standard section 2). A
-// payload with a score outside that is malformed.
-const Scores = z.partialRecord(Dimension, z.number().min(0).max(1).nullable());
+// payload with a score outside that is malformed. The issuer writes the
+// base dimensions and competence by category only (Dimension). A verifier
+// also accepts competence by task type (AcceptedDimension), the key SEALs
+// carried before RT-3, so a SEAL issued before the change stays valid until
+// it expires and a verifier never has to know which keys an issuer writes
+// today. The API reads its stored SEALs back with the issued shape, so a
+// stored SEAL with a task type key fails that parse and is reissued.
+const Score = z.number().min(0).max(1).nullable();
+const IssuedScores = z.partialRecord(Dimension, Score);
+const VerifiedScores = z.partialRecord(AcceptedDimension, Score);
 // A SEAL lives at most 24 hours from issue, standard section 2. The issuer's
 // CREDENTIAL_TTL_HOURS may not go above it, and a payload whose exp is
 // further from its iat is malformed.
@@ -92,6 +104,26 @@ export const SEAL_CLOCK_SKEW_SECONDS = 300;
 // and parseSealPayload checks the clock with acceptedIssuer first.
 const IssuedIssuer = z.literal(CREDENTIAL_ISSUER);
 const VerifiedIssuer = z.enum([CREDENTIAL_ISSUER, ...LEGACY_ISSUERS]);
+// The state of a version 3 SEAL, how the agent's current fingerprint stands
+// against the one its level was last confirmed under. The set is closed.
+// matches is the only value the issuer writes until the re-check flow
+// exists. changed and provisional are reserved for it, so a verifier of
+// version 3 already reads them.
+export const SealState = z.enum(['matches', 'changed', 'provisional']);
+// The fingerprint of a version 3 SEAL. hash is SHA-256 over bytes a later
+// change to the standard defines, base64url, and a verifier treats it as
+// opaque until then. at is Unix seconds of when the level was last
+// confirmed under it, never after iat. null when the agent has sent no
+// fingerprint. A 32 byte value in base64url has 43 characters and only
+// some last characters, the rule agent-id.ts uses for a key.
+export const SealFingerprint = z
+    .strictObject({
+    hash: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/, 'SHA-256, base64url'),
+    at: Seconds,
+})
+    .nullable();
 const withinMaxTtl = (c) => c.exp - c.iat <= SEAL_MAX_TTL_SECONDS;
 const MAX_TTL_MESSAGE = 'exp must be at most 24 hours after iat';
 /*
@@ -104,7 +136,7 @@ const MAX_TTL_MESSAGE = 'exp must be at most 24 hours after iat';
  * Unix seconds of the agent's newest accepted event, null when it has sent
  * none, and dormant_days whole days since then at issue, null with it.
  */
-const v1Payload = (iss) => z
+const v1Payload = (iss, scores) => z
     .strictObject({
     iss,
     sub: AgentId,
@@ -114,7 +146,7 @@ const v1Payload = (iss) => z
     agent_version: StoredVersion,
     version: StoredVersion,
     level: Level,
-    scores: Scores,
+    scores,
     counts: StandingCounts,
     operator: z.strictObject({ verified: z.boolean() }),
     identity: z.array(IdentityReference).max(16),
@@ -129,7 +161,7 @@ const v1Payload = (iss) => z
  * counted evidence the level read (CountedCounts). counts stay the raw
  * facts. Each counted value is at most its raw count.
  */
-const v2Payload = (iss) => z
+const v2Payload = (iss, scores) => z
     .strictObject({
     iss,
     sub: AgentId,
@@ -139,7 +171,7 @@ const v2Payload = (iss) => z
     agent_version: StoredVersion,
     version: StoredVersion,
     level: Level,
-    scores: Scores,
+    scores,
     counts: StandingCounts,
     counted: CountedCounts,
     operator: z.strictObject({ verified: z.boolean() }),
@@ -153,27 +185,69 @@ const v2Payload = (iss) => z
     .refine((c) => c.counted.seed_tasks <= c.counts.seed_tasks &&
     c.counted.server_checked_tasks <= c.counts.server_checked_tasks &&
     c.counted.confirmed_tasks <= c.counts.confirmed_tasks, 'counted must not exceed counts');
-// The issuer side. iss is CREDENTIAL_ISSUER only.
-export const CredentialPayload = v1Payload(IssuedIssuer);
-export const CredentialPayloadV2 = v2Payload(IssuedIssuer);
-// The verifier side. iss may also be a LEGACY_ISSUERS entry. The shape has
+/*
+ * Version 3. Every version 2 field with the same meaning except version,
+ * which is dropped (VOU-77), so agent_version alone names the agent
+ * version. counts gains the three posted counts (StandingCountsV3), counted
+ * gains the counted twins of posted_tasks and posted_confirmed_tasks
+ * (CountedCountsV3), and fingerprint and state are new. Each counted value
+ * is at most its raw count, and fingerprint.at is not after iat. Nothing
+ * issues it yet.
+ */
+const v3Payload = (iss, scores) => z
+    .strictObject({
+    iss,
+    sub: AgentId,
+    ver: z.literal(3),
+    iat: Seconds,
+    exp: Seconds,
+    agent_version: StoredVersion,
+    level: Level,
+    scores,
+    counts: StandingCountsV3,
+    counted: CountedCountsV3,
+    fingerprint: SealFingerprint,
+    state: SealState,
+    operator: z.strictObject({ verified: z.boolean() }),
+    identity: z.array(IdentityReference).max(16),
+    last_active: Seconds.nullable(),
+    dormant_days: Count.nullable(),
+})
+    .refine((c) => c.exp > c.iat, 'exp must be after iat')
+    .refine(withinMaxTtl, MAX_TTL_MESSAGE)
+    .refine((c) => c.counted.seed_tasks <= c.counts.seed_tasks &&
+    c.counted.server_checked_tasks <= c.counts.server_checked_tasks &&
+    c.counted.confirmed_tasks <= c.counts.confirmed_tasks &&
+    c.counted.posted_tasks <= c.counts.posted_tasks &&
+    c.counted.posted_confirmed_tasks <= c.counts.posted_confirmed_tasks, 'counted must not exceed counts')
+    .refine((c) => c.fingerprint === null || c.fingerprint.at <= c.iat, 'fingerprint.at must not be after iat');
+// The issuer side. iss is CREDENTIAL_ISSUER only, and scores carry
+// competence by category only.
+export const CredentialPayload = v1Payload(IssuedIssuer, IssuedScores);
+export const CredentialPayloadV2 = v2Payload(IssuedIssuer, IssuedScores);
+export const CredentialPayloadV3 = v3Payload(IssuedIssuer, IssuedScores);
+// The verifier side. iss may also be a LEGACY_ISSUERS entry, and scores may
+// also carry competence by task type. The shape has
 // no clock, so read these through parseSealPayload, never on their own.
-export const VerifiedCredentialPayload = v1Payload(VerifiedIssuer);
-export const VerifiedCredentialPayloadV2 = v2Payload(VerifiedIssuer);
-// Any payload a verifier accepts today, version 1 or version 2, from the
-// current issuer or a legacy one. Version 2 has every version 1 field with
-// the same meaning, so a reader of version 1 fields takes both.
+export const VerifiedCredentialPayload = v1Payload(VerifiedIssuer, VerifiedScores);
+export const VerifiedCredentialPayloadV2 = v2Payload(VerifiedIssuer, VerifiedScores);
+export const VerifiedCredentialPayloadV3 = v3Payload(VerifiedIssuer, VerifiedScores);
+// Any payload a verifier accepts today, version 1, 2 or 3, from the current
+// issuer or a legacy one. Each version has every field of the one before
+// with the same meaning, except version, which version 3 drops. A reader
+// takes the agent version from agent_version, which all three carry.
 export const SealPayload = z.union([
     VerifiedCredentialPayload,
     VerifiedCredentialPayloadV2,
+    VerifiedCredentialPayloadV3,
 ]);
 // The counted evidence a SEAL carries, version 2 on, null before.
 export const sealCounted = (p) => 'counted' in p ? p.counted : null;
 const hasVer = (raw) => typeof raw === 'object' && raw !== null && 'ver' in raw;
 /*
  * Whether a verifier understands the version of a signed payload. Read
- * after the signature and the issuer check out and before the shape. ver 1
- * and 2 (SEAL_VERSIONS) are understood. Any other ver is
+ * after the signature and the issuer check out and before the shape. ver 1,
+ * 2 and 3 (SEAL_VERSIONS) are understood. Any other ver is
  * unsupported_version, as section 9 of the standard says, never valid with
  * an unknown meaning. So is no ver at all, a SEAL issued before version 1,
  * whose last one expired on 26 September 2026. Anything that is not an
@@ -210,9 +284,12 @@ export function parseSealPayload(raw, nowSeconds) {
     const problem = sealVersionProblem(raw);
     if (problem)
         return { ok: false, reason: problem };
-    const parsed = (hasVer(raw) && raw.ver === 2
-        ? VerifiedCredentialPayloadV2
-        : VerifiedCredentialPayload).safeParse(raw);
+    const ver = hasVer(raw) ? raw.ver : undefined;
+    const parsed = (ver === 3
+        ? VerifiedCredentialPayloadV3
+        : ver === 2
+            ? VerifiedCredentialPayloadV2
+            : VerifiedCredentialPayload).safeParse(raw);
     return parsed.success
         ? { ok: true, payload: parsed.data }
         : { ok: false, reason: 'malformed' };
@@ -241,10 +318,17 @@ export const LegacySealExtension = z.strictObject({
     description: z.string().min(1).max(512),
     params: z.strictObject({ credential: Jws }),
 });
+// The current extension may also carry handshake, the agent's signed
+// handshake (VB-6, ./handshake.ts) beside the SEAL, refreshed each time the
+// card is written. A reader takes params loosely, so one that does not know
+// handshake ignores it. The two old URIs carry the SEAL alone.
 export const SealExtension = z.strictObject({
     uri: z.literal(SEAL_EXTENSION_URI),
     description: z.string().min(1).max(512),
-    params: z.strictObject({ credential: Jws }),
+    params: z.strictObject({
+        credential: Jws,
+        handshake: Jws.max(HANDSHAKE_MAX_CHARS).optional(),
+    }),
 });
 export const credentialExtension = (jws) => ({
     uri: CREDENTIAL_EXTENSION_URI,
@@ -256,15 +340,17 @@ export const legacySealExtension = (jws) => ({
     description: EXTENSION_DESCRIPTION,
     params: { credential: jws },
 });
-export const sealExtension = (jws) => ({
+export const sealExtension = (jws, handshake) => ({
     uri: SEAL_EXTENSION_URI,
     description: EXTENSION_DESCRIPTION,
-    params: { credential: jws },
+    params: handshake === undefined
+        ? { credential: jws }
+        : { credential: jws, handshake },
 });
 // The extensions a card carries for one SEAL, in SEAL_EXTENSION_URIS order,
-// the current URI first.
-export const sealExtensions = (jws) => [
-    sealExtension(jws),
+// the current URI first. A handshake goes on the current one only.
+export const sealExtensions = (jws, handshake) => [
+    sealExtension(jws, handshake),
     legacySealExtension(jws),
     credentialExtension(jws),
 ];

package/dist/dimensions.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { TaskCategory } from './tasks.js';
 export declare const TaskType: z.ZodString;
 export type TaskType = z.infer<typeof TaskType>;
 export declare const BaseDimension: z.ZodEnum<{
@@ -8,14 +9,26 @@ export declare const BaseDimension: z.ZodEnum<{
     safety: "safety";
 }>;
 export type BaseDimension = z.infer<typeof BaseDimension>;
-export declare const CompetenceDimension: z.ZodTemplateLiteral<`competence:${string}`>;
+export declare const CompetenceDimension: z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">;
 export type CompetenceDimension = z.infer<typeof CompetenceDimension>;
+export declare const COMPETENCE_TYPES_MAX = 32;
+export declare const COMPETENCE_DIMENSIONS: readonly CompetenceDimension[];
 export declare const Dimension: z.ZodUnion<readonly [z.ZodEnum<{
     cost_latency: "cost_latency";
     provenance: "provenance";
     reliability: "reliability";
     safety: "safety";
-}>, z.ZodTemplateLiteral<`competence:${string}`>]>;
+}>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">]>;
 export type Dimension = z.infer<typeof Dimension>;
-export declare const competence: (taskType: TaskType) => CompetenceDimension;
+export declare const TypeCompetenceDimension: z.ZodTemplateLiteral<`competence:${string}`>;
+export type TypeCompetenceDimension = z.infer<typeof TypeCompetenceDimension>;
+export declare const AcceptedDimension: z.ZodUnion<readonly [z.ZodEnum<{
+    cost_latency: "cost_latency";
+    provenance: "provenance";
+    reliability: "reliability";
+    safety: "safety";
+}>, z.ZodTemplateLiteral<"competence:code" | "competence:conversation" | "competence:data" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">, z.ZodTemplateLiteral<`competence:${string}`>]>;
+export type AcceptedDimension = z.infer<typeof AcceptedDimension>;
+export declare const competence: (category: TaskCategory) => CompetenceDimension;
+export declare const categoryOf: (dimension: string) => TaskCategory | null;
 export declare const isTrustDimension: (dimension: string) => boolean;