@vouched-dev/schema 0.1.0

package/dist/api.js

@@ -0,0 +1,260 @@
+import { z } from 'zod';
+import { AgentId } from './agent-id.js';
+import { utf8Encode } from './base64url.js';
+import { CredentialPayload } from './credential.js';
+import { Dimension, TaskType } from './dimensions.js';
+import { Jws } from './envelope.js';
+import { Version } from './events.js';
+import { Sha256Hex, TaskOutcome, TaskState, VerificationSpec, } from './tasks.js';
+export const MAX_EVENTS_PER_BATCH = 500;
+export const MAX_ENVELOPE_CHARS = 4096;
+export const MAX_TASK_SPEC_BYTES = 16384;
+// Measured as the UTF-8 bytes of the submission's JSON encoding, which is
+// what gets signed. Counting chars would let escapes and multi-byte text
+// grow the envelope past its cap.
+export const MAX_SUBMISSION_BYTES = 65536;
+// Task writes carry a spec or a submission, so their envelopes are larger
+// than an event's. The largest submission payload is about 64K bytes of
+// JSON, which base64url encodes to about 88K chars. The largest post (spec
+// plus jsonSchema, 16K bytes each) is about 45K chars. Both fit.
+export const MAX_TASK_ENVELOPE_CHARS = 131072;
+// A task without expiresAt lives this long. A later expiresAt is capped.
+export const TASK_DEFAULT_TTL_HOURS = 24;
+export const TASK_MAX_TTL_DAYS = 7;
+const Timestamp = z.iso.datetime();
+const Limit = z.coerce.number().int().min(1).max(100).default(50);
+export const AgentParams = z.strictObject({ id: AgentId });
+export const TaskParams = z.strictObject({ id: z.uuid() });
+// The body of a signed task write.
+export const SignedTaskRequest = z.strictObject({
+    envelope: Jws.max(MAX_TASK_ENVELOPE_CHARS),
+});
+export const RegisterAgentRequest = z.strictObject({
+    publicKey: AgentId,
+    githubToken: z.string().min(1).max(256),
+    name: z.string().min(1).max(64),
+    version: Version,
+});
+export const AgentResponse = z.strictObject({
+    id: AgentId,
+    name: z.string().min(1).max(64),
+    version: Version,
+    operator: z.strictObject({ login: z.string().min(1).max(39) }),
+    createdAt: Timestamp,
+});
+export const AgentCardResponse = z.looseObject({
+    name: z.string(),
+    capabilities: z.looseObject({
+        extensions: z.array(z.looseObject({
+            uri: z.string(),
+            description: z.string().optional(),
+            params: z.record(z.string(), z.unknown()).optional(),
+        })),
+    }),
+});
+export const EventsBatchRequest = z.strictObject({
+    envelopes: z
+        .array(Jws.max(MAX_ENVELOPE_CHARS))
+        .min(1)
+        .max(MAX_EVENTS_PER_BATCH),
+});
+// accepted counts rows newly stored. duplicates counts events already stored
+// for this agent (same event_id), which are skipped, so a retry is safe.
+export const EventsBatchResponse = z.strictObject({
+    accepted: z.int().min(0),
+    duplicates: z.int().min(0),
+});
+const TaskSpec = z
+    .record(z.string(), z.unknown())
+    .refine((spec) => utf8Encode(JSON.stringify(spec)).length <= MAX_TASK_SPEC_BYTES, `spec must be at most ${MAX_TASK_SPEC_BYTES} bytes`);
+// taskId is generated by the client and becomes the task id, so a retried
+// post is a no-op. The same poster gets the existing task back, any other
+// poster gets 409.
+export const PostTaskRequest = z.strictObject({
+    taskId: z.uuid(),
+    taskType: TaskType,
+    spec: TaskSpec,
+    verification: VerificationSpec,
+    expiresAt: Timestamp.optional(),
+});
+export const TaskResponse = z.strictObject({
+    id: z.uuid(),
+    posterAgentId: AgentId,
+    claimantAgentId: AgentId.nullable(),
+    taskType: TaskType,
+    spec: z.record(z.string(), z.unknown()),
+    verification: VerificationSpec,
+    state: TaskState,
+    postedAt: Timestamp,
+    claimedAt: Timestamp.nullable(),
+    submittedAt: Timestamp.nullable(),
+    verifiedAt: Timestamp.nullable(),
+    expiresAt: Timestamp,
+    // Present only in responses to the poster or the claimant.
+    submission: z.string().optional(),
+});
+// Claim and submit payloads name the task they are for, and the server checks
+// it against the path. Without it a signed claim for one task could be
+// replayed against any other.
+export const ClaimTaskRequest = z.strictObject({ taskId: z.uuid() });
+export const SubmitTaskRequest = z.strictObject({
+    taskId: z.uuid(),
+    submission: z
+        .string()
+        .refine((text) => utf8Encode(JSON.stringify(text)).length <= MAX_SUBMISSION_BYTES, `submission must be at most ${MAX_SUBMISSION_BYTES} bytes as JSON`),
+});
+// Named for its task like claim and submit, checked against the path.
+export const TaskOutcomeRequest = z.strictObject({
+    taskId: z.uuid(),
+    outcome: TaskOutcome,
+    evidenceHash: Sha256Hex.optional(),
+});
+export const ListTasksQuery = z.strictObject({
+    state: TaskState.default('open'),
+    taskType: TaskType.optional(),
+    limit: Limit,
+});
+export const ListTasksResponse = z.strictObject({
+    tasks: z.array(TaskResponse),
+});
+// The body of a signed rating. A rating payload is small, so it takes the
+// event envelope cap.
+export const SignedRatingRequest = z.strictObject({
+    envelope: Jws.max(MAX_ENVELOPE_CHARS),
+});
+export const RatingValue = z.int().min(1).max(5);
+// One rater rates one ratee on one dimension. A new rating on the same
+// dimension replaces the old one. issuedAt is signed with the rest, so an
+// old envelope sent again can never replace a newer rating.
+export const RatingRequest = z.strictObject({
+    rateeAgentId: AgentId,
+    dimension: Dimension,
+    value: RatingValue,
+    issuedAt: Timestamp,
+});
+// The stored rating. raterScoreAtTime is the rater's score when it rated,
+// which is the weight the rating carries in scoring.
+export const RatingResponse = z.strictObject({
+    rateeAgentId: AgentId,
+    dimension: Dimension,
+    value: RatingValue,
+    raterScoreAtTime: z.number().min(0).max(1),
+});
+// A base dimension with no row is still listed, with every field after
+// dimension null. Competence entries appear only where a row exists.
+export const ScoreEntry = z.strictObject({
+    version: Version,
+    dimension: Dimension,
+    value: z.number().min(0).max(1).nullable(),
+    windowStart: Timestamp.nullable(),
+    windowEnd: Timestamp.nullable(),
+    computedAt: Timestamp.nullable(),
+});
+// The agent's current version only.
+export const ScoreResponse = z.strictObject({
+    agentId: AgentId,
+    scores: z.array(ScoreEntry),
+});
+export const CredentialResponse = z.strictObject({
+    credential: Jws,
+    payload: CredentialPayload,
+});
+export const LeaderboardQuery = z.strictObject({
+    dimension: Dimension,
+    limit: Limit,
+});
+// Rows on the current version only, ranked by value, highest first. Ties go
+// to the value computed first.
+export const LeaderboardEntry = z.strictObject({
+    rank: z.int().min(1),
+    agentId: AgentId,
+    name: z.string().min(1).max(64),
+    operator: z.strictObject({ login: z.string().min(1).max(39) }),
+    version: Version,
+    value: z.number().min(0).max(1),
+    // Tasks this agent claimed that reached verified, across all versions.
+    verifiedTasks: z.int().min(0),
+});
+export const LeaderboardResponse = z.strictObject({
+    dimension: Dimension,
+    entries: z.array(LeaderboardEntry),
+});
+// The public feed. Payloads carry public facts only. Never an operator
+// email, an envelope, a spec or a submission.
+export const FeedKind = z.enum([
+    'registration',
+    'task_verified',
+    'score_change',
+    'flag',
+]);
+// The one flag code today. Two sides of a counterparty task disagreed.
+export const FeedFlagCode = z.enum(['outcome_disagreement']);
+const FeedAgent = {
+    agentId: AgentId,
+    name: z.string().min(1).max(64),
+};
+export const FeedPayloads = {
+    registration: z.strictObject({ ...FeedAgent, version: Version }),
+    task_verified: z.strictObject({
+        ...FeedAgent,
+        taskId: z.uuid(),
+        taskType: TaskType,
+    }),
+    score_change: z.strictObject({
+        ...FeedAgent,
+        version: Version,
+        dimension: Dimension,
+        // null when the dimension had no value before.
+        old: z.number().min(0).max(1).nullable(),
+        new: z.number().min(0).max(1),
+    }),
+    flag: z.strictObject({
+        ...FeedAgent,
+        code: FeedFlagCode,
+        taskId: z.uuid(),
+    }),
+};
+const feedItemOf = (kind) => z.strictObject({
+    // The SSE event id. Ascending in insert order.
+    id: z.int().min(1),
+    kind: z.literal(kind),
+    agentId: AgentId.nullable(),
+    payload: FeedPayloads[kind],
+    createdAt: Timestamp,
+});
+export const FeedItem = z.discriminatedUnion('kind', [
+    feedItemOf('registration'),
+    feedItemOf('task_verified'),
+    feedItemOf('score_change'),
+    feedItemOf('flag'),
+]);
+export const FEED_RECENT_MAX = 200;
+export const FeedRecentQuery = z.strictObject({
+    limit: z.coerce.number().int().min(1).max(FEED_RECENT_MAX).default(50),
+});
+// Newest first.
+export const FeedRecentResponse = z.strictObject({
+    items: z.array(FeedItem),
+});
+// Network totals for the landing page. eventsLast24h counts by the server's
+// received_at, so a client clock cannot move it.
+export const StatsResponse = z.strictObject({
+    agents: z.int().min(0),
+    verifiedTasks: z.int().min(0),
+    eventsLast24h: z.int().min(0),
+});
+export const ScoreRunResponse = z.strictObject({
+    scored: z.int().min(0),
+});
+export const ErrorIssue = z.strictObject({
+    path: z.array(z.union([z.string(), z.number()])),
+    code: z.string(),
+    message: z.string(),
+});
+export const ErrorResponse = z.strictObject({
+    error: z.strictObject({
+        code: z.string(),
+        message: z.string(),
+        issues: z.array(ErrorIssue).optional(),
+    }),
+});

package/dist/base64url.d.ts

@@ -0,0 +1,4 @@
+export declare function base64urlEncode(bytes: Uint8Array): string;
+export declare function base64urlDecode(text: string): Uint8Array<ArrayBuffer>;
+export declare const utf8Encode: (text: string) => Uint8Array<ArrayBuffer>;
+export declare const utf8Decode: (bytes: Uint8Array) => string;

package/dist/base64url.js

@@ -0,0 +1,43 @@
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const LOOKUP = new Map([...ALPHABET].map((char, i) => [char, i]));
+export function base64urlEncode(bytes) {
+    let out = '';
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = ((buffer << 8) | byte) & 0xffff;
+        bits += 8;
+        while (bits >= 6) {
+            bits -= 6;
+            out += ALPHABET[(buffer >> bits) & 63];
+        }
+    }
+    if (bits > 0)
+        out += ALPHABET[(buffer << (6 - bits)) & 63];
+    return out;
+}
+export function base64urlDecode(text) {
+    if (text.length % 4 === 1)
+        throw new Error('Invalid base64url length');
+    const out = new Uint8Array(Math.floor((text.length * 6) / 8));
+    let buffer = 0;
+    let bits = 0;
+    let j = 0;
+    for (const char of text) {
+        const value = LOOKUP.get(char);
+        if (value === undefined)
+            throw new Error('Invalid base64url character');
+        buffer = ((buffer << 6) | value) & 0xfff;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[j++] = (buffer >> bits) & 0xff;
+        }
+    }
+    if ((buffer & ((1 << bits) - 1)) !== 0) {
+        throw new Error('Non-canonical base64url');
+    }
+    return out;
+}
+export const utf8Encode = (text) => new TextEncoder().encode(text);
+export const utf8Decode = (bytes) => new TextDecoder('utf-8', { fatal: true }).decode(bytes);

package/dist/credential.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+export declare const CREDENTIAL_ISSUER = "vouched.run";
+export declare const CREDENTIAL_EXTENSION_URI = "https://vouched.run/ext/credential/v1";
+export declare const WELL_KNOWN_URL = "https://vouched.run/.well-known/vouched.json";
+export declare const CredentialPayload: z.ZodObject<{
+    iss: z.ZodLiteral<"vouched.run">;
+    sub: z.ZodString;
+    iat: z.ZodInt;
+    exp: z.ZodInt;
+    version: z.ZodString;
+    scores: z.ZodRecord<z.ZodUnion<readonly [z.ZodEnum<{
+        cost_latency: "cost_latency";
+        provenance: "provenance";
+        reliability: "reliability";
+        safety: "safety";
+    }>, z.ZodTemplateLiteral<`competence:${string}`>]> & z.core.$partial, z.ZodNullable<z.ZodNumber>>;
+    counts: z.ZodObject<{
+        events: z.ZodInt;
+        verified_tasks: z.ZodInt;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CredentialPayload = z.infer<typeof CredentialPayload>;
+export declare const WellKnownKey: z.ZodObject<{
+    kid: z.ZodString;
+    kty: z.ZodLiteral<"OKP">;
+    crv: z.ZodLiteral<"Ed25519">;
+    alg: z.ZodLiteral<"EdDSA">;
+    x: z.ZodString;
+}, z.core.$strict>;
+export type WellKnownKey = z.infer<typeof WellKnownKey>;
+export declare const WellKnown: z.ZodObject<{
+    keys: z.ZodArray<z.ZodObject<{
+        kid: z.ZodString;
+        kty: z.ZodLiteral<"OKP">;
+        crv: z.ZodLiteral<"Ed25519">;
+        alg: z.ZodLiteral<"EdDSA">;
+        x: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WellKnown = z.infer<typeof WellKnown>;
+export declare const CredentialExtension: z.ZodObject<{
+    uri: z.ZodLiteral<"https://vouched.run/ext/credential/v1">;
+    description: z.ZodString;
+    params: z.ZodObject<{
+        credential: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CredentialExtension = z.infer<typeof CredentialExtension>;
+export declare const credentialExtension: (jws: string) => CredentialExtension;
+export declare const A2A_PROTOCOL_VERSION = "0.3.0";
+export declare const AgentSkill: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type AgentSkill = z.infer<typeof AgentSkill>;
+export declare const AgentCard: z.ZodObject<{
+    protocolVersion: z.ZodLiteral<"0.3.0">;
+    name: z.ZodString;
+    description: z.ZodString;
+    url: z.ZodOptional<z.ZodURL>;
+    version: z.ZodString;
+    capabilities: z.ZodObject<{
+        extensions: z.ZodArray<z.ZodObject<{
+            uri: z.ZodLiteral<"https://vouched.run/ext/credential/v1">;
+            description: z.ZodString;
+            params: z.ZodObject<{
+                credential: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    skills: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        tags: z.ZodArray<z.ZodString>;
+        examples: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    defaultInputModes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    defaultOutputModes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type AgentCard = z.infer<typeof AgentCard>;
+export type AgentCardInput = z.input<typeof AgentCard>;

package/dist/credential.js

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import { AgentId, Ed25519PublicKey } from './agent-id.js';
+import { Dimension } from './dimensions.js';
+import { Jws } from './envelope.js';
+import { Version } from './events.js';
+export const CREDENTIAL_ISSUER = 'vouched.run';
+export const CREDENTIAL_EXTENSION_URI = 'https://vouched.run/ext/credential/v1';
+export const WELL_KNOWN_URL = 'https://vouched.run/.well-known/vouched.json';
+const Seconds = z.int().min(0);
+const Count = z.int().min(0);
+export const CredentialPayload = z
+    .strictObject({
+    iss: z.literal(CREDENTIAL_ISSUER),
+    sub: AgentId,
+    iat: Seconds,
+    exp: Seconds,
+    version: Version,
+    scores: z.partialRecord(Dimension, z.number().nullable()),
+    counts: z.strictObject({ events: Count, verified_tasks: Count }),
+})
+    .refine((c) => c.exp > c.iat, 'exp must be after iat');
+export const WellKnownKey = z.strictObject({
+    kid: z.string().min(1).max(128),
+    kty: z.literal('OKP'),
+    crv: z.literal('Ed25519'),
+    alg: z.literal('EdDSA'),
+    x: Ed25519PublicKey,
+});
+export const WellKnown = z.strictObject({
+    keys: z.array(WellKnownKey).min(1).max(16),
+});
+const EXTENSION_DESCRIPTION = `Vouched reputation credential. JWS compact, EdDSA, verify offline with the keys at ${WELL_KNOWN_URL}`;
+export const CredentialExtension = z.strictObject({
+    uri: z.literal(CREDENTIAL_EXTENSION_URI),
+    description: z.string().min(1).max(512),
+    params: z.strictObject({ credential: Jws }),
+});
+export const credentialExtension = (jws) => ({
+    uri: CREDENTIAL_EXTENSION_URI,
+    description: EXTENSION_DESCRIPTION,
+    params: { credential: jws },
+});
+export const A2A_PROTOCOL_VERSION = '0.3.0';
+export const AgentSkill = z.strictObject({
+    id: z.string().min(1).max(128),
+    name: z.string().min(1).max(128),
+    description: z.string().min(1).max(1024),
+    tags: z.array(z.string().min(1).max(64)).max(32),
+    examples: z.array(z.string().min(1).max(1024)).max(32).optional(),
+});
+const Modes = z.array(z.string().min(1).max(128)).max(32).default(['text']);
+// The subset of the A2A agent card that Vouched emits, strict so the CLI
+// never writes a field it did not mean to. Reading someone else's card uses
+// the loose AgentCardResponse instead.
+export const AgentCard = z.strictObject({
+    protocolVersion: z.literal(A2A_PROTOCOL_VERSION),
+    name: z.string().min(1).max(128),
+    description: z.string().min(1).max(1024),
+    url: z.url({ protocol: /^https$/ }).optional(),
+    version: z.string().min(1).max(64),
+    capabilities: z.strictObject({
+        extensions: z.array(CredentialExtension).max(8),
+    }),
+    skills: z.array(AgentSkill).max(64),
+    defaultInputModes: Modes,
+    defaultOutputModes: Modes,
+});

package/dist/db/agents.d.ts

@@ -0,0 +1,128 @@
+export declare const agents: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "agents";
+    schema: undefined;
+    columns: {
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "agents";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "updated_at";
+            tableName: "agents";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "agents";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        operatorId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "operator_id";
+            tableName: "agents";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "agents";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        version: import("drizzle-orm/pg-core").PgColumn<{
+            name: "version";
+            tableName: "agents";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        card: import("drizzle-orm/pg-core").PgColumn<{
+            name: "card";
+            tableName: "agents";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>;
+export type Agent = typeof agents.$inferSelect;
+export type NewAgent = typeof agents.$inferInsert;

package/dist/db/agents.js

@@ -0,0 +1,31 @@
+import { sql } from 'drizzle-orm';
+import { check, jsonb, pgTable, text, uuid } from 'drizzle-orm/pg-core';
+import { operators } from './operators.js';
+import { timestamps } from './timestamps.js';
+// How a Drizzle table is declared.
+//
+// pgTable(sqlName, columns, extras) returns a table object. Queries use it,
+// as in db.select().from(agents), and drizzle-kit diffs it to write
+// migrations.
+//
+// columns maps a TypeScript property to a column builder. The first argument
+// of each builder is the SQL column name, so the property is camelCase in
+// code and snake_case in the database. Builders chain constraints such as
+// .notNull(), .primaryKey() and .references(() => operators.id). The arrow in
+// references() lets tables point at each other regardless of file order.
+//
+// ...timestamps spreads the shared created_at and updated_at columns in.
+//
+// extras receives the built columns and returns table level constraints and
+// indexes. Here it is a check constraint written as raw SQL. The agent id is
+// the ed25519 public key, 32 bytes, base64url without padding, so 43 chars.
+export const agents = pgTable('agents', {
+    id: text('id').primaryKey(),
+    operatorId: uuid('operator_id')
+        .notNull()
+        .references(() => operators.id),
+    name: text('name').notNull(),
+    version: text('version').notNull(),
+    card: jsonb('card'),
+    ...timestamps,
+}, (t) => [check('agents_id_length', sql `length(${t.id}) = 43`)]);