@vertesia/common 1.5.0 → 1.6.0-dev.20260918.061604Z

package/src/api-schemas/agent-runs.ts

@@ -2,11 +2,13 @@
 
 import { ExecutionTokenUsageSchema, ReasoningEffortSchema } from '@llumiverse/common/schemas';
 import { z } from 'zod';
+import { AGENT_RUN_FEEDBACK_COMMENT_MAX_LENGTH, AGENT_RUN_FEEDBACK_ID_MAX_LENGTH } from '../store/agent-run-values.js';
 import type { AgentMessageType, FileProcessingStatus } from '../store/workflow.js';
 import { type AgentEvent, AgentEventType, LlmCallType, TelemetryToolType } from '../workflow-analytics.js';
 import * as AppLifecycleSchemas from './app-lifecycle.js';
 import {
     AgentRunStatusSchema,
+    AgentToolApprovalClassSchema,
     ContentObjectTypeRefSchema,
     ConversationActivityStateSchema,
     EventRefSchema,
@@ -36,6 +38,252 @@ import { AgentCheckpointConfigurationSchema } from './project-configuration.js';
 import { nullableStringSchema } from './schema-primitives.js';
 import { InteractionExecutionConfigurationSchema } from './store.js';
 
+// ----------------------------------------------------------------------------
+// Evaluation vocabularies
+// ----------------------------------------------------------------------------
+
+export const TurnTerminalTypeSchema = z
+    .enum(['answer', 'user_stopped', 'completed', 'failed', 'cancelled', 'interrupted'])
+    .meta({ id: 'TurnTerminalType', description: 'How an agent turn ended.' });
+
+export const EvaluationSeveritySchema = z.enum(['none', 'low', 'medium', 'high']).meta({
+    id: 'EvaluationSeverity',
+    description: 'Worst deterministic detector level. `none` means no detector fired, not success.',
+});
+
+export const TurnEvaluationFlagSchema = z
+    .enum([
+        'user_stopped_after_failure',
+        'mutation_unsuccessful',
+        'run_failed',
+        'unrecovered_tool',
+        'fail_streak',
+        'identical_retry',
+        'reread',
+        'high_gather',
+        'overhead',
+        'followup_after_answer',
+        'approval_denied',
+        'circuit_breaker',
+    ])
+    .meta({ id: 'TurnEvaluationFlag', description: 'Reason behind an evaluation severity.' });
+
+export const ToolErrorClassSchema = z
+    .enum(['schema', 'platform', 'config', 'environment', 'other'])
+    .meta({ id: 'ToolErrorClass', description: 'Coarse class of a tool error, derived from the error text.' });
+
+const ToolErrorClassCountsSchema = z.strictObject({
+    schema: z.number().int().min(0),
+    platform: z.number().int().min(0),
+    config: z.number().int().min(0),
+    environment: z.number().int().min(0),
+    other: z.number().int().min(0),
+});
+
+const TelemetryDeploymentSchema = z.strictObject({
+    env: z.string(),
+    group: z.string(),
+    version: z.string(),
+    region: z.string().optional(),
+});
+
+const TelemetryProducerSchema = z.strictObject({
+    version: z.string(),
+});
+
+export const JudgeGateReasonSchema = z
+    .enum(['signal', 'sample'])
+    .meta({ id: 'JudgeGateReason', description: 'Why the judge looked at a run.' });
+
+export const JudgeOutcomeSchema = z
+    .enum(['judged', 'skipped_unarchived', 'failed'])
+    .meta({ id: 'JudgeOutcome', description: 'What a judge run produced.' });
+
+export const JudgeVerdictSchema = z
+    .enum(['success', 'partial', 'failure'])
+    .meta({ id: 'JudgeVerdict', description: "The judge's reading of a turn." });
+
+// ----------------------------------------------------------------------------
+// User feedback
+// ----------------------------------------------------------------------------
+
+/**
+ * How the user rated an agent run's work. Two values on purpose: a rating is a signal, not a score,
+ * and a wider scale invites a precision the reader does not have.
+ */
+export const AgentRunFeedbackRatingSchema = z
+    .enum(['up', 'down'])
+    .meta({ id: 'AgentRunFeedbackRating', description: 'Thumbs up or thumbs down on an agent run.' });
+
+/**
+ * The closed reason vocabulary. Closed rather than free text because the reason is the part that
+ * gets counted; the free-text `comment` stays with the tenant and is never aggregated.
+ */
+export const AgentRunFeedbackReasonCodeSchema = z
+    .enum([
+        'accurate',
+        'helpful',
+        'fast',
+        'well_explained',
+        'wrong_result',
+        'incomplete',
+        'misunderstood_request',
+        'too_slow',
+        'tool_failure',
+        'unsafe_action',
+        'other',
+    ])
+    .meta({ id: 'AgentRunFeedbackReasonCode', description: 'Why the run was rated the way it was.' });
+
+export const AgentRunFeedbackPayloadSchema = z
+    .strictObject({
+        feedback_id: z.string().min(1).max(AGENT_RUN_FEEDBACK_ID_MAX_LENGTH).meta({
+            description: 'Client-generated idempotency key (a UUID). A retried request with the same id is a no-op.',
+        }),
+        rating: AgentRunFeedbackRatingSchema,
+        reason_code: AgentRunFeedbackReasonCodeSchema.optional(),
+        comment: z.string().max(AGENT_RUN_FEEDBACK_COMMENT_MAX_LENGTH).optional().meta({
+            description: 'Free-text comment. Stored with the tenant; only its presence is ever counted.',
+        }),
+        message_id: z.string().optional().meta({
+            description: 'Rate one message rather than the run as a whole.',
+        }),
+        message_seq: z.number().int().min(0).optional().meta({
+            description: 'Position of the rated message in the run, when a message is rated.',
+        }),
+    })
+    .meta({ id: 'AgentRunFeedbackPayload', description: 'A user rating on an agent run.' });
+
+/**
+ * What happened to the rating. `recorded` and `replaced` both mean it counts; `replaced` says an
+ * earlier rating by the same user on the same scope was superseded. `disabled` means this
+ * deployment does not record feedback; it answers 200 because a rating is never the user's error.
+ */
+export const AgentRunFeedbackStatusSchema = z
+    .enum(['recorded', 'replaced', 'disabled'])
+    .meta({ id: 'AgentRunFeedbackStatus', description: 'Whether the rating was recorded.' });
+
+export const AgentRunFeedbackCountsSchema = z
+    .strictObject({
+        up: z.number().int().min(0),
+        down: z.number().int().min(0),
+        last_rating: AgentRunFeedbackRatingSchema.optional(),
+        last_reason_code: AgentRunFeedbackReasonCodeSchema.optional(),
+    })
+    .meta({
+        id: 'AgentRunFeedbackCounts',
+        description:
+            'Ratings over the retained feedback entries, one vote per rater: a user who rated the run and ' +
+            'one of its answers counts once, by their latest rating.',
+    });
+
+export const AgentRunFeedbackResponseSchema = z
+    .strictObject({
+        status: AgentRunFeedbackStatusSchema,
+        feedback_counts: AgentRunFeedbackCountsSchema.optional(),
+    })
+    .meta({ id: 'AgentRunFeedbackResponse', description: 'Result of rating an agent run.' });
+
+export const AgentRunFeedbackEntrySchema = z
+    .strictObject({
+        feedback_id: z.string(),
+        rating: AgentRunFeedbackRatingSchema,
+        reason_code: AgentRunFeedbackReasonCodeSchema.optional(),
+        comment: z.string().optional(),
+        message_id: z.string().optional(),
+        message_seq: z.number().int().optional(),
+        message_scoped: z.boolean(),
+        user_id: z.string(),
+        rated_at: z.string().meta({ format: 'date-time' }),
+        replaced_at: z.string().meta({ format: 'date-time' }).optional(),
+    })
+    .meta({ id: 'AgentRunFeedbackEntry', description: 'One recorded rating on an agent run.' });
+
+// ----------------------------------------------------------------------------
+// Evaluation summary
+// ----------------------------------------------------------------------------
+
+const AgentRunEvaluationTotalsSchema = z.strictObject({
+    tool_calls: z.number().int(),
+    error_tool_results: z.number().int(),
+    unrecovered_tools: z.array(z.string()),
+    llm_calls: z.number().int(),
+    prompt_tokens: z.number(),
+    completion_tokens: z.number(),
+    cached_tokens: z.number(),
+    retry_completion_tokens: z.number(),
+    active_ms: z.number(),
+    ask_user_wait_ms: z.number(),
+    approval_wait_ms: z.number(),
+    followups: z.number().int(),
+    approvals_requested: z.number().int(),
+    approvals_denied: z.number().int(),
+    stop_requests: z.number().int(),
+    /** Absent on rollups written before the stall counters existed; read as 0. */
+    stall_trips: z.number().int().optional(),
+});
+
+/**
+ * What the workflow reports about a run: the fold of its turn evaluations. Owned by the workflow;
+ * it never carries feedback or judge fields, which the server owns.
+ */
+export const AgentRunEvaluationRollupSchema = z
+    .strictObject({
+        seq: z.number().int().min(1).meta({
+            description: 'Monotonic per run; the server ignores a rollup older than the one it holds.',
+        }),
+        detector_version: z.number().int(),
+        turns: z.number().int(),
+        severity: EvaluationSeveritySchema,
+        flags: z.array(TurnEvaluationFlagSchema),
+        worst_turn_seq: z.number().int().optional(),
+        last_terminal_type: TurnTerminalTypeSchema.optional(),
+        terminal_error_class: z.string().optional(),
+        partial: z.boolean().optional(),
+        totals: AgentRunEvaluationTotalsSchema,
+        updated_at: z.string().meta({ format: 'date-time' }),
+    })
+    .meta({ id: 'AgentRunEvaluationRollup', description: 'Fold of the turn evaluations of a run.' });
+
+export const AgentRunJudgeResultSchema = z
+    .strictObject({
+        rev: z.number().int(),
+        gate: JudgeGateReasonSchema,
+        sample_rate: z.number(),
+        selected_probability: z.number(),
+        outcome: JudgeOutcomeSchema,
+        verdict: JudgeVerdictSchema.optional(),
+        score: z.number().optional(),
+        model: z.string().optional(),
+        prompt_version: z.string(),
+        turns_judged: z.array(z.number().int()).optional(),
+        judged_at: z.string().meta({ format: 'date-time' }),
+    })
+    .meta({ id: 'AgentRunJudgeResult', description: 'Latest judge result for a run.' });
+
+export const AgentRunContradictionReasonSchema = z
+    .enum(['feedback_down_on_clean_run', 'judge_failure_on_clean_run'])
+    .meta({ id: 'AgentRunContradictionReason' });
+
+/**
+ * The server-owned evaluation summary of a run: the workflow rollup, the feedback counts and the
+ * judge result, plus the derived severity, flags and contradiction the run list filters on.
+ */
+export const AgentRunEvaluationSchema = z
+    .strictObject({
+        rev: z.number().int().meta({ description: 'Bumped on every change to any part of the summary.' }),
+        rollup: AgentRunEvaluationRollupSchema.optional(),
+        feedback_counts: AgentRunFeedbackCountsSchema.optional(),
+        judge: AgentRunJudgeResultSchema.optional(),
+        severity: EvaluationSeveritySchema,
+        flags: z.array(TurnEvaluationFlagSchema),
+        contradicted: z.boolean(),
+        contradiction_reasons: z.array(AgentRunContradictionReasonSchema).optional(),
+        deployment_env: z.string().optional(),
+        updated_at: z.string().meta({ format: 'date-time' }),
+    })
+    .meta({ id: 'AgentRunEvaluation', description: 'Evaluation summary of an agent run.' });
+
 const agentEventBase = {
     timestamp: z.string(),
     runId: z.string(),
@@ -46,6 +294,9 @@ const agentEventBase = {
     interactionId: z.string(),
     parentRunId: z.string().optional(),
     ancestorRunIds: z.array(z.string()).optional(),
+    eventId: z.string().optional(),
+    deployment: TelemetryDeploymentSchema.optional(),
+    producer: TelemetryProducerSchema.optional(),
 };
 
 const AgentRunStartedEventSchema = z.strictObject({
@@ -123,6 +374,112 @@ const ToolCallEventSchema = z.strictObject({
     errorType: z.string().optional(),
     errorMessage: z.string().optional(),
     spawnedChildWorkflow: z.boolean().optional(),
+    approvalClass: AgentToolApprovalClassSchema.optional(),
+    errorClass: ToolErrorClassSchema.optional(),
+    signatureHash: z.string().optional(),
+    workstreamId: z.string().optional(),
+});
+
+const TurnToolObservationSchema = z.strictObject({
+    seq: z.number().int().min(1),
+    toolUseId: z.string(),
+    name: z.string(),
+    approvalClass: AgentToolApprovalClassSchema.optional(),
+    ok: z.boolean(),
+    errorClass: ToolErrorClassSchema.optional(),
+    sig: z.string(),
+    durationMs: z.number(),
+});
+
+const TurnEvaluationEventSchema = z.strictObject({
+    ...agentEventBase,
+    eventType: z.literal(AgentEventType.TurnEvaluation),
+    schemaVersion: z.number().int(),
+    detectorVersion: z.number().int(),
+    workstreamId: z.string(),
+    turnSeq: z.number().int().min(1),
+    terminalType: TurnTerminalTypeSchema,
+    partial: z.boolean().optional(),
+    startedAt: z.string(),
+    endedAt: z.string(),
+    durationMs: z.number(),
+    activeMs: z.number(),
+    askUserWaitMs: z.number(),
+    approvalWaitMs: z.number(),
+    timeToFirstAnswerMs: z.number().optional(),
+    toolCalls: z.number().int(),
+    errorToolResults: z.number().int(),
+    maxFailStreak: z.number().int(),
+    identicalRetryCount: z.number().int(),
+    unrecoveredTools: z.array(z.string()),
+    errorClasses: ToolErrorClassCountsSchema,
+    gatherCalls: z.number().int(),
+    gatherRatio: z.number().optional(),
+    mutationAttempted: z.boolean(),
+    mutationSucceeded: z.boolean(),
+    rereadCount: z.number().int(),
+    overheadCalls: z.number().int(),
+    skillsLoaded: z.number().int(),
+    interruptedToolCalls: z.number().int(),
+    llmCalls: z.number().int(),
+    promptTokens: z.number(),
+    completionTokens: z.number(),
+    cachedTokens: z.number(),
+    retryCompletionTokens: z.number(),
+    approvalsRequested: z.number().int(),
+    approvalsDenied: z.number().int(),
+    stopRequests: z.number().int(),
+    /** Absent on events from producers that predate the stall counters; read as 0. */
+    stallCorrectives: z.number().int().optional(),
+    stallTrips: z.number().int().optional(),
+    followupAfterAnswer: z.boolean(),
+    severity: EvaluationSeveritySchema,
+    flags: z.array(TurnEvaluationFlagSchema),
+    terminalErrorClass: z.string().optional(),
+    tools: z.array(TurnToolObservationSchema),
+    toolsTruncated: z.number().int(),
+});
+
+const FeedbackEventSchema = z.strictObject({
+    ...agentEventBase,
+    eventType: z.literal(AgentEventType.Feedback),
+    feedbackId: z.string(),
+    rating: AgentRunFeedbackRatingSchema,
+    reasonCode: AgentRunFeedbackReasonCodeSchema.optional(),
+    hasComment: z.boolean(),
+    messageScoped: z.boolean(),
+    messageSeq: z.number().int().optional(),
+    replaced: z.boolean(),
+});
+
+const TurnJudgementEventSchema = z.strictObject({
+    ...agentEventBase,
+    eventType: z.literal(AgentEventType.TurnJudgement),
+    evaluationRev: z.number().int(),
+    workstreamId: z.string(),
+    turnSeq: z.number().int().min(0),
+    gate: JudgeGateReasonSchema,
+    sampleRate: z.number(),
+    selectedProbability: z.number(),
+    outcome: JudgeOutcomeSchema,
+    verdict: JudgeVerdictSchema.optional(),
+    score: z.number().optional(),
+    reasons: z.array(z.string()).optional(),
+    promptVersion: z.string(),
+    detectorVersion: z.number().int().optional(),
+});
+
+const StallBreakerEventSchema = z.strictObject({
+    ...agentEventBase,
+    eventType: z.literal(AgentEventType.StallBreaker),
+    action: z.enum(['corrective', 'trip']),
+    toolNames: z.array(z.string()),
+    repeatCount: z.number().int(),
+    stallMeasure: z.number().int(),
+    allErrored: z.boolean(),
+    iteration: z.number().int(),
+    interactive: z.boolean(),
+    workstreamId: z.string(),
 });
 
 export const AgentEventSchema: z.ZodType<AgentEvent> = z
@@ -131,6 +488,10 @@ export const AgentEventSchema: z.ZodType<AgentEvent> = z
         AgentRunCompletedEventSchema,
         LlmCallEventSchema,
         ToolCallEventSchema,
+        TurnEvaluationEventSchema,
+        FeedbackEventSchema,
+        TurnJudgementEventSchema,
+        StallBreakerEventSchema,
     ])
     .meta({ id: 'AgentEvent' });
 
@@ -420,6 +781,11 @@ export const AutonomousRunResponseSchema = z
             .array(z.string())
             .meta({ description: 'Lessons learned from the conversation (extracted at completion)' })
             .optional(),
+        evaluation: AgentRunEvaluationSchema.meta({ description: 'Evaluation summary of the run.' }).optional(),
+        feedback: z
+            .array(AgentRunFeedbackEntrySchema)
+            .meta({ description: 'Retained user ratings on the run.' })
+            .optional(),
         archived_at: z
             .string()
             .meta({ description: 'When the last successful archive completed', format: 'date-time' })
@@ -568,6 +934,11 @@ export const AgentRunSchema = z
             .array(z.string())
             .meta({ description: 'Lessons learned from the conversation (extracted at completion)' })
             .optional(),
+        evaluation: AgentRunEvaluationSchema.meta({ description: 'Evaluation summary of the run.' }).optional(),
+        feedback: z
+            .array(AgentRunFeedbackEntrySchema)
+            .meta({ description: 'Retained user ratings on the run.' })
+            .optional(),
         archived_at: z
             .string()
             .meta({ description: 'When the last successful archive completed', format: 'date-time' })
@@ -988,6 +1359,14 @@ export const AgentRunArtifactQuerySchema = z
 
 export const AgentRunDetailsQuerySchema = z
     .object({
+        from: z
+            .string()
+            .max(12000)
+            .meta({
+                description:
+                    'Opaque history cursor from next_from; requires include_history. Invalid or expired cursors return a snapshot.',
+            })
+            .optional(),
         include_history: z.boolean().optional(),
         hydrate_payloads: z.boolean().optional(),
     })
@@ -999,6 +1378,10 @@ export const AgentRunArtifactsQuerySchema = z
     })
     .meta({ id: 'AgentRunArtifactsQuery' });
 
+export const ListAgentRunsEvaluationSeveritySchema = z
+    .enum(['unrated', 'none', 'low', 'medium', 'high'])
+    .meta({ id: 'ListAgentRunsEvaluationSeverity' });
+
 export const ListAgentRunsQuerySchema = z
     .object({
         id: z.string().meta({ description: 'Filter by agent run ID' }).optional(),
@@ -1022,6 +1405,21 @@ export const ListAgentRunsQuerySchema = z
         run_kind: RunKindSchema.meta({ description: 'Filter by internal run discriminator' }).optional(),
         sort: z.enum(['started_at', 'updated_at']).meta({ description: 'Field to sort by' }).optional(),
         order: z.enum(['asc', 'desc']).meta({ description: 'Sort order' }).optional(),
+        evaluation_severity: z
+            .array(ListAgentRunsEvaluationSeveritySchema)
+            .meta({ description: 'Filter by evaluation severity; `unrated` selects runs without an evaluation' })
+            .optional(),
+        evaluation_flag: z
+            .array(TurnEvaluationFlagSchema)
+            .meta({ description: 'Filter by evaluation flag (any of)' })
+            .optional(),
+        feedback_rating: AgentRunFeedbackRatingSchema.meta({
+            description: 'Filter by last feedback rating',
+        }).optional(),
+        contradicted: z
+            .boolean()
+            .meta({ description: 'Only runs whose feedback or judge contradicts the detectors' })
+            .optional(),
     })
     .meta({ id: 'ListAgentRunsQuery' });
 
@@ -1107,6 +1505,7 @@ export const UpdateAgentRunStatusPayloadSchema = z
         last_archive_error: z.string().optional(),
         sequence: z.number().optional(),
         process_state: ProcessStateSchema.optional(),
+        evaluation_rollup: AgentRunEvaluationRollupSchema.optional(),
     })
     .meta({ id: 'UpdateAgentRunStatusPayload' });
 

package/src/api-schemas/apikey.ts

@@ -207,3 +207,34 @@ export type ApiKeyReadResponseFromSchema = z.infer<typeof ApiKeyReadResponseSche
 export type CreateApiKeyPayloadFromSchema = z.infer<typeof CreateApiKeyPayloadSchema>;
 export type UpdateApiKeyPayloadFromSchema = z.infer<typeof UpdateApiKeyPayloadSchema>;
 export type AuthTokenResponseFromSchema = z.infer<typeof AuthTokenResponseSchema>;
+
+/** Project-independent organization credentials, managed only by interactive administrators. */
+export const AccountApiKeySchema = ApiKeySchema.pick({
+    id: true,
+    name: true,
+    account: true,
+    enabled: true,
+    maskedValue: true,
+    created_by: true,
+    updated_by: true,
+    created_at: true,
+    updated_at: true,
+    expires_at: true,
+})
+    .extend({
+        scope: z.literal('account'),
+        profile: z.literal('account_admin_v1'),
+        last_used_at: z.string().meta({ format: 'date-time' }).optional(),
+    })
+    .meta({ id: 'AccountApiKey' });
+export const AccountApiKeyWithValueSchema = AccountApiKeySchema.extend({ value: z.string() }).meta({
+    id: 'AccountApiKeyWithValue',
+});
+export const AccountApiKeyArraySchema = z.array(AccountApiKeySchema).meta({ id: 'AccountApiKeyArray' });
+export const CreateAccountApiKeyPayloadSchema = AccountApiKeySchema.pick({ name: true, expires_at: true })
+    .extend({ name: z.string().trim().min(1).regex(/\S/) })
+    .meta({ id: 'CreateAccountApiKeyPayload' });
+export const UpdateAccountApiKeyPayloadSchema = AccountApiKeySchema.pick({ name: true, enabled: true })
+    .extend({ name: z.string().trim().min(1).regex(/\S/) })
+    .partial()
+    .meta({ id: 'UpdateAccountApiKeyPayload' });

package/src/api-schemas/bundle-isolation.test.ts

@@ -1,37 +1,16 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { gzipSync } from 'node:zlib';
 import { describe, expect, it } from 'vitest';
 
 /**
- * Guards the packaging boundary that keeps schema-authoring runtime code out of ordinary
- * `@vertesia/common` and `@vertesia/client` consumers.
- *
- * `lib/index.js` is bundled wholesale into `lib/vertesia-common.js` by rolldown, and
- * `apps/composable-ui/build/shared-libs.ts` serves that single file to the browser mapped to the
- * bare specifier `@vertesia/common`. There is no per-consumer tree-shaking anywhere on that path,
- * so `import type` erasure in app code cannot save us: anything runtime-reachable from the root
- * barrel ships to every UI user.
- *
- * The rule this enforces: the root may re-export schema-derived TYPES (`export type`, erased by
- * tsc) but must never runtime-export `./api-schemas/*`. `@vertesia/client` is covered too — it is
- * shipped to the browser by the same mechanism, so a schema import there leaks just as badly. Its
- * default and Node.js entries are checked independently because this is also an SDK dependency
- * boundary for Node.js, serverless, CLI, and other JavaScript applications—not only a browser-size
- * concern.
- *
- * Runs against build output, so each artifact is skipped when it has not been built.
+ * Keep schema-authoring code out of the common browser bundle and public root entry.
+ * Build outputs are required; Turbo builds this package before running its tests.
+ * Client packaging is tested by the client package.
  */
 const path = (relative: string) => new URL(relative, import.meta.url).pathname;
 
 const COMMON_BUNDLE = path('../../lib/vertesia-common.js');
 const COMMON_ENTRY = path('../../lib/index.js');
-const CLIENT_BUNDLE = path('../../../client/lib/vertesia-client.js');
-/** `.` and `./node` in the client's exports map — the latter is `lib/nodejs/index.js`, not `lib/index.js`. */
-const CLIENT_ENTRIES = [
-    { label: 'client default entry (.)', file: path('../../../client/lib/index.js') },
-    { label: 'client node entry (./node)', file: path('../../../client/lib/nodejs/index.js') },
-];
-
 /** Markers that prove a runtime schema import leaked into a browser artifact. */
 const FORBIDDEN = ['zod', '_zod', 'ZodObject', 'api-schemas', 'toOpenApiComponents', 'ApiSchemaComponents'];
 
@@ -45,7 +24,7 @@ function expectNoSchemaRuntime(file: string, label: string): void {
     }
 }
 
-describe.skipIf(!existsSync(COMMON_BUNDLE))('@vertesia/common runtime schema isolation', () => {
+describe('@vertesia/common runtime schema isolation', () => {
     it('does not runtime-reference the api-schemas subpath from the root entry', () => {
         expect(readFileSync(COMMON_ENTRY, 'utf8')).not.toContain('api-schemas');
     });
@@ -63,18 +42,3 @@ describe.skipIf(!existsSync(COMMON_BUNDLE))('@vertesia/common runtime schema iso
         ).toBeLessThan(MAX_COMMON_GZIP_BYTES);
     });
 });
-
-describe.skipIf(!existsSync(CLIENT_BUNDLE))('@vertesia/client consumer runtime isolation', () => {
-    it('contains no zod import or schema registry code', () => {
-        // The client is served to the browser the same way common is, so importing
-        // `@vertesia/common/api-schemas` from an SDK method would ship zod to every UI user.
-        expectNoSchemaRuntime(CLIENT_BUNDLE, 'client browser bundle');
-    });
-
-    it.each(CLIENT_ENTRIES)('does not reference the api-schemas subpath from the $label', ({ label, file }) => {
-        // Asserted rather than skipped: a missing artifact means the entry moved or stopped being
-        // built, and silently passing would let a packaging regression through unnoticed.
-        expect(existsSync(file), `${label} not found at ${file} — has the exports map changed?`).toBe(true);
-        expect(readFileSync(file, 'utf8'), `${label} must not import api-schemas`).not.toContain('api-schemas');
-    });
-});

package/src/api-schemas/delegation.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+const id = z.string().regex(/^[a-f0-9]{24}$/i);
+export const CreateDelegationGrantPayloadSchema = z
+    .strictObject({
+        schedule_id: id,
+        subject: id,
+        output_collection_id: id,
+        policy_hash: z.string().regex(/^[a-f0-9]{64}$/),
+        expires_at: z.string().datetime().nullable(),
+    })
+    .meta({ id: 'CreateDelegationGrantPayload' });
+export const DelegationGrantSchema = CreateDelegationGrantPayloadSchema.extend({
+    id,
+    account_id: id,
+    project_id: id,
+    granter: id,
+    created_at: z.string().datetime(),
+    revoked_at: z.string().datetime().nullable(),
+}).meta({ id: 'DelegationGrant' });
+export const DelegationGrantArraySchema = z.array(DelegationGrantSchema).meta({ id: 'DelegationGrantArray' });

package/src/api-schemas/emit-json-schema.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { toOpenApiComponents } from './adapter.js';
+import { emitJsonSchema } from './emit-json-schema.js';
+
+describe('explicit union emission', () => {
+    it('preserves optional explicit unions and nullable schemas', () => {
+        const schema = z.object({
+            explicit: z.union([z.string(), z.null()]).optional().describe('Clear with null'),
+            nullable: z.string().nullable(),
+        });
+        const emitted = emitJsonSchema(schema);
+        expect(emitted.properties).toEqual({
+            explicit: { anyOf: [{ type: 'string' }, { type: 'null' }], description: 'Clear with null' },
+            nullable: { anyOf: [{ type: 'string' }, { type: 'null' }] },
+        });
+        expect(JSON.stringify(emitted)).not.toContain('x-vertesia-explicit-union');
+    });
+
+    it('preserves referenced explicit unions inside named definitions', () => {
+        const value = z.union([z.string(), z.boolean(), z.number(), z.null()]).meta({ id: 'Value' });
+        const schema = z.object({ value }).meta({ id: 'Holder' });
+        const components = toOpenApiComponents({ Holder: emitJsonSchema(schema) });
+        expect(components.Value).toEqual({
+            anyOf: [{ type: 'string' }, { type: 'boolean' }, { type: 'number' }, { type: 'null' }],
+        });
+        expect(JSON.stringify(components)).not.toContain('x-vertesia-explicit-union');
+    });
+
+    it('retains constraints on union branches', () => {
+        expect(emitJsonSchema(z.union([z.string().min(2), z.null()])).anyOf).toEqual([
+            { type: 'string', minLength: 2 },
+            { type: 'null' },
+        ]);
+    });
+});

package/src/api-schemas/emit-json-schema.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { isPlainObject, type JsonObject } from './adapter.js';
+
+const EXPLICIT_UNION = 'x-vertesia-explicit-union';
+
+/** Preserve the published explicit-union spelling across Zod's final compaction pass. */
+export function emitJsonSchema(schema: z.ZodType): JsonObject {
+    const emitted = z.toJSONSchema(schema, {
+        target: 'draft-2020-12',
+        io: 'input',
+        override: ({ jsonSchema }) => {
+            // Zod 4.5 compacts bare anyOf branches AFTER override runs. Carry the original
+            // branches through that pass; optional wrappers inherit this metadata as well.
+            const branches = jsonSchema.anyOf;
+            if (
+                branches?.every(
+                    (branch) => isPlainObject(branch) && Object.keys(branch).length === 1 && 'type' in branch,
+                )
+            ) {
+                jsonSchema[EXPLICIT_UNION] = branches;
+            }
+        },
+    });
+    restoreExplicitUnions(emitted);
+    return emitted;
+}
+
+function restoreExplicitUnions(value: unknown): void {
+    if (Array.isArray(value)) {
+        for (const child of value) restoreExplicitUnions(child);
+    } else if (isPlainObject(value)) {
+        const branches = value[EXPLICIT_UNION];
+        if (Array.isArray(branches)) {
+            delete value[EXPLICIT_UNION];
+            delete value.type;
+            value.anyOf = branches;
+        }
+        for (const child of Object.values(value)) restoreExplicitUnions(child);
+    }
+}