@sealkeeper/schema 0.4.7 → 0.4.9

package/dist/credential.js

@@ -1,9 +1,11 @@
 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';
+import { STORED_TASK_CATEGORIES, StoredTaskCategory } from './tasks.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
@@ -47,14 +49,33 @@ export const SEAL_EXTENSION_URIS = [
 ];
 const Seconds = z.int().min(0);
 const Count = z.int().min(0);
-// The version of the SEAL standard this issuer writes, carried as ver.
+// Version 1 of the SEAL standard, the ver of a version 1 SEAL. The API
+// writes version 1, 3 or 4, whichever its SEAL_ISSUE_VERSION names.
 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). Version 4 is version 3 plus
+// `trust` and `top_categories` (VOU-560). CLIs before 0.4.5 understand
+// version 1 only, CLIs before 0.4.11 do not understand version 3 and CLIs
+// before 0.4.14 do not understand version 4, and each refuses a ver it does
+// not know. So the issuer keeps writing version 1 until every CLI before
+// the first that reads the version it moves to is gone, and then moves
+// when the API's SEAL_ISSUE_VERSION is set by hand. Verifiers accept
+// versions 1, 2 and 3 from CLI 0.4.11 on and all four from CLI 0.4.14 on.
+// SEAL standard section 9.
+export const SEAL_VERSIONS = [1, 2, 3, 4];
+// The first CLI that reads SEAL version 3, a CliVersion. Gone means no CLI
+// older than this, and no signed request without a CLI version, for
+// SEAL_V3_QUIET_DAYS whole days. GET /internal/metrics measures it from
+// the CLI version each signed request names (VOU-454), in cliVersions.
+export const SEAL_V3_FIRST_CLI = '0.4.11';
+export const SEAL_V3_QUIET_DAYS = 14;
+// The first CLI that reads SEAL version 4, a CliVersion, under the same
+// rule and the same SEAL_V3_QUIET_DAYS. It is also the first CLI that
+// names its version on a signed request, so every older one is a request
+// without a CLI version, which cliVersions already counts as old.
+export const SEAL_V4_FIRST_CLI = '0.4.14';
 // 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 +97,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.
@@ -86,12 +115,95 @@ export const SEAL_MAX_TTL_SECONDS = 24 * 3600;
 // valid. Five minutes covers clock drift between issuer and verifier.
 export const SEAL_CLOCK_SKEW_SECONDS = 300;
 // iss on the issuer side is CREDENTIAL_ISSUER and nothing else. The API
-// writes it and reads its stored SEALs back with CredentialPayload, so a
+// writes it and reads its stored SEALs back with IssuedSealPayload, so a
 // stored SEAL with a legacy issuer fails that parse and is reissued. Only
 // a verifier accepts a legacy issuer, through the Verified shapes below,
 // 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 or 4 SEAL, how the agent's current fingerprint
+// stands against the one the SEAL carries. The set is closed. matches is
+// the only value the issuer writes until the re-check flow exists, and
+// means only that the fingerprint is the one on the issuer's record at
+// issue. With a null fingerprint it says nothing. changed and provisional
+// are reserved for that flow, so a verifier of version 3 already reads
+// them.
+export const SealState = z.enum(['matches', 'changed', 'provisional']);
+// The fingerprint of a version 3 or 4 SEAL. hash is SHA-256 over bytes a later
+// change to the standard defines, base64url, and a verifier treats it as
+// opaque until then. It is the agent's current fingerprint on the issuer's
+// record at issue. at is Unix seconds of when the agent's software says it
+// captured it, never after iat, unchecked, and no level is checked against
+// it (SEAL standard section 4b). 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();
+// The most entries top_categories of a version 4 SEAL holds.
+export const SEAL_TOP_CATEGORIES_MAX = 3;
+// One entry of top_categories in a version 4 SEAL, a category of the
+// agent version's Trust Score and its score there, a whole number.
+export const SealTopCategory = z.strictObject({
+    category: StoredTaskCategory,
+    score: Count,
+});
+// A stored score as a SEAL carries it, rounded as the Trust answer rounds.
+// A value that is not a finite number, which no scoring run writes, reads 0.
+const whole = (n) => Number.isFinite(n) ? Math.max(0, Math.round(n)) : 0;
+const categoryOrder = (c) => STORED_TASK_CATEGORIES.indexOf(c);
+// Highest score first, a tie in the order of STORED_TASK_CATEGORIES, the
+// order topDimensions keeps for the competence categories. Negative when a
+// goes first.
+const bySealOrder = (a, b) => b.score - a.score || categoryOrder(a.category) - categoryOrder(b.category);
+// top_categories of a version 4 SEAL. At most SEAL_TOP_CATEGORIES_MAX,
+// each category once, in bySealOrder, so the order a verifier reads is the
+// one sealTrust writes.
+export const SealTopCategories = z
+    .array(SealTopCategory)
+    .max(SEAL_TOP_CATEGORIES_MAX)
+    .refine((list) => list.every((c, i) => i === 0 || bySealOrder(list[i - 1], c) < 0), 'top_categories must be highest first, a tie in category order, each category once');
+/*
+ * trust and top_categories of a version 4 SEAL, from the stored rows the
+ * scoring run wrote for the agent version the SEAL is for, its Trust Score
+ * (standing.trust_score) and its categories (standing.trust_categories).
+ * The issuer computes nothing new. trust is the Trust Score rounded to a
+ * whole number as GET /v1/agents/:id/trust rounds it, 0 with none stored.
+ * top_categories is the SEAL_TOP_CATEGORIES_MAX categories with the
+ * highest stored score, a tie in category order, chosen before rounding so
+ * they are the three the trust answer ranks first, save an exact tie at the
+ * third, which it breaks by name. Each is then rounded the same way and put
+ * in bySealOrder, empty with none stored. A key that is not a stored task
+ * category and an entry without a finite score are left out, and a
+ * trust_score that is not finite reads 0, so a stray stored value never
+ * stops a SEAL from being issued. The issuer reads this and nothing else
+ * for the two fields, and the verifier's shape holds the same order. A
+ * value is never below 0, as no stored score is, so a SEAL is never
+ * refused over it.
+ */
+export function sealTrust(score, categories) {
+    const stored = [];
+    for (const [key, c] of Object.entries(categories ?? {})) {
+        const category = StoredTaskCategory.safeParse(key);
+        const raw = c?.score;
+        if (category.success && typeof raw === 'number' && Number.isFinite(raw)) {
+            stored.push({ category: category.data, score: raw });
+        }
+    }
+    return {
+        trust: whole(score ?? 0),
+        top_categories: stored
+            .sort(bySealOrder)
+            .slice(0, SEAL_TOP_CATEGORIES_MAX)
+            .map((c) => ({ category: c.category, score: whole(c.score) }))
+            .sort(bySealOrder),
+    };
+}
 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 +216,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 +226,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 +241,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 +251,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 +265,119 @@ 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. The API
+ * issues it when its SEAL_ISSUE_VERSION is 3.
+ */
+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');
+/*
+ * Version 4. Every version 3 field with the same meaning, plus trust and
+ * top_categories (VOU-560, D-UI-4, D-UI-5), both from sealTrust. trust is
+ * the Trust Score of the agent version the SEAL is for, a whole number.
+ * top_categories is its highest categories, at most three, in the order
+ * SealTopCategories holds. Both are what the agent has earned, read from
+ * the issuer's own rows at issue, never a permission and never a level.
+ * The API issues it when its SEAL_ISSUE_VERSION is 4.
+ */
+const v4Payload = (iss, scores) => z
+    .strictObject({
+    iss,
+    sub: AgentId,
+    ver: z.literal(4),
+    iat: Seconds,
+    exp: Seconds,
+    agent_version: StoredVersion,
+    level: Level,
+    scores,
+    counts: StandingCountsV3,
+    counted: CountedCountsV3,
+    fingerprint: SealFingerprint,
+    state: SealState,
+    trust: Count,
+    top_categories: SealTopCategories,
+    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);
+export const CredentialPayloadV4 = v4Payload(IssuedIssuer, IssuedScores);
+// What the issuer writes, version 1, 3 or 4, whichever the API's
+// SEAL_ISSUE_VERSION names. The API serves it and reads its stored SEALs
+// back with it, so a SEAL stored before the setting changed still parses
+// and is reissued once. Version 2 is never issued.
+export const IssuedSealPayload = z.union([
+    CredentialPayload,
+    CredentialPayloadV3,
+    CredentialPayloadV4,
+]);
+// 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);
+export const VerifiedCredentialPayloadV4 = v4Payload(VerifiedIssuer, VerifiedScores);
+// Any payload a verifier accepts today, version 1, 2, 3 or 4, 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 four carry.
 export const SealPayload = z.union([
     VerifiedCredentialPayload,
     VerifiedCredentialPayloadV2,
+    VerifiedCredentialPayloadV3,
+    VerifiedCredentialPayloadV4,
 ]);
 // 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, 3 and 4 (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 +414,14 @@ 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 === 4
+        ? VerifiedCredentialPayloadV4
+        : ver === 3
+            ? VerifiedCredentialPayloadV3
+            : ver === 2
+                ? VerifiedCredentialPayloadV2
+                : VerifiedCredentialPayload).safeParse(raw);
     return parsed.success
         ? { ok: true, payload: parsed.data }
         : { ok: false, reason: 'malformed' };
@@ -241,10 +450,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 +472,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 { StoredTaskCategory } 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:math" | "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:math" | "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:math" | "competence:operations" | "competence:other" | "competence:research" | "competence:writing">, z.ZodTemplateLiteral<`competence:${string}`>]>;
+export type AcceptedDimension = z.infer<typeof AcceptedDimension>;
+export declare const competence: (category: StoredTaskCategory) => CompetenceDimension;
+export declare const categoryOf: (dimension: string) => StoredTaskCategory | null;
 export declare const isTrustDimension: (dimension: string) => boolean;

package/dist/dimensions.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { STORED_TASK_CATEGORIES, StoredTaskCategory } from './tasks.js';
 export const TaskType = z.string().regex(/^[a-z0-9_-]{1,32}$/);
 export const BaseDimension = z.enum([
     'reliability',
@@ -6,9 +7,58 @@ export const BaseDimension = z.enum([
     'cost_latency',
     'provenance',
 ]);
-export const CompetenceDimension = z.templateLiteral(['competence:', TaskType]);
+/*
+ * Competence rolls up to the task's category (RT-3), one dimension per
+ * category, competence:data and so on. The per task type values stay a
+ * breakdown under the category on the score answer and are never a
+ * dimension of their own. It reads the stored categories, conversation and
+ * other included, since a task keeps the category it was scored under
+ * (D-UI-12), so the run still scores them and a stored score or a SEAL
+ * that names one still parses until its tasks leave the window.
+ */
+export const CompetenceDimension = z.templateLiteral([
+    'competence:',
+    StoredTaskCategory,
+]);
+// The most task types a competence entry's breakdown lists, the most
+// claimed first, so the answer stays small however many free task types an
+// agent took.
+export const COMPETENCE_TYPES_MAX = 32;
+// The eight competence dimensions in stored category order, the order every
+// list shows them in. The scoring run keeps a stored competence row only
+// when it names one of them.
+export const COMPETENCE_DIMENSIONS = STORED_TASK_CATEGORIES.map((c) => CompetenceDimension.parse(`competence:${c}`));
+// What the issuer writes and what a request may name, the base dimensions
+// and the eight competence categories.
 export const Dimension = z.union([BaseDimension, CompetenceDimension]);
-export const competence = (taskType) => CompetenceDimension.parse(`competence:${taskType}`);
+/*
+ * competence:<task_type>, the competence key SEALs carried before RT-3,
+ * when competence was per task type. The issuer no longer writes it. Every category is also a valid task type, so this pattern
+ * takes both kinds of key.
+ */
+export const TypeCompetenceDimension = z.templateLiteral([
+    'competence:',
+    TaskType,
+]);
+/*
+ * Any dimension a reader accepts, issued today or before RT-3. A verifier
+ * reads SEAL scores with it, so a SEAL issued with a task type key stays
+ * valid for the rest of its 24 hours, and so do stored feed items that
+ * name one. Never used for what the issuer writes or a request names.
+ */
+export const AcceptedDimension = z.union([
+    BaseDimension,
+    CompetenceDimension,
+    TypeCompetenceDimension,
+]);
+export const competence = (category) => CompetenceDimension.parse(`competence:${category}`);
+// The category inside a competence dimension, null for any other.
+export const categoryOf = (dimension) => {
+    const parsed = CompetenceDimension.safeParse(dimension);
+    return parsed.success
+        ? parsed.data.slice('competence:'.length)
+        : null;
+};
 // Reliability, safety, provenance and every competence dimension are trust.
 // They need verified work from another operator before they get a value.
 // cost_latency comes from usage events and is information, not trust.

package/dist/fingerprint-conformance.d.ts

@@ -0,0 +1,17 @@
+import type { FingerprintParts } from './fingerprint.js';
+export type PartHashVector = {
+    name: string;
+    sub: string;
+    content: string;
+    hash: string;
+};
+export type FingerprintVector = {
+    name: string;
+    sub: string;
+    parts: FingerprintParts;
+    canonical: string;
+    hash: string;
+};
+export declare const FINGERPRINT_VECTOR_SUB = "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo";
+export declare const PART_HASH_VECTORS: readonly PartHashVector[];
+export declare const FINGERPRINT_VECTORS: readonly FingerprintVector[];

package/dist/fingerprint-conformance.js

@@ -0,0 +1,83 @@
+export const FINGERPRINT_VECTOR_SUB = '11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo';
+const sub = FINGERPRINT_VECTOR_SUB;
+const MODEL = '6soeG-P3CXqRWuQ6H4urtEb45deX7u3mbPL5-qAKQLo';
+const PROMPT = 'mLFX469k6BHZ3-B4a8L_jTSM2ZxJY3u4indqI00En-c';
+const TOOLS = 'otJ7Lv3rmxSYzTJO3fcRNAFpmWHzzovNQQJ7HT9pIO8';
+const FRAMEWORK = 'fZr0sK5GawVx1whZ8jTP7ZEHoteH22nOQS0fH4-UeOw';
+export const PART_HASH_VECTORS = [
+    {
+        name: 'empty content',
+        sub,
+        content: '',
+        hash: '92JJjLzUuso4nM82PbsP-RKqxI1cEBakXLzWFqVoYjg',
+    },
+    { name: 'one model id', sub, content: 'claude-sonnet-4-5', hash: MODEL },
+    {
+        name: 'a prompt',
+        sub,
+        content: 'You are the research agent alice runs.',
+        hash: PROMPT,
+    },
+    {
+        name: 'sorted tool lines',
+        sub,
+        content: 'mcp:github\nmcp:linear\ntool:mcp__github__create_issue',
+        hash: TOOLS,
+    },
+    {
+        name: 'a framework and its version',
+        sub,
+        content: 'claude-code@2.1.283',
+        hash: FRAMEWORK,
+    },
+];
+export const FINGERPRINT_VECTORS = [
+    {
+        name: 'every part declared',
+        sub,
+        parts: {
+            model_set: { hash: MODEL },
+            prompt: { hash: PROMPT },
+            tools: { hash: TOOLS },
+            framework: { hash: FRAMEWORK },
+        },
+        canonical: `${MODEL}\n${PROMPT}\n${TOOLS}\n${FRAMEWORK}`,
+        hash: 'unFXnGMKWNOP4f_NnbearJn0prLlxoGia2LaZcqnzy8',
+    },
+    {
+        name: 'prompt not declared',
+        sub,
+        parts: {
+            model_set: { hash: MODEL },
+            prompt: 'not_declared',
+            tools: { hash: TOOLS },
+            framework: { hash: FRAMEWORK },
+        },
+        canonical: `${MODEL}\nnot_declared\n${TOOLS}\n${FRAMEWORK}`,
+        hash: 'BHAfx6dALmCdt3aXz-g6iAjLLGDurK95DZm15ZjIVZg',
+    },
+    {
+        name: 'tools unstable, prompt not declared',
+        sub,
+        parts: {
+            model_set: { hash: MODEL },
+            prompt: 'not_declared',
+            tools: 'unstable',
+            framework: { hash: FRAMEWORK },
+        },
+        canonical: `${MODEL}\nnot_declared\nunstable\n${FRAMEWORK}`,
+        hash: 'u50ZFfkaGkhaMqciRzxv8meCaFxXycHCr9IasIEPwgk',
+    },
+    {
+        name: 'nothing declared',
+        sub,
+        parts: {
+            model_set: 'not_declared',
+            prompt: 'not_declared',
+            tools: 'not_declared',
+            framework: 'not_declared',
+        },
+        canonical: 'not_declared\nnot_declared\nnot_declared\nnot_declared',
+        hash: 'GupgdwZ9bk92irIz_drScpdSxs6gX2CrSEL9A-ndiHI',
+    },
+];