@kindgi/api 0.1.2 → 0.1.4-rc.0

package/dist/routes/judgment-flow-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgment-flow-context.js","sourceRoot":"","sources":["../../src/routes/judgment-flow-context.ts"],"names":[],"mappings":"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"}

package/dist/routes/judgments.d.ts

@@ -0,0 +1,41 @@
+import { Hono } from 'hono';
+import type { ConversationBinding } from '@kindgi/agents';
+import type { RunBinding } from '@kindgi/runtime';
+import type { FlowRegistryBinding } from '../flow-binding.js';
+import { type JudgmentRegistryBinding } from '../judgment-binding.js';
+import type { Authorizer } from '../middleware/authorize.js';
+import type { AppEnv } from '../types.js';
+/**
+ * Judgments: yes or no, with an optional reason, about one item of a
+ * run's output, recorded under a judge class.
+ *
+ * - `POST /v1/judgments`: judge an item of a finished run.
+ * - `GET /v1/judgments`: live judgments, filtered by run, agent version,
+ *   flow, verdict, class, participant or project scope.
+ * - `GET /v1/judgments/:id`: one judgment with the stored copies.
+ * - `POST /v1/judgments/:id/unregister`: remove a judgment (soft).
+ *
+ * Authorization: judging needs `write` on the run's project (a run
+ * inherits its permissions from its project). Reading and removing go by
+ * the judgment's project (`read` / `write`), since a judgment outlives
+ * its run.
+ */
+export declare function judgmentsRouter(binding: JudgmentRegistryBinding, runBinding: RunBinding, authorizer?: Authorizer, conversations?: ConversationBinding, flows?: FlowRegistryBinding): Hono<AppEnv>;
+/**
+ * Judge classes: the deployment's named classes of judges ("expert",
+ * "user", …), each with a weight, scoped to the tenant, a project, or an
+ * agent in a project.
+ *
+ * Managing a tenant-scoped class needs `admin` on the tenant; a project-
+ * or agent-scoped class needs `admin` on its project. Listing returns the
+ * classes the caller may read.
+ */
+export declare function judgeClassesRouter(binding: JudgmentRegistryBinding, authorizer?: Authorizer): Hono<AppEnv>;
+/** RFC 6901: the value at `pointer` in `doc`. "" is the whole document. */
+export declare function resolvePointer(doc: unknown, pointer: string): {
+    readonly found: true;
+    readonly value: unknown;
+} | {
+    readonly found: false;
+};
+//# sourceMappingURL=judgments.d.ts.map

package/dist/routes/judgments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgments.d.ts","sourceRoot":"","sources":["../../src/routes/judgments.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,IAAI,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAQL,KAAK,uBAAuB,EAK7B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAM1C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,UAAU,EACtB,UAAU,CAAC,EAAE,UAAU,EACvB,aAAa,CAAC,EAAE,mBAAmB,EACnC,KAAK,CAAC,EAAE,mBAAmB,GAC1B,IAAI,CAAC,MAAM,CAAC,CA8Jd;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,uBAAuB,EAChC,UAAU,CAAC,EAAE,UAAU,GACtB,IAAI,CAAC,MAAM,CAAC,CAoJd;AAkTD,2EAA2E;AAC3E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,MAAM,GACd;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAe/E"}

package/dist/routes/judgments.js

@@ -0,0 +1,566 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { Hono } from 'hono';
+import { ref } from '@kindgi/authz';
+import { statusFor, toWireError } from '../errors.js';
+import { VERDICTS, judgeClassApplies, } from '../judgment-binding.js';
+import { captureTurnContext } from './judgment-context.js';
+import { captureFlowContext } from './judgment-flow-context.js';
+import { clampLimit } from './pagination.js';
+import { parseListScope } from './scope-params.js';
+/**
+ * Judgments: yes or no, with an optional reason, about one item of a
+ * run's output, recorded under a judge class.
+ *
+ * - `POST /v1/judgments`: judge an item of a finished run.
+ * - `GET /v1/judgments`: live judgments, filtered by run, agent version,
+ *   flow, verdict, class, participant or project scope.
+ * - `GET /v1/judgments/:id`: one judgment with the stored copies.
+ * - `POST /v1/judgments/:id/unregister`: remove a judgment (soft).
+ *
+ * Authorization: judging needs `write` on the run's project (a run
+ * inherits its permissions from its project). Reading and removing go by
+ * the judgment's project (`read` / `write`), since a judgment outlives
+ * its run.
+ */
+export function judgmentsRouter(binding, runBinding, authorizer, conversations, flows) {
+    const r = new Hono();
+    r.post('/', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const fail = (code, message) => {
+            c.status(statusFor(code));
+            return c.json(toWireError({ code, message }, requestId));
+        };
+        const parsed = parseJudgmentBody(await c.req.json().catch(() => null));
+        if (parsed.kind === 'err')
+            return fail('bad-input', parsed.message);
+        const body = parsed.body;
+        const asserted = assertedByOf(c.get('principal'));
+        if (asserted === undefined) {
+            return fail('permission-denied', 'Judging needs a user or a service token.');
+        }
+        const prepared = await prepareJudgment(c, body, runBinding, binding, authorizer);
+        if (prepared.kind === 'err')
+            return fail(prepared.code, prepared.message);
+        const { run, subject, projectId, itemValue, conversationId } = prepared;
+        const context = (await isFirstJudgment(binding, tenantId, body.runId))
+            ? await captureContext({
+                tenantId,
+                runId: body.runId,
+                subject,
+                output: run.output,
+                conversationId,
+                runBinding,
+                conversations,
+                flows,
+            })
+            : undefined;
+        const judgment = await binding.record({
+            tenantId,
+            projectId,
+            runId: body.runId,
+            run: {
+                subject,
+                input: run.input,
+                output: run.output,
+                ...(context !== undefined && { context }),
+            },
+            item: body.item,
+            ...(itemValue !== undefined && { itemValue }),
+            verdict: body.verdict,
+            ...(body.reason !== undefined && { reason: body.reason }),
+            ...(body.judgeClassId !== undefined && { judgeClassId: body.judgeClassId }),
+            assertedBy: asserted,
+            ...(body.participantId !== undefined && { participantId: body.participantId }),
+        });
+        c.status(201);
+        return c.json(serializeJudgment(judgment));
+    });
+    r.get('/', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const fail = (code, message) => {
+            c.status(statusFor(code));
+            return c.json(toWireError({ code, message }, requestId));
+        };
+        const q = (name) => {
+            const v = c.req.query(name);
+            return v !== undefined && v.length > 0 ? v : undefined;
+        };
+        const scope = parseListScope(c.req.query(), { tenantId });
+        if (scope.kind === 'err')
+            return fail('scope-invalid', scope.message);
+        const verdict = q('verdict');
+        if (verdict !== undefined && !isVerdict(verdict)) {
+            return fail('bad-input', `verdict must be one of: ${VERDICTS.join(', ')}.`);
+        }
+        if (q('agentVersion') !== undefined && q('agentId') === undefined) {
+            return fail('bad-input', 'agentVersion needs agentId.');
+        }
+        const page = await binding.list({
+            tenantId,
+            limit: clampLimit(c.req.query('limit')),
+            ...(scope.scope !== undefined && { scope: scope.scope }),
+            ...optional('runId', q('runId')),
+            ...optional('agentId', q('agentId')),
+            ...optional('agentVersion', q('agentVersion')),
+            ...optional('flowId', q('flowId')),
+            ...(verdict !== undefined && { verdict: verdict }),
+            ...optional('judgeClassId', q('judgeClassId')),
+            ...optional('participantId', q('participantId')),
+            ...(q('cursor') !== undefined && { cursor: q('cursor') }),
+        });
+        const visible = authorizer === undefined
+            ? page.data
+            : await authorizer.filterByCan(c, 'read', page.data, (j) => ref('project', j.projectId));
+        return c.json({
+            data: visible.map(serializeJudgment),
+            hasMore: page.hasMore,
+            ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor }),
+        });
+    });
+    r.get('/:judgmentId', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const judgmentId = c.req.param('judgmentId');
+        const judgment = await binding.get({ tenantId, judgmentId });
+        if (judgment === null ||
+            (authorizer !== undefined &&
+                !(await authorizer.can(c, 'read', ref('project', judgment.projectId))))) {
+            c.status(statusFor('judgment-not-found'));
+            return c.json(toWireError({ code: 'judgment-not-found', message: `No judgment "${judgmentId}".` }, requestId));
+        }
+        return c.json(serializeJudgmentWithCopies(judgment));
+    });
+    r.post('/:judgmentId/unregister', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const judgmentId = c.req.param('judgmentId');
+        const notFound = () => {
+            c.status(statusFor('judgment-not-found'));
+            return c.json(toWireError({ code: 'judgment-not-found', message: `No live judgment "${judgmentId}".` }, requestId));
+        };
+        const judgment = await binding.get({ tenantId, judgmentId });
+        if (judgment === null || judgment.unregisteredAt !== undefined)
+            return notFound();
+        if (authorizer !== undefined &&
+            !(await authorizer.can(c, 'write', ref('project', judgment.projectId)))) {
+            c.status(statusFor('permission-denied'));
+            return c.json(toWireError({ code: 'permission-denied', message: `Not allowed to remove judgment "${judgmentId}".` }, requestId));
+        }
+        const outcome = await binding.unregister({ tenantId, judgmentId });
+        if (!outcome.unregistered)
+            return notFound();
+        return c.json({ judgmentId, unregistered: true });
+    });
+    return r;
+}
+/**
+ * Judge classes: the deployment's named classes of judges ("expert",
+ * "user", …), each with a weight, scoped to the tenant, a project, or an
+ * agent in a project.
+ *
+ * Managing a tenant-scoped class needs `admin` on the tenant; a project-
+ * or agent-scoped class needs `admin` on its project. Listing returns the
+ * classes the caller may read.
+ */
+export function judgeClassesRouter(binding, authorizer) {
+    const r = new Hono();
+    const scopeRef = (tenantId, scope) => scope.kind === 'tenant' ? ref('tenant', tenantId) : ref('project', scope.projectId);
+    r.post('/', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const fail = (code, message) => {
+            c.status(statusFor(code));
+            return c.json(toWireError({ code, message }, requestId));
+        };
+        const parsed = parseClassBody(await c.req.json().catch(() => null));
+        if (parsed.kind === 'err')
+            return fail('bad-input', parsed.message);
+        const { scope, name, weight, description } = parsed.body;
+        if (authorizer !== undefined &&
+            !(await authorizer.can(c, 'admin', scopeRef(tenantId, scope)))) {
+            return fail('permission-denied', 'Not allowed to manage judge classes in this scope.');
+        }
+        const outcome = await binding.createClass({
+            tenantId,
+            scope,
+            name,
+            weight,
+            ...(description !== undefined && { description }),
+        });
+        if (outcome.kind === 'name-taken') {
+            return fail('judge-class-name-taken', `A judge class named "${name}" already exists here.`);
+        }
+        c.status(201);
+        return c.json(serializeJudgeClass(outcome.judgeClass));
+    });
+    r.get('/', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const scope = parseClassScopeQuery(c.req.query());
+        if (scope.kind === 'err') {
+            c.status(statusFor('bad-input'));
+            return c.json(toWireError({ code: 'bad-input', message: scope.message }, requestId));
+        }
+        const cursor = c.req.query('cursor');
+        const page = await binding.listClasses({
+            tenantId,
+            limit: clampLimit(c.req.query('limit')),
+            ...(scope.scope !== undefined && { scope: scope.scope }),
+            ...(cursor !== undefined && cursor.length > 0 && { cursor: cursor }),
+        });
+        const visible = authorizer === undefined
+            ? page.data
+            : await authorizer.filterByCan(c, 'read', page.data, (k) => scopeRef(tenantId, k.scope));
+        return c.json({
+            data: visible.map(serializeJudgeClass),
+            hasMore: page.hasMore,
+            ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor }),
+        });
+    });
+    const loadClass = async (c, action) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const judgeClassId = c.req.param('judgeClassId') ?? '';
+        const found = await binding.getClass({
+            tenantId,
+            judgeClassId,
+            includeUnregistered: action === 'read',
+        });
+        if (found !== null && authorizer !== undefined) {
+            const allowed = await authorizer.can(c, action, scopeRef(tenantId, found.scope));
+            if (!allowed &&
+                action === 'admin' &&
+                (await authorizer.can(c, 'read', scopeRef(tenantId, found.scope)))) {
+                c.status(statusFor('permission-denied'));
+                return c.json(toWireError({
+                    code: 'permission-denied',
+                    message: 'Not allowed to manage judge classes in this scope.',
+                }, requestId));
+            }
+            if (!allowed)
+                return classNotFound(c, judgeClassId);
+        }
+        return found ?? classNotFound(c, judgeClassId);
+    };
+    r.get('/:judgeClassId', async (c) => {
+        const found = await loadClass(c, 'read');
+        return found instanceof Response ? found : c.json(serializeJudgeClass(found));
+    });
+    r.patch('/:judgeClassId', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const raw = (await c.req.json().catch(() => null));
+        const weight = raw?.weight;
+        const description = raw?.description;
+        if (raw === null ||
+            typeof raw !== 'object' ||
+            (weight === undefined && description === undefined) ||
+            (weight !== undefined && !isWeight(weight)) ||
+            (description !== undefined && typeof description !== 'string')) {
+            c.status(statusFor('bad-input'));
+            return c.json(toWireError({
+                code: 'bad-input',
+                message: 'Send weight (a number ≥ 0) and/or description (a string).',
+            }, requestId));
+        }
+        const found = await loadClass(c, 'admin');
+        if (found instanceof Response)
+            return found;
+        if (found.unregisteredAt !== undefined)
+            return classNotFound(c, found.id);
+        const updated = await binding.updateClass({
+            tenantId,
+            judgeClassId: found.id,
+            ...(weight !== undefined && { weight: weight }),
+            ...(description !== undefined && { description: description }),
+        });
+        return updated === null ? classNotFound(c, found.id) : c.json(serializeJudgeClass(updated));
+    });
+    r.post('/:judgeClassId/unregister', async (c) => {
+        const tenantId = c.get('tenantId');
+        const found = await loadClass(c, 'admin');
+        if (found instanceof Response)
+            return found;
+        const outcome = await binding.unregisterClass({ tenantId, judgeClassId: found.id });
+        if (!outcome.unregistered)
+            return classNotFound(c, found.id);
+        return c.json({ judgeClassId: found.id, unregistered: true });
+    });
+    return r;
+}
+/**
+ * Everything a judgment needs from its run, or why it can't be recorded:
+ * the run exists, the caller may judge it, it has finished with an output,
+ * the class (if any) applies to it, and the pointer (if any) resolves.
+ */
+async function prepareJudgment(c, body, runBinding, binding, authorizer) {
+    const err = (code, message) => ({ kind: 'err', code, message });
+    const tenantId = c.get('tenantId');
+    const run = await runBinding.getRun(tenantId, body.runId);
+    if (run === null)
+        return err('run-not-found', `No run "${body.runId}".`);
+    // A run inherits its permissions from its project (as cancelling one
+    // does): judging it needs `write` there.
+    if (authorizer !== undefined &&
+        !(await authorizer.can(c, 'write', ref('project', run.projectId)))) {
+        return err('permission-denied', `Not allowed to judge run "${body.runId}".`);
+    }
+    if (run.status !== 'completed' || run.output === undefined || run.output === null) {
+        return err('run-not-finished', `Run "${body.runId}" has no output to judge yet (status ${run.status}).`);
+    }
+    const subject = subjectOf(run);
+    const projectId = run.projectId;
+    if (body.judgeClassId !== undefined &&
+        !(await classApplies(binding, tenantId, body.judgeClassId, { projectId, subject }))) {
+        return err('judge-class-not-applicable', `Judge class "${body.judgeClassId}" doesn't exist or doesn't apply to this run's project or agent.`);
+    }
+    const copy = { input: run.input, output: run.output };
+    const turn = run.agent !== undefined ? { conversationId: run.agent.conversationId } : {};
+    if (body.item.pointer === undefined)
+        return { kind: 'ok', run: copy, subject, projectId, ...turn };
+    const found = resolvePointer(run.output, body.item.pointer);
+    if (!found.found) {
+        return err('item-not-found', `Nothing at "${body.item.pointer}" in run "${body.runId}"'s output.`);
+    }
+    return { kind: 'ok', run: copy, subject, projectId, itemValue: found.value, ...turn };
+}
+/** Whether the run has no live judgment yet (its copy is stored with the first). */
+/**
+ * What a run's first judgment keeps so the run can be replayed later: a
+ * turn's history and retrieved context; a flow run's tool calls with
+ * their results.
+ */
+function captureContext(input) {
+    const { tenantId, runId, subject, runBinding } = input;
+    return subject.kind === 'agent'
+        ? captureTurnContext({
+            tenantId,
+            runId,
+            output: input.output,
+            conversationId: input.conversationId,
+            runBinding,
+            conversations: input.conversations,
+        })
+        : captureFlowContext({
+            tenantId,
+            run: { runId, flowId: subject.id, flowVersion: subject.version },
+            runBinding,
+            flows: input.flows,
+        });
+}
+async function isFirstJudgment(binding, tenantId, runId) {
+    const page = await binding.list({ tenantId, runId, limit: 1 });
+    return page.data.length === 0;
+}
+/** Whether a live class exists and its scope covers the run. */
+async function classApplies(binding, tenantId, judgeClassId, run) {
+    const judgeClass = await binding.getClass({ tenantId, judgeClassId });
+    return judgeClass !== null && judgeClassApplies(judgeClass.scope, run);
+}
+const MAX_REASON = 4000;
+function parseJudgmentBody(raw) {
+    const err = (message) => ({ kind: 'err', message });
+    if (raw === null || typeof raw !== 'object')
+        return err('Send a JSON object.');
+    const b = raw;
+    if (!nonEmpty(b.runId))
+        return err('runId is required.');
+    if (typeof b.verdict !== 'string' || !isVerdict(b.verdict)) {
+        return err(`verdict must be one of: ${VERDICTS.join(', ')}.`);
+    }
+    const item = parseItem(b.item);
+    if (typeof item === 'string')
+        return err(item);
+    const optional = optionalFieldError(b);
+    if (optional !== undefined)
+        return err(optional);
+    return {
+        kind: 'ok',
+        body: {
+            runId: b.runId,
+            item,
+            verdict: b.verdict,
+            ...(typeof b.judgeClassId === 'string' && { judgeClassId: b.judgeClassId }),
+            ...(typeof b.reason === 'string' && b.reason.length > 0 && { reason: b.reason }),
+            ...(typeof b.participantId === 'string' && { participantId: b.participantId }),
+        },
+    };
+}
+/** What's wrong with the optional fields (class, reason, participant), if anything. */
+function optionalFieldError(b) {
+    if (b.judgeClassId !== undefined && !nonEmpty(b.judgeClassId)) {
+        return 'judgeClassId must be a judge class id, or left out for an unclassified judgment.';
+    }
+    if (b.reason !== undefined && (typeof b.reason !== 'string' || b.reason.length > MAX_REASON)) {
+        return `reason must be a string of at most ${MAX_REASON} characters.`;
+    }
+    if (b.participantId !== undefined && !nonEmpty(b.participantId)) {
+        return 'participantId must be a non-empty string.';
+    }
+    return undefined;
+}
+function parseItem(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return 'item is required: { key, pointer?, rank? }.';
+    const i = raw;
+    if (!nonEmpty(i.key))
+        return 'item.key is required.';
+    if (i.pointer !== undefined && (typeof i.pointer !== 'string' || !isPointer(i.pointer))) {
+        return 'item.pointer must be a JSON Pointer such as "/matches/2" (or "" for the whole output).';
+    }
+    if (i.rank !== undefined && !(Number.isInteger(i.rank) && i.rank >= 0)) {
+        return 'item.rank must be a whole number ≥ 0.';
+    }
+    return {
+        key: i.key,
+        ...(typeof i.pointer === 'string' && { pointer: i.pointer }),
+        ...(typeof i.rank === 'number' && { rank: i.rank }),
+    };
+}
+function parseClassBody(raw) {
+    const err = (message) => ({ kind: 'err', message });
+    if (raw === null || typeof raw !== 'object')
+        return err('Send a JSON object.');
+    const b = raw;
+    if (!nonEmpty(b.name) || b.name.length > 100)
+        return err('name is required (at most 100 characters).');
+    if (!isWeight(b.weight))
+        return err('weight is required: a number ≥ 0.');
+    if (b.description !== undefined && typeof b.description !== 'string') {
+        return err('description must be a string.');
+    }
+    const scope = parseClassScope(b.scope);
+    if (typeof scope === 'string')
+        return err(scope);
+    return {
+        kind: 'ok',
+        body: {
+            scope,
+            name: b.name,
+            weight: b.weight,
+            ...(typeof b.description === 'string' && { description: b.description }),
+        },
+    };
+}
+function parseClassScope(raw) {
+    const usage = 'scope is required: { kind: "tenant" }, { kind: "project", projectId }, or { kind: "agent", projectId, agentId }.';
+    if (raw === null || typeof raw !== 'object')
+        return usage;
+    const s = raw;
+    if (s.kind === 'tenant')
+        return { kind: 'tenant' };
+    if (!nonEmpty(s.projectId))
+        return usage;
+    const projectId = s.projectId;
+    if (s.kind === 'project')
+        return { kind: 'project', projectId };
+    if (s.kind === 'agent' && nonEmpty(s.agentId))
+        return { kind: 'agent', projectId, agentId: s.agentId };
+    return usage;
+}
+/** `?scopeKind=tenant|project|agent&projectId=&agentId=` on the class list. */
+function parseClassScopeQuery(query) {
+    const kind = query.scopeKind;
+    if (kind === undefined || kind.length === 0)
+        return { kind: 'ok' };
+    const scope = parseClassScope({ kind, projectId: query.projectId, agentId: query.agentId });
+    return typeof scope === 'string' ? { kind: 'err', message: scope } : { kind: 'ok', scope };
+}
+// ---------- helpers ----------
+function nonEmpty(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function isVerdict(v) {
+    return VERDICTS.includes(v);
+}
+function isWeight(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+function optional(key, value) {
+    return (value === undefined ? {} : { [key]: value });
+}
+function classNotFound(c, id) {
+    c.status(statusFor('judge-class-not-found'));
+    return c.json(toWireError({ code: 'judge-class-not-found', message: `No judge class "${id}".` }, c.get('requestId')));
+}
+/** The caller as a judgment records it, from the request's principal. */
+function assertedByOf(principal) {
+    if (principal === undefined)
+        return undefined;
+    const actor = principal.actor;
+    return { kind: actor.kind === 'user' ? 'user' : 'service', id: actor.id };
+}
+/** What a run ran: its agent at a version (agent turns), else its flow. */
+function subjectOf(run) {
+    return run.agent !== undefined
+        ? { kind: 'agent', id: run.agent.id, version: run.agent.version }
+        : { kind: 'flow', id: run.flowId, version: run.flowVersion };
+}
+const POINTER_RE = /^(\/([^~/]|~[01])*)*$/;
+function isPointer(p) {
+    return POINTER_RE.test(p);
+}
+/** RFC 6901: the value at `pointer` in `doc`. "" is the whole document. */
+export function resolvePointer(doc, pointer) {
+    if (pointer === '')
+        return { found: true, value: doc };
+    let current = doc;
+    for (const raw of pointer.slice(1).split('/')) {
+        const token = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+        if (Array.isArray(current)) {
+            if (!/^(0|[1-9]\d*)$/.test(token) || Number(token) >= current.length)
+                return { found: false };
+            current = current[Number(token)];
+        }
+        else if (current !== null && typeof current === 'object' && Object.hasOwn(current, token)) {
+            current = current[token];
+        }
+        else {
+            return { found: false };
+        }
+    }
+    return { found: true, value: current };
+}
+// ---------- serialization ----------
+function serializeJudgment(j) {
+    return {
+        id: j.id,
+        tenantId: j.tenantId,
+        projectId: j.projectId,
+        runId: j.runId,
+        subject: j.subject,
+        item: j.item,
+        verdict: j.verdict,
+        ...(j.reason !== undefined && { reason: j.reason }),
+        ...(j.judgeClassId !== undefined && { judgeClassId: j.judgeClassId }),
+        assertedBy: j.assertedBy,
+        ...(j.participantId !== undefined && { participantId: j.participantId }),
+        createdAt: j.createdAt,
+        ...(j.unregisteredAt !== undefined && { unregisteredAt: j.unregisteredAt }),
+        ...(j.supersededBy !== undefined && { supersededBy: j.supersededBy }),
+    };
+}
+function serializeJudgmentWithCopies(j) {
+    return {
+        ...serializeJudgment(j),
+        run: j.run,
+        ...(j.itemValue !== undefined && { itemValue: j.itemValue }),
+    };
+}
+function serializeJudgeClass(k) {
+    return {
+        id: k.id,
+        tenantId: k.tenantId,
+        scope: k.scope,
+        name: k.name,
+        weight: k.weight,
+        ...(k.description !== undefined && { description: k.description }),
+        createdAt: k.createdAt,
+        updatedAt: k.updatedAt,
+        ...(k.unregisteredAt !== undefined && { unregisteredAt: k.unregisteredAt }),
+    };
+}
+//# sourceMappingURL=judgments.js.map