@vertesia/common 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260804.124748Z

package/src/api-schemas/document-processing.ts

@@ -0,0 +1,344 @@
+import { z } from 'zod';
+import { MarkdownRenditionFormat } from '../store/store.js';
+import { WorkflowExecutionStatusValues } from '../store/workflow.js';
+import { InteractionExecutionConfigurationSchema } from './store.js';
+
+/** Zod's `.nullable()` emits `anyOf`; this annotation preserves the published type-array form. */
+const nullableStringSchema: z.ZodType<string | null> = z.any().meta({ type: ['string', 'null'] });
+
+export const WorkflowExecutionStatusSchema = z
+    .enum(WorkflowExecutionStatusValues)
+    .meta({ id: 'WorkflowExecutionStatus' });
+
+export const GroundedAssistantResponseSchema = z
+    .strictObject({
+        agent_run_id: z.string().meta({ description: 'The AgentRun id to stream/render the conversation.' }),
+        workflow_id: z.string().meta({ description: 'The conversation workflow id backing the run.' }),
+        object_id: z.string().meta({ description: 'The object the assistant is scoped to.' }),
+    })
+    .meta({
+        id: 'GroundedAssistantResponse',
+        description:
+            'Response from starting the interactive grounded extraction assistant. The agent run + conversation workflow are launched server-side (recordRun -> stage the document into the agent space -> launch the interactive conversation); the client renders the conversation with `agent_run_id`.',
+    });
+
+export const GroundedExtractionRequestSchema = z
+    .strictObject({
+        schema: z
+            .looseObject({})
+            .meta({ description: 'JSON schema describing the data to extract. Takes precedence over type_ref.' })
+            .optional(),
+        type_ref: z
+            .string()
+            .meta({ description: 'Content type id or catalog ref whose object_schema drives the extraction.' })
+            .optional(),
+        interaction_name: z
+            .string()
+            .meta({ description: 'Interaction to use. Defaults to sys:ExtractInformationGrounded.' })
+            .optional(),
+        max_pages: z.number().meta({ description: 'Maximum number of pages to process.' }).optional(),
+        force_ocr: z.boolean().meta({ description: 'Run OCR on every page even when a text layer exists.' }).optional(),
+        refresh_ocr: z
+            .boolean()
+            .meta({ description: 'Re-run OCR on pages that need it instead of restoring the stored OCR result.' })
+            .optional(),
+        use_vision: z
+            .boolean()
+            .meta({
+                description:
+                    'Attach clean page images for layout/semantic context; direct-vision pages also receive checkerboards.',
+            })
+            .optional(),
+        grid_cell_pt: z
+            .number()
+            .meta({
+                description:
+                    'A1 locate-grid cell size in PDF points for vision pages (drives both the drawn grid and cell→box resolution). Smaller = finer grid / more cells. Default: 14.',
+            })
+            .optional(),
+        raster_mode: z
+            .enum(['vision', 'ocr'])
+            .meta({
+                description:
+                    "How to read pages that have no digital text layer (scans / image-only pages). 'vision' (default): read them off the page image with the extraction model, skipping OCR entirely. 'ocr': legacy path — OCR those pages and block-ground on the (lossy) OCR text. Set to 'ocr' to revert to the pre-vision behavior.",
+            })
+            .optional(),
+        window_pages: z
+            .number()
+            .meta({
+                description: 'Maximum pages per extraction call; larger documents are split into sequential windows.',
+            })
+            .optional(),
+        agentic_extraction: z
+            .boolean()
+            .meta({
+                description:
+                    'Extract with an autonomous agent (views the whole document at once) instead of the deterministic windowed pipeline. Sidesteps window-boundary splits on long documents. The workflow stages the artifacts into an agent space, runs a conversation agent that writes the extraction, then folds it back.',
+            })
+            .optional(),
+        extract_agent: z
+            .string()
+            .meta({ description: 'Agent interaction for agentic_extraction. Defaults to sys:GeneralAgent.' })
+            .optional(),
+        update_properties: z
+            .boolean()
+            .meta({ description: "Update the object's properties with the extracted data. Default: true." })
+            .optional(),
+        config: InteractionExecutionConfigurationSchema.meta({
+            description: 'LLM execution configuration (model, environment, ...) for the main pass.',
+        }).optional(),
+        hard_config: InteractionExecutionConfigurationSchema.meta({
+            description: 'Execution configuration used instead of `config` on hard content (scans, handwriting).',
+        }).optional(),
+        hardness_threshold: z
+            .number()
+            .meta({ description: 'Hardness score (0..1) at or above which `hard_config` is used. Default: 0.5.' })
+            .optional(),
+        review_config: InteractionExecutionConfigurationSchema.meta({
+            description: 'Execution configuration for the post-extraction review pass. No review runs when absent.',
+        }).optional(),
+        review_threshold: z
+            .number()
+            .meta({
+                description: 'Hardness score (0..1) at or above which the review runs. Defaults to hardness_threshold.',
+            })
+            .optional(),
+        coverage_review_threshold: z
+            .number()
+            .meta({
+                description: "Review triggers when any page's citation coverage falls below this floor. Default: 0.2.",
+            })
+            .optional(),
+        force_review: z
+            .boolean()
+            .meta({
+                description:
+                    'Run the model review even when every citation was digitally verified. Requires review_config.',
+            })
+            .optional(),
+        operator_instructions: z
+            .string()
+            .meta({
+                description:
+                    'Free-text operator guidance folded into the extraction prompt to steer a (re-)extraction, e.g. "part numbers are in the third column; some line items wrap onto the next row".',
+            })
+            .optional(),
+        user_prompt: z
+            .string()
+            .meta({
+                description:
+                    "Interactive assistant only: the operator's opening message for the assistant conversation.",
+            })
+            .optional(),
+    })
+    .meta({
+        id: 'GroundedExtractionRequest',
+        description:
+            "Request body to start a grounded extraction on a content object. All fields are optional: with none set, the object's own content-type schema drives the extraction with default models and settings.",
+    });
+
+export const GroundedVerificationBreakdownSchema = z
+    .strictObject({
+        total: z.number().meta({ description: 'Total number of cited values.' }),
+        digitally_verified: z
+            .number()
+            .meta({ description: "Values matched verbatim against the document's text (digital layer or OCR)." }),
+        ai_verified: z.number().meta({ description: 'Values the reviewer model confirmed against the page image.' }),
+        unverified: z
+            .number()
+            .meta({ description: 'Values read from the image but neither text-matched nor reviewer-confirmed.' }),
+    })
+    .meta({
+        id: 'GroundedVerificationBreakdown',
+        description:
+            "How each extracted value was verified. Two kinds, both trustworthy: digitally verified (matched the document's text — digital layer or OCR) and AI verified (the reviewer confirmed it against the page image — the primary signal for scanned or handwritten content, which has no text layer to match).",
+    });
+
+export const GroundedExtractionVerdictSchema = z.enum(['good_to_go', 'needs_review']).meta({
+    id: 'GroundedExtractionVerdict',
+    description:
+        'Document-level trust verdict for a grounded extraction. `good_to_go` means the extracted content (after any review corrections) can be used without a human check; `needs_review` means a human should verify it. This reflects content correctness, not how many citation boxes rendered.',
+});
+
+export const DocProcessorOutputFormatSchema = z
+    .literal('markdown')
+    .meta({ id: 'DocProcessorOutputFormat', description: 'Output format for document processing workflows' });
+
+export const DocAnalyzerProgressStatusSchema = z
+    .strictObject({
+        total: z.number(),
+        processed: z.number(),
+        success: z.number(),
+        failed: z.number(),
+    })
+    .meta({ id: 'DocAnalyzerProgressStatus' });
+
+export const DocumentProcessingPhaseSchema = z
+    .enum(['markdown', 'grounded_extraction'])
+    .meta({ id: 'DocumentProcessingPhase' });
+
+export const DocumentPrepOptionsSchema = z
+    .object({
+        features: z.array(z.string()).optional(),
+        debug: z.boolean().optional(),
+        output_format: DocProcessorOutputFormatSchema.optional(),
+    })
+    .catchall(z.unknown())
+    .meta({ id: 'DocumentPrepOptions' });
+
+export const GroundedExtractionResultResponseSchema = z
+    .strictObject({
+        object_id: z.string(),
+        data: z.looseObject({}).meta({ description: 'The extracted data, shaped by the requested schema.' }),
+        verdict: GroundedExtractionVerdictSchema.meta({ description: 'Document-level trust verdict.' }).optional(),
+        verdict_reason: z.string().meta({ description: 'One-sentence rationale for the verdict.' }).optional(),
+        confidence: z.number().meta({ description: 'Mean citation confidence in [0,1].' }).optional(),
+        verification: GroundedVerificationBreakdownSchema.meta({ description: 'Per-value verification breakdown.' }),
+        review: z
+            .strictObject({
+                assessment: z.enum(['complete', 'issues_found']),
+                summary: z.string().optional(),
+                corrections_applied: z.number().optional(),
+            })
+            .meta({ description: 'Review outcome, when a review pass ran.' })
+            .optional(),
+        result_url: nullableStringSchema
+            .meta({
+                description: 'Signed download URL for the full grounded-extraction.json (data + citations + boxes).',
+            })
+            .optional(),
+    })
+    .meta({
+        id: 'GroundedExtractionResultResponse',
+        description:
+            'Completed grounded extraction result: the extracted data with its trust verdict and verification breakdown, plus a download URL for the full citations artifact.',
+    });
+
+export const DocAnalyzerProgressSchema = z
+    .strictObject({
+        phase: DocumentProcessingPhaseSchema.optional(),
+        pages: DocAnalyzerProgressStatusSchema,
+        images: DocAnalyzerProgressStatusSchema,
+        tables: DocAnalyzerProgressStatusSchema,
+        visuals: DocAnalyzerProgressStatusSchema,
+        started_at: z.number().optional(),
+        percent: z.number(),
+        output_format: DocProcessorOutputFormatSchema.meta({
+            description: 'The output format being used for processing.',
+        }).optional(),
+    })
+    .meta({ id: 'DocAnalyzerProgress' });
+
+export const DocAnalyzeRunStatusResponseSchema = z
+    .strictObject({
+        workflow_id: nullableStringSchema,
+        workflow_run_id: nullableStringSchema,
+        status: WorkflowExecutionStatusSchema,
+        phase: DocumentProcessingPhaseSchema.optional(),
+        progress: DocAnalyzerProgressSchema.optional(),
+        output_format: DocProcessorOutputFormatSchema.meta({
+            description: 'The output format being used for processing.',
+        }).optional(),
+    })
+    .meta({ id: 'DocAnalyzeRunStatusResponse', description: 'Represents a document analysis run status' });
+
+export const MarkdownRenditionFormatSchema = z.enum(MarkdownRenditionFormat).meta({ id: 'MarkdownRenditionFormat' });
+
+export const PdfRenderingMetadataSchema = z
+    .strictObject({
+        document_id: z.string().meta({ description: 'Document ID to display in footer' }).optional(),
+        agent_name: z.string().meta({ description: 'Agent name that generated the document' }).optional(),
+        agent_run_id: z.string().meta({ description: 'Agent run ID to display in footer' }).optional(),
+        subtitle: z.string().meta({ description: 'Document subtitle' }).optional(),
+        author: z.array(z.string()).meta({ description: 'Document author(s)' }).optional(),
+        date: z
+            .string()
+            .meta({ description: 'Document date (displayed in header and title page; defaults to today if omitted)' })
+            .optional(),
+    })
+    .meta({ id: 'PdfRenderingMetadata', description: 'Metadata for PDF rendering (displayed in header/footer)' });
+
+export const RenderMarkdownPayloadSchema = z
+    .strictObject({
+        format: MarkdownRenditionFormatSchema.meta({ description: 'Output format' }),
+        object_id: z.string().meta({ description: 'Object ID to render (mutually exclusive with content)' }).optional(),
+        content: z
+            .string()
+            .meta({ description: 'Inline markdown content to render (mutually exclusive with object_id)' })
+            .optional(),
+        title: z
+            .string()
+            .meta({ description: 'Document title (used for filename when using inline content)' })
+            .optional(),
+        template_url: z
+            .string()
+            .meta({ description: 'URL to a template file for pandoc (DOCX reference doc or LaTeX template)' })
+            .optional(),
+        template_logo_url: z
+            .string()
+            .meta({ description: 'Optional logo URL for template variable `logo-path` (studio-hosted URL)' })
+            .optional(),
+        template_path: z
+            .string()
+            .meta({ description: 'Template file via artifact:/store: protocol (takes precedence over template_url)' })
+            .optional(),
+        logo_path: z
+            .string()
+            .meta({ description: 'Logo file via artifact:/store: protocol (takes precedence over template_logo_url)' })
+            .optional(),
+        use_default_template: z
+            .boolean()
+            .meta({ description: 'Use Vertesia default template if no template_url provided (default: true for pdf)' })
+            .optional(),
+        pandoc_options: z.array(z.string()).meta({ description: 'Additional pandoc command-line options' }).optional(),
+        artifact_run_id: z.string().meta({ description: 'Run ID for resolving artifact: and image: URLs' }).optional(),
+        metadata: PdfRenderingMetadataSchema.meta({
+            description: 'Document metadata for PDF footer/header',
+        }).optional(),
+        template_data_source: z
+            .string()
+            .meta({
+                description:
+                    'Source reference for auto-wired template data: `store:<objectId>` or `artifact:<path-to-json>`',
+            })
+            .optional(),
+        output_path: z.string().meta({ description: 'Custom upload path for the rendered output' }).optional(),
+    })
+    .meta({
+        id: 'RenderMarkdownPayload',
+        description: 'Payload for rendering markdown to PDF or DOCX. Either object_id OR content must be provided.',
+    });
+
+export const RenderMarkdownStartResponseSchema = z
+    .strictObject({
+        workflow_id: nullableStringSchema,
+        workflow_run_id: nullableStringSchema,
+        status: WorkflowExecutionStatusSchema,
+        format: MarkdownRenditionFormatSchema.meta({ description: 'Requested output format' }),
+    })
+    .meta({
+        id: 'RenderMarkdownStartResponse',
+        description:
+            'Initial response when starting a markdown rendering workflow. Clients should poll status using workflow_id/workflow_run_id.',
+    });
+
+export const RenderMarkdownStatusResponseSchema = z
+    .strictObject({
+        workflow_id: nullableStringSchema,
+        workflow_run_id: nullableStringSchema,
+        status: WorkflowExecutionStatusSchema,
+        format: MarkdownRenditionFormatSchema.meta({ description: 'Requested output format (if known)' }).optional(),
+        download_url: z.string().meta({ description: 'Download URL for completed output' }).optional(),
+        file_uri: z.string().meta({ description: 'File URI in storage for completed output' }).optional(),
+        error: z.string().meta({ description: 'Error details for failed/terminated runs' }).optional(),
+    })
+    .meta({
+        id: 'RenderMarkdownStatusResponse',
+        description: 'Polled status response for markdown rendering workflow.',
+    });
+
+/** Query components validate declared fields without rejecting unrelated query parameters. */
+export const RenderMarkdownStatusQuerySchema = z.looseObject({
+    workflow_id: z.string(),
+    workflow_run_id: z.string(),
+});

package/src/api-schemas/embeddings.ts

@@ -0,0 +1,113 @@
+import { EmbeddingTaskTypeSchema } from '@llumiverse/common/schemas';
+import { z } from 'zod';
+
+/**
+ * The request half of `POST /environments/:envId/embeddings`.
+ *
+ * The result half is llumiverse's — vectors and counts are already JSON, so `EmbeddingsResult` is
+ * the same object on both sides. The request is not: a driver consumes a `DataSource`, which is a
+ * stream, so the wire format carries a URL or base64 text instead and the server wraps it before
+ * handing the request on.
+ */
+
+export const EmbeddingsApiSourceSchema = z
+    .strictObject({
+        name: z.string().meta({ description: 'Display name for the source (defaults to "embedding-input").' }),
+        mime_type: z.string().meta({ description: 'MIME type of the binary content. Required for most providers.' }),
+        url: z.string().meta({
+            description:
+                'Provider-native URL the driver may pass through directly:\n' +
+                '- gs:// or https://storage.googleapis.com/ for Vertex AI\n' +
+                '- s3:// or https://*.amazonaws.com for Bedrock\n' +
+                '- https:// for fetch fallback Mutually exclusive with base64.',
+        }),
+        base64: z.string().meta({ description: 'Base64-encoded bytes. Mutually exclusive with url.' }),
+    })
+    .partial()
+    .meta({ id: 'EmbeddingsApiSource' });
+
+export const EmbeddingsApiTextInputSchema = z
+    .strictObject({
+        type: z.literal('text'),
+        text: z.string(),
+        task_type: EmbeddingTaskTypeSchema.optional(),
+        title: z.string().optional(),
+    })
+    .meta({ id: 'EmbeddingsApiTextInput' });
+
+export const EmbeddingsApiImageInputSchema = z
+    .strictObject({
+        type: z.literal('image'),
+        source: EmbeddingsApiSourceSchema,
+    })
+    .meta({ id: 'EmbeddingsApiImageInput' });
+
+export const EmbeddingsApiVideoInputSchema = z
+    .strictObject({
+        type: z.literal('video'),
+        source: EmbeddingsApiSourceSchema,
+        start_sec: z.number().optional(),
+        length_sec: z.number().optional(),
+        interval_sec: z.number().optional(),
+        use_fixed_length_sec: z.boolean().optional(),
+        min_clip_sec: z.number().optional(),
+        embedding_option: z.array(z.enum(['visual-text', 'visual-image', 'audio'])).optional(),
+    })
+    .meta({ id: 'EmbeddingsApiVideoInput' });
+
+export const EmbeddingsApiAudioInputSchema = z
+    .strictObject({
+        type: z.literal('audio'),
+        source: EmbeddingsApiSourceSchema,
+        start_sec: z.number().optional(),
+        length_sec: z.number().optional(),
+    })
+    .meta({ id: 'EmbeddingsApiAudioInput' });
+
+export const EmbeddingsApiInputSchema = z
+    .discriminatedUnion('type', [
+        EmbeddingsApiTextInputSchema,
+        EmbeddingsApiImageInputSchema,
+        EmbeddingsApiVideoInputSchema,
+        EmbeddingsApiAudioInputSchema,
+    ])
+    .meta({
+        id: 'EmbeddingsApiInput',
+        description:
+            'Wire-format inputs accepted by the studio-server embeddings endpoint. Mirror of ' +
+            "@llumiverse/common's EmbeddingInput, but binary modalities carry a JSON-friendly source " +
+            '(URL or base64) instead of a DataSource. The server wraps each source in a ' +
+            'Base64DataSource or URLDataSource before passing the request to the llumiverse driver.',
+    });
+
+export const EmbeddingsApiRequestSchema = z
+    .strictObject({
+        inputs: z.array(EmbeddingsApiInputSchema),
+        model: z.string().optional(),
+        task_type: EmbeddingTaskTypeSchema.optional(),
+        dimensions: z.number().optional(),
+    })
+    .meta({ id: 'EmbeddingsApiRequest' });
+
+export const EmbeddingsStatusResponseSchema = z
+    .strictObject({
+        status: z.string(),
+        embeddingRunsInProgress: z.number().optional(),
+        totalIndexableObjects: z.number().optional(),
+        embeddingsModels: z.array(z.string()).optional(),
+        objectsWithEmbeddings: z.number().optional(),
+        vectorIndex: z.strictObject({
+            status: z.enum(['READY', 'PENDING', 'DELETING', 'ABSENT']),
+            name: z.string().optional(),
+            type: z.string().optional(),
+        }),
+    })
+    .meta({ id: 'EmbeddingsStatusResponse' });
+
+export const ProjectConfigurationEmbeddingEnablePayloadSchema = z
+    .strictObject({
+        environment: z.string(),
+        max_tokens: z.number().optional(),
+        model: z.string().optional(),
+    })
+    .meta({ id: 'ProjectConfigurationEmbeddingEnablePayload' });

package/src/api-schemas/environment.contract.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from 'vitest';
+import { SupportedProviders } from '../environment.js';
+import { ApiSchemaComponents, validateApiRequest, validateApiResponse } from './registry.js';
+
+/**
+ * The environment contracts, pinned where converting them changed what the document says or where
+ * the conversion had a choice to make.
+ *
+ * Thirty-six components, of which thirty-two re-emit byte-identically; what is asserted here is the
+ * four that do not, the two provider vocabularies that have to stay in step, and the secret boundary
+ * that is the reason the read and write shapes are separate objects.
+ */
+
+describe('the provider vocabulary', () => {
+    /**
+     * `SupportedProviders` is llumiverse's `Providers` merged with the three studio-only virtual
+     * providers, and the schema reads its members off that merged object rather than restating them.
+     * This is the assertion that it still does: a provider added on either side has to reach the
+     * document without anyone editing a list, which is the whole reason `z.enum()` takes the object.
+     */
+    it('publishes every member of the merged provider object, in its order', () => {
+        expect(enumOf('SupportedProviders')).toEqual(Object.values(SupportedProviders));
+    });
+
+    it('includes the studio-only virtual providers, which llumiverse does not know about', () => {
+        expect(enumOf('SupportedProviders')).toEqual(
+            expect.arrayContaining(['virtual_lb', 'virtual_mediator', 'test']),
+        );
+    });
+
+    it('rejects a provider that is neither', () => {
+        expect(validateApiRequest('ExecutionEnvironmentCreatePayload', { name: 'e', provider: 'openai' }).valid).toBe(
+            true,
+        );
+        expect(validateApiRequest('ExecutionEnvironmentCreatePayload', { name: 'e', provider: 'gpt' }).valid).toBe(
+            false,
+        );
+    });
+});
+
+describe('the environment secret boundary', () => {
+    it('accepts an API key on create', () => {
+        expect(
+            validateApiRequest('ExecutionEnvironmentCreatePayload', {
+                name: 'vertex',
+                provider: 'vertexai',
+                apiKey: 'shhh',
+            }),
+        ).toMatchObject({ valid: true });
+    });
+
+    it('publishes apiKey on the read shape, because what comes back is the masked value', () => {
+        // Unlike the OAuth providers, the read shape does NOT drop the field: `toEnvironmentResponse`
+        // overwrites it with `apikey_hint` or a masked form of the key, so the property a caller reads
+        // is a display hint rather than a credential. The response contract has to allow it, or every
+        // environment read would fail its own check.
+        const environment = {
+            id: '68b1779130afe5403a1589ba',
+            name: 'vertex',
+            provider: 'vertexai',
+            apiKey: 'AKIA...3xQf',
+            apikey_hint: 'AKIA...3xQf',
+            account: '69d4762f24d3048c99149d0b',
+            created_by: 'u1',
+            updated_by: 'u1',
+            created_at: '2026-01-01T00:00:00.000Z',
+            updated_at: '2026-01-01T00:00:00.000Z',
+        };
+
+        expect(validateApiResponse('ExecutionEnvironment', environment)).toMatchObject({ valid: true });
+        expect(validateApiResponse('ExecutionEnvironment', { ...environment, secret: 'x' }).valid).toBe(false);
+    });
+});
+
+describe('ExecutionEnvironmentSettings', () => {
+    /**
+     * The one component in this closure published OPEN. It carried an index signature, so a setting
+     * for a provider this build has never heard of round-trips instead of being rejected — which is
+     * what the settings bag is for, and the reason it is absent from `STRICT_COMPONENTS`.
+     */
+    it('accepts a setting it does not declare', () => {
+        expect(
+            validateApiRequest('ExecutionEnvironmentUpdatePayload', {
+                settings: { bucket_access_principal: 'sa@p.iam', some_future_driver_flag: true },
+            }),
+        ).toMatchObject({ valid: true });
+    });
+
+    it('still rejects an undeclared property on the payload around it', () => {
+        expect(validateApiRequest('ExecutionEnvironmentUpdatePayload', { setttings: {} }).valid).toBe(false);
+    });
+});
+
+describe('the create and update payloads', () => {
+    /**
+     * They used to be `Omit<ExecutionEnvironment, ...>` and `Partial<Omit<...>>`. Both are stated
+     * where they are named now, from one shared field list — so the assertion that matters is that
+     * the two still describe the same fields, which the mapped types used to guarantee structurally.
+     */
+    it('describe the same fields, one requiring name and provider and the other requiring nothing', () => {
+        expect(propertiesOf('ExecutionEnvironmentUpdatePayload')).toEqual(
+            propertiesOf('ExecutionEnvironmentCreatePayload'),
+        );
+        expect(requiredOf('ExecutionEnvironmentCreatePayload')).toEqual(['name', 'provider']);
+        expect(requiredOf('ExecutionEnvironmentUpdatePayload')).toEqual([]);
+    });
+
+    it('neither accepts a server-owned field', () => {
+        // `id`, `account` and the audit fields are on the read shape only. A payload carrying one used
+        // to be silently ignored; the write shapes not listing them is what makes it a 400.
+        for (const field of ['id', 'account', 'created_by', 'created_at', 'apikey_hint']) {
+            expect(
+                validateApiRequest('ExecutionEnvironmentCreatePayload', { name: 'e', provider: 'test', [field]: 'x' })
+                    .valid,
+            ).toBe(false);
+            expect(validateApiRequest('ExecutionEnvironmentUpdatePayload', { [field]: 'x' }).valid).toBe(false);
+        }
+    });
+
+    it('accepts an empty update body', () => {
+        expect(validateApiRequest('ExecutionEnvironmentUpdatePayload', {}).valid).toBe(true);
+    });
+});
+
+describe('the model search query', () => {
+    /**
+     * `text` was published `required: true` and is optional now. The interface declared it
+     * non-optional, but `EnvironmentsApi.listModels(id, payload?)` takes the payload optionally and
+     * three existing call sites pass nothing — so enforcing the requirement the document stated would
+     * have 400'd the UI on a parameter the server never wanted.
+     */
+    it('takes no required parameter', () => {
+        // The scanner expands this component into four query parameters, and a property the component
+        // does not require becomes a parameter the document does not require.
+        expect(requiredOf('ModelSearchPayload')).toEqual([]);
+        expect(validateApiRequest('ModelSearchPayload', {}).valid).toBe(true);
+    });
+
+    it('still rejects a value outside the model-type vocabulary', () => {
+        expect(validateApiRequest('ModelSearchPayload', { type: 'text' }).valid).toBe(true);
+        expect(validateApiRequest('ModelSearchPayload', { type: 'spreadsheet' }).valid).toBe(false);
+    });
+});
+
+describe('the embeddings request', () => {
+    it('discriminates its four input shapes on type', () => {
+        expect(ApiSchemaComponents.EmbeddingsApiInput).toMatchObject({
+            discriminator: {
+                propertyName: 'type',
+                mapping: { text: expect.stringContaining('EmbeddingsApiTextInput') },
+            },
+        });
+    });
+
+    it('accepts a text input and refuses one carrying an image source', () => {
+        const request = (input: unknown) => validateApiRequest('EmbeddingsApiRequest', { inputs: [input] });
+
+        expect(request({ type: 'text', text: 'hello' })).toMatchObject({ valid: true });
+        expect(request({ type: 'text', text: 'hello', source: { url: 'gs://b/o' } }).valid).toBe(false);
+        expect(request({ type: 'image', source: { url: 'gs://b/o' } })).toMatchObject({ valid: true });
+    });
+
+    it('accepts an empty inputs array, which the handler rejects rather than the schema', () => {
+        // `minItems` is deliberately not published: an empty batch is well-formed and useless, and
+        // adding the constraint would newly reject a request the document has always described.
+        expect(validateApiRequest('EmbeddingsApiRequest', { inputs: [] }).valid).toBe(true);
+    });
+});
+
+function enumOf(component: 'SupportedProviders'): string[] {
+    const emitted = ApiSchemaComponents[component] as { enum?: unknown };
+    if (!Array.isArray(emitted?.enum)) throw new Error(`${component} is not published as an enum`);
+    return emitted.enum as string[];
+}
+
+function propertiesOf(component: string): string[] {
+    const emitted = ApiSchemaComponents[component] as { properties?: Record<string, unknown> };
+    return Object.keys(emitted?.properties ?? {});
+}
+
+function requiredOf(component: string): string[] {
+    const emitted = ApiSchemaComponents[component] as { required?: unknown };
+    return Array.isArray(emitted?.required) ? (emitted.required as string[]) : [];
+}