@sealkeeper/schema 0.0.1 → 0.4.1

package/dist/db/tasks.js

@@ -0,0 +1,49 @@
+import { sql } from 'drizzle-orm';
+import { index, jsonb, pgTable, text, timestamp, uuid, } from 'drizzle-orm/pg-core';
+import { agents } from './agents.js';
+import { timestamps } from './timestamps.js';
+export const tasks = pgTable('tasks', {
+    id: uuid('id').primaryKey(),
+    posterAgentId: text('poster_agent_id')
+        .notNull()
+        .references(() => agents.id),
+    claimantAgentId: text('claimant_agent_id').references(() => agents.id),
+    taskType: text('task_type').notNull(),
+    spec: jsonb('spec').notNull(),
+    verification: jsonb('verification').notNull(),
+    postedAt: timestamp('posted_at', { withTimezone: true })
+        .notNull()
+        .defaultNow(),
+    claimedAt: timestamp('claimed_at', { withTimezone: true }),
+    submittedAt: timestamp('submitted_at', { withTimezone: true }),
+    verifiedAt: timestamp('verified_at', { withTimezone: true }),
+    // What the claimant submitted, null until submit. Only the poster and the
+    // claimant may read it. Wrapped in an object because a bare jsonb string
+    // does not survive a read. postgres-js parses jsonb and Drizzle then
+    // JSON.parses any string it gets back, so "123" would return as 123.
+    submission: jsonb('submission').$type(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    ...timestamps,
+}, 
+/*
+ * Secondary indexes, one per hot read. A partial index, shown once, keeps
+ * only the rows its where clause matches, so the open and claimed lists
+ * stay small however many tasks have settled. The where clauses match the
+ * state derivation in apps/api/src/routes/tasks.ts (stateWhere).
+ */
+(t) => [
+    // The open task cap per poster, and a deletion's tasks by poster.
+    index('tasks_poster_agent_id_idx').on(t.posterAgentId),
+    // The claim cap per claimant, activity counts, scoring and evidence.
+    index('tasks_claimant_agent_id_idx').on(t.claimantAgentId),
+    // GET /v1/tasks?state=open, oldest first.
+    index('tasks_open_posted_at_idx')
+        .on(t.postedAt, t.id)
+        .where(sql `${t.claimedAt} is null and ${t.verifiedAt} is null`),
+    // GET /v1/tasks?state=claimed, oldest first.
+    index('tasks_claimed_posted_at_idx')
+        .on(t.postedAt, t.id)
+        .where(sql `${t.claimedAt} is not null and ${t.submittedAt} is null and ${t.verifiedAt} is null`),
+    // Evidence counts over the window and the verified task count in stats.
+    index('tasks_verified_at_idx').on(t.verifiedAt),
+]);

package/dist/db/timestamps.d.ts

@@ -0,0 +1,4 @@
+export declare const timestamps: {
+    createdAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<"created_at">>>;
+    updatedAt: import("drizzle-orm").HasDefault<import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTimestampBuilderInitial<"updated_at">>>;
+};

package/dist/db/timestamps.js

@@ -0,0 +1,24 @@
+import { timestamp } from 'drizzle-orm/pg-core';
+// Shared columns for every table except events.
+//
+// A column builder like timestamp('created_at', ...) describes a column but
+// is not bound to a table yet. pgTable binds it when the table is declared,
+// so one plain object of builders can be spread into many tables.
+//
+//   export const agents = pgTable('agents', {
+//     id: text('id').primaryKey(),
+//     ...timestamps,
+//   });
+//
+// Both columns are set by the database. defaultNow() fills them on insert and
+// the set_updated_at() trigger in the second migration bumps updated_at on
+// every update. We do not use Drizzle's $onUpdate, because that only runs
+// when the update goes through Drizzle.
+export const timestamps = {
+    createdAt: timestamp('created_at', { withTimezone: true })
+        .notNull()
+        .defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true })
+        .notNull()
+        .defaultNow(),
+};

package/dist/db/url.d.ts

@@ -0,0 +1,12 @@
+import type { Options } from 'postgres';
+/**
+ * Turns DATABASE_URL into arguments for postgres.js.
+ *
+ * On Cloud Run the URL uses the Cloud SQL socket form with an empty host,
+ * `postgres://user:pass@/db?host=/cloudsql/project:region:instance`.
+ * postgres.js cannot parse an empty host and ignores `?host=`, so this moves
+ * the socket directory into the `path` option. Other URLs pass through.
+ *
+ * Errors never include the URL, because it carries the password.
+ */
+export declare function pgArgs(databaseUrl: string): [string, Options<never>];

package/dist/db/url.js

@@ -0,0 +1,25 @@
+/**
+ * Turns DATABASE_URL into arguments for postgres.js.
+ *
+ * On Cloud Run the URL uses the Cloud SQL socket form with an empty host,
+ * `postgres://user:pass@/db?host=/cloudsql/project:region:instance`.
+ * postgres.js cannot parse an empty host and ignores `?host=`, so this moves
+ * the socket directory into the `path` option. Other URLs pass through.
+ *
+ * Errors never include the URL, because it carries the password.
+ */
+export function pgArgs(databaseUrl) {
+    const withHost = databaseUrl.replace(/^(postgres(?:ql)?:\/\/[^/@]*@)\//, '$1localhost/');
+    let u;
+    try {
+        u = new URL(withHost);
+    }
+    catch {
+        throw new Error('DATABASE_URL is not a valid postgres URL');
+    }
+    const socketDir = u.searchParams.get('host');
+    if (!socketDir)
+        return [databaseUrl, {}];
+    u.searchParams.delete('host');
+    return [u.toString(), { path: `${socketDir}/.s.PGSQL.${u.port || 5432}` }];
+}

package/dist/dimensions.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export declare const TaskType: z.ZodString;
+export type TaskType = z.infer<typeof TaskType>;
+export declare const BaseDimension: z.ZodEnum<{
+    cost_latency: "cost_latency";
+    provenance: "provenance";
+    reliability: "reliability";
+    safety: "safety";
+}>;
+export type BaseDimension = z.infer<typeof BaseDimension>;
+export declare const CompetenceDimension: z.ZodTemplateLiteral<`competence:${string}`>;
+export type CompetenceDimension = z.infer<typeof CompetenceDimension>;
+export declare const Dimension: z.ZodUnion<readonly [z.ZodEnum<{
+    cost_latency: "cost_latency";
+    provenance: "provenance";
+    reliability: "reliability";
+    safety: "safety";
+}>, z.ZodTemplateLiteral<`competence:${string}`>]>;
+export type Dimension = z.infer<typeof Dimension>;
+export declare const competence: (taskType: TaskType) => CompetenceDimension;
+export declare const isTrustDimension: (dimension: string) => boolean;

package/dist/dimensions.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export const TaskType = z.string().regex(/^[a-z0-9_-]{1,32}$/);
+export const BaseDimension = z.enum([
+    'reliability',
+    'safety',
+    'cost_latency',
+    'provenance',
+]);
+export const CompetenceDimension = z.templateLiteral(['competence:', TaskType]);
+export const Dimension = z.union([BaseDimension, CompetenceDimension]);
+export const competence = (taskType) => CompetenceDimension.parse(`competence:${taskType}`);
+// 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.
+export const isTrustDimension = (dimension) => dimension !== 'cost_latency';

package/dist/envelope.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare const Jws: z.ZodString;
+export declare const JwsHeader: z.ZodObject<{
+    alg: z.ZodLiteral<"EdDSA">;
+    kid: z.ZodString;
+}, z.core.$strict>;
+export type JwsHeader = z.infer<typeof JwsHeader>;
+export declare class EnvelopeError extends Error {
+    name: string;
+}
+export declare function sign(payload: unknown, privateKey: Uint8Array, kid: string): Promise<string>;
+export declare function decodeHeader(jws: string): JwsHeader;
+export declare function verify(jws: string, publicKey: Uint8Array): Promise<{
+    header: JwsHeader;
+    payload: unknown;
+}>;

package/dist/envelope.js

@@ -0,0 +1,70 @@
+import { signAsync, verifyAsync } from '@noble/ed25519';
+import { z } from 'zod';
+import { base64urlDecode, base64urlEncode, utf8Decode, utf8Encode, } from './base64url.js';
+// The outer cap matches the API body limit. Routes set a tighter one.
+export const Jws = z
+    .string()
+    .max(262144)
+    .regex(/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/, 'Expected JWS compact');
+export const JwsHeader = z.strictObject({
+    alg: z.literal('EdDSA'),
+    kid: z.string().min(1).max(128),
+});
+export class EnvelopeError extends Error {
+    name = 'EnvelopeError';
+}
+function split(jws) {
+    if (!Jws.safeParse(jws).success) {
+        throw new EnvelopeError('Envelope is not three base64url parts');
+    }
+    const [header, payload, signature] = jws.split('.');
+    return { header, payload, signature };
+}
+function parseJson(part, what) {
+    try {
+        return JSON.parse(utf8Decode(base64urlDecode(part)));
+    }
+    catch {
+        throw new EnvelopeError(`Envelope ${what} is not base64url JSON`);
+    }
+}
+function parseHeader(part) {
+    const result = JwsHeader.safeParse(parseJson(part, 'header'));
+    if (!result.success) {
+        throw new EnvelopeError('Envelope header must be alg EdDSA with a kid');
+    }
+    return result.data;
+}
+export async function sign(payload, privateKey, kid) {
+    const header = JwsHeader.parse({ alg: 'EdDSA', kid });
+    const body = JSON.stringify(payload);
+    if (body === undefined)
+        throw new EnvelopeError('Payload is not JSON');
+    const signingInput = `${base64urlEncode(utf8Encode(JSON.stringify(header)))}.${base64urlEncode(utf8Encode(body))}`;
+    const signature = await signAsync(utf8Encode(signingInput), privateKey);
+    return `${signingInput}.${base64urlEncode(signature)}`;
+}
+export function decodeHeader(jws) {
+    return parseHeader(split(jws).header);
+}
+export async function verify(jws, publicKey) {
+    const parts = split(jws);
+    const signingInput = utf8Encode(`${parts.header}.${parts.payload}`);
+    let ok = false;
+    try {
+        const signature = base64urlDecode(parts.signature);
+        ok =
+            signature.length === 64 &&
+                publicKey.length === 32 &&
+                (await verifyAsync(signature, signingInput, publicKey, {
+                    zip215: false,
+                }));
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok)
+        throw new EnvelopeError('Envelope signature is invalid');
+    const header = parseHeader(parts.header);
+    return { header, payload: parseJson(parts.payload, 'payload') };
+}

package/dist/events.d.ts

@@ -0,0 +1,153 @@
+import { z } from 'zod';
+export declare const Version: z.ZodString;
+export declare const EventType: z.ZodEnum<{
+    incident: "incident";
+    "session.end": "session.end";
+    "session.start": "session.start";
+    "task.claimed": "task.claimed";
+    "task.outcome": "task.outcome";
+    "task.submitted": "task.submitted";
+    "tool.call": "tool.call";
+    usage: "usage";
+}>;
+export type EventType = z.infer<typeof EventType>;
+export declare const IncidentKind: z.ZodEnum<{
+    flagged: "flagged";
+    leak_suspected: "leak_suspected";
+    scope: "scope";
+    tool_denied: "tool_denied";
+}>;
+export type IncidentKind = z.infer<typeof IncidentKind>;
+export declare const EventPayload: {
+    'session.start': z.ZodObject<{
+        session_id: z.ZodString;
+    }, z.core.$strict>;
+    'session.end': z.ZodObject<{
+        session_id: z.ZodString;
+        duration_ms: z.ZodInt;
+    }, z.core.$strict>;
+    'tool.call': z.ZodObject<{
+        tool: z.ZodString;
+        duration_ms: z.ZodInt;
+        ok: z.ZodBoolean;
+        error_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    'task.claimed': z.ZodObject<{
+        task_id: z.ZodUUID;
+        task_type: z.ZodString;
+    }, z.core.$strict>;
+    'task.submitted': z.ZodObject<{
+        task_id: z.ZodUUID;
+        task_type: z.ZodString;
+    }, z.core.$strict>;
+    'task.outcome': z.ZodObject<{
+        task_id: z.ZodUUID;
+        outcome: z.ZodEnum<{
+            failure: "failure";
+            success: "success";
+        }>;
+        evidence_hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    incident: z.ZodObject<{
+        kind: z.ZodEnum<{
+            flagged: "flagged";
+            leak_suspected: "leak_suspected";
+            scope: "scope";
+            tool_denied: "tool_denied";
+        }>;
+        detail_hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    usage: z.ZodObject<{
+        tokens_in: z.ZodInt;
+        tokens_out: z.ZodInt;
+        latency_ms: z.ZodOptional<z.ZodInt>;
+        model: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+};
+export type EventPayload<T extends EventType> = z.infer<(typeof EventPayload)[T]>;
+export declare const Event: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    event_id: z.ZodUUID;
+    type: z.ZodLiteral<"session.start">;
+    occurred_at: z.ZodISODateTime;
+    version: z.ZodString;
+    payload: z.ZodObject<{
+        session_id: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    event_id: z.ZodUUID;
+    type: z.ZodLiteral<"session.end">;
+    occurred_at: z.ZodISODateTime;
+    version: z.ZodString;
+    payload: z.ZodObject<{
+        session_id: z.ZodString;
+        duration_ms: z.ZodInt;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    event_id: z.ZodUUID;
+    type: z.ZodLiteral<"tool.call">;
+    occurred_at: z.ZodISODateTime;
+    version: z.ZodString;
+    payload: z.ZodObject<{
+        tool: z.ZodString;
+        duration_ms: z.ZodInt;
+        ok: z.ZodBoolean;
+        error_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    event_id: z.ZodUUID;
+    type: z.ZodLiteral<"task.claimed">;
+    occurred_at: z.ZodISODateTime;
+    version: z.ZodString;
+    payload: z.ZodObject<{
+        task_id: z.ZodUUID;
+        task_type: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    event_id: z.ZodUUID;
+    type: z.ZodLiteral<"task.submitted">;
+    occurred_at: z.ZodISODateTime;
+    version: z.ZodString;
+    payload: z.ZodObject<{
+        task_id: z.ZodUUID;
+        task_type: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    event_id: z.ZodUUID;
+    type: z.ZodLiteral<"task.outcome">;
+    occurred_at: z.ZodISODateTime;
+    version: z.ZodString;
+    payload: z.ZodObject<{
+        task_id: z.ZodUUID;
+        outcome: z.ZodEnum<{
+            failure: "failure";
+            success: "success";
+        }>;
+        evidence_hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    event_id: z.ZodUUID;
+    type: z.ZodLiteral<"incident">;
+    occurred_at: z.ZodISODateTime;
+    version: z.ZodString;
+    payload: z.ZodObject<{
+        kind: z.ZodEnum<{
+            flagged: "flagged";
+            leak_suspected: "leak_suspected";
+            scope: "scope";
+            tool_denied: "tool_denied";
+        }>;
+        detail_hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    event_id: z.ZodUUID;
+    type: z.ZodLiteral<"usage">;
+    occurred_at: z.ZodISODateTime;
+    version: z.ZodString;
+    payload: z.ZodObject<{
+        tokens_in: z.ZodInt;
+        tokens_out: z.ZodInt;
+        latency_ms: z.ZodOptional<z.ZodInt>;
+        model: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+export type Event = z.infer<typeof Event>;

package/dist/events.js

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { TaskType } from './dimensions.js';
+import { Sha256Hex, TaskOutcome } from './tasks.js';
+/*
+ * The Zod pattern, shown once. Every schema file in this package follows it.
+ *
+ * 1. A strict object schema rejects unknown keys, so a payload cannot carry
+ *    anything the taxonomy does not name.
+ *
+ *      const ToolCall = z.strictObject({ tool: Name, ok: z.boolean() });
+ *      ToolCall.parse({ tool: 'Bash', ok: true, prompt: 'hi' });  // throws
+ *
+ * 2. A discriminated union picks the member schema by one literal field, so
+ *    `type` decides which payload schema runs and errors name the right one.
+ *
+ *      const Event = z.discriminatedUnion('type', [
+ *        z.strictObject({ type: z.literal('tool.call'), payload: ToolCall }),
+ *        z.strictObject({ type: z.literal('usage'), payload: Usage }),
+ *      ]);
+ *
+ * 3. z.infer derives the TypeScript type from the schema. The schema and the
+ *    type share one name, so `Event` works as a value and as a type.
+ *
+ *      export type Event = z.infer<typeof Event>;
+ *
+ * Use parse to throw on bad input and safeParse to get { success, data, error }.
+ */
+export const Version = z.string().min(1).max(32);
+const Name = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[A-Za-z0-9._:/@-]+$/);
+const Millis = z.int().min(0).max(604_800_000);
+const Count = z.int().min(0).max(100_000_000);
+export const EventType = z.enum([
+    'session.start',
+    'session.end',
+    'tool.call',
+    'task.claimed',
+    'task.submitted',
+    'task.outcome',
+    'incident',
+    'usage',
+]);
+export const IncidentKind = z.enum([
+    'scope',
+    'tool_denied',
+    'leak_suspected',
+    'flagged',
+]);
+const TaskRef = z.strictObject({ task_id: z.uuid(), task_type: TaskType });
+export const EventPayload = {
+    'session.start': z.strictObject({ session_id: Name }),
+    'session.end': z.strictObject({ session_id: Name, duration_ms: Millis }),
+    'tool.call': z.strictObject({
+        tool: Name,
+        duration_ms: Millis,
+        ok: z.boolean(),
+        error_class: Name.optional(),
+    }),
+    'task.claimed': TaskRef,
+    'task.submitted': TaskRef,
+    'task.outcome': z.strictObject({
+        task_id: z.uuid(),
+        outcome: TaskOutcome,
+        evidence_hash: Sha256Hex.optional(),
+    }),
+    incident: z.strictObject({
+        kind: IncidentKind,
+        detail_hash: Sha256Hex.optional(),
+    }),
+    // latency_ms and model are optional, since not every framework reports
+    // them. A usage event without latency_ms is no signal for cost_latency.
+    usage: z.strictObject({
+        tokens_in: Count,
+        tokens_out: Count,
+        latency_ms: Millis.optional(),
+        model: Name.optional(),
+    }),
+};
+const eventOf = (type) => z.strictObject({
+    event_id: z.uuid(),
+    type: z.literal(type),
+    occurred_at: z.iso.datetime(),
+    version: Version,
+    payload: EventPayload[type],
+});
+export const Event = z.discriminatedUnion('type', [
+    eventOf('session.start'),
+    eventOf('session.end'),
+    eventOf('tool.call'),
+    eventOf('task.claimed'),
+    eventOf('task.submitted'),
+    eventOf('task.outcome'),
+    eventOf('incident'),
+    eventOf('usage'),
+]);

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './agent-id.js';
+export * from './agent-name.js';
+export * from './api.js';
+export * from './base64url.js';
+export * from './credential.js';
+export * from './dimensions.js';
+export * from './envelope.js';
+export * from './events.js';
+export * from './standing.js';
+export * from './tasks.js';
+export * from './top-dimensions.js';
+export declare const SCHEMA_VERSION = 1;

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from './agent-id.js';
+export * from './agent-name.js';
+export * from './api.js';
+export * from './base64url.js';
+export * from './credential.js';
+export * from './dimensions.js';
+export * from './envelope.js';
+export * from './events.js';
+export * from './standing.js';
+export * from './tasks.js';
+export * from './top-dimensions.js';
+export const SCHEMA_VERSION = 1;

package/dist/seal-conformance.d.ts

@@ -0,0 +1,14 @@
+import type { SealBrokenReason } from './api.js';
+import { type WellKnown } from './credential.js';
+export type SealConformanceCase = {
+    name: string;
+    jws: string;
+    expected: 'valid' | SealBrokenReason;
+    nowSeconds?: number;
+};
+export type SealConformance = {
+    nowSeconds: number;
+    wellKnown: WellKnown;
+    cases: SealConformanceCase[];
+};
+export declare function sealConformanceCases(): Promise<SealConformance>;