@vertesia/common 1.5.0-dev.20260807.073259Z → 1.5.0-dev.20260901.005903Z

package/src/api-schemas/content.ts

@@ -300,27 +300,54 @@ export const EmbeddingMapSchema = z.object({}).catchall(EmbeddingSchema).meta({
  * keeps emitting under the base's `id` and collides with it in the published document.
  */
 const collectionPayloadFields = {
-    description: z.string().optional(),
-    skip_head_sync: z.boolean().optional(),
-    tags: z.array(z.string()).optional(),
-    type: nullableStringSchema.optional(),
-    query: z.looseObject({}).optional(),
-    properties: z.looseObject({}).optional(),
-    parent: nullableStringSchema.optional(),
+    description: z.string().meta({ description: 'Description of the collection and its purpose' }).optional(),
+    skip_head_sync: z
+        .boolean()
+        .meta({
+            description: 'When true the collection does not track and sync member HEAD revisions. Defaults to false.',
+        })
+        .optional(),
+    tags: z.array(z.string()).meta({ description: 'Categorization tags for the collection' }).optional(),
+    type: nullableStringSchema
+        .meta({ description: 'Default content type ID for documents in the collection' })
+        .optional(),
+    query: z
+        .looseObject({})
+        .meta({ description: 'MongoDB query that determines membership of a dynamic collection' })
+        .optional(),
+    properties: z.looseObject({}).meta({ description: 'Metadata properties attached to the collection' }).optional(),
+    parent: nullableStringSchema.meta({ description: 'Parent collection ID when the collection is nested' }).optional(),
     table_layout: z
         .array(ColumnLayoutSchema)
         .nullable()
-        .meta({ anyOf: undefined, type: ['array', 'null'], items: { $ref: 'ColumnLayout' } })
+        .meta({
+            anyOf: undefined,
+            type: ['array', 'null'],
+            items: { $ref: 'ColumnLayout' },
+            description: 'Column layout used when listing collection members',
+        })
+        .optional(),
+    allowed_types: z
+        .array(z.string())
+        .meta({ description: 'Content type IDs allowed to be added to the collection' })
+        .optional(),
+    updated_by: z.string().meta({ description: 'Identity recorded as the updater of the collection' }).optional(),
+    shared_properties: z
+        .array(z.string())
+        .meta({ description: 'Names of collection properties whose values are propagated to member documents' })
         .optional(),
-    allowed_types: z.array(z.string()).optional(),
-    updated_by: z.string().optional(),
-    shared_properties: z.array(z.string()).optional(),
     sensitivity: z.number().meta({ description: 'BLP sensitivity level for member documents' }).optional(),
     compartments: z.array(z.string()).meta({ description: 'Compartments for member documents' }).optional(),
 };
 
 export const CreateCollectionPayloadSchema = z
-    .strictObject({ ...collectionPayloadFields, name: z.string(), dynamic: z.boolean() })
+    .strictObject({
+        ...collectionPayloadFields,
+        name: z.string().meta({ description: 'Name of the collection' }),
+        dynamic: z.boolean().meta({
+            description: 'When true, membership is determined by `query`; when false, members are added explicitly',
+        }),
+    })
     .meta({ id: 'CreateCollectionPayload' });
 
 /**
@@ -331,8 +358,13 @@ export const CreateCollectionPayloadSchema = z
 export const UpdateCollectionPayloadSchema = z
     .strictObject({
         ...collectionPayloadFields,
-        name: z.string().optional(),
-        dynamic: z.boolean().optional(),
+        name: z.string().meta({ description: 'Name of the collection' }).optional(),
+        dynamic: z
+            .boolean()
+            .meta({
+                description: 'When true, membership is determined by `query`; when false, members are added explicitly',
+            })
+            .optional(),
     })
     .meta({ id: 'UpdateCollectionPayload', description: 'Fields to change on a collection. All optional.' });
 
@@ -780,6 +812,15 @@ export const ContentObjectApiResponseSchema = z
         is_locked: z.boolean().optional(),
         score: z.number().optional(),
         user_permissions: ContentObjectUserPermissionsSchema.optional(),
+        searchTypeResult: z
+            .array(
+                z.strictObject({
+                    type: z.string(),
+                    score: z.number(),
+                    rank: z.number(),
+                }),
+            )
+            .optional(),
         text: z.string().optional(),
         text_etag: z.string().optional(),
         embeddings: EmbeddingMapSchema.optional(),
@@ -793,6 +834,7 @@ export const ContentObjectApiResponseSchema = z
                 description:
                     'BLP sensitivity level — set directly or inherited from collections (max across collections).',
             })
+            .nullable()
             .optional(),
         compartments: z
             .array(z.string())
@@ -804,6 +846,18 @@ export const ContentObjectApiResponseSchema = z
     })
     .meta({ id: 'ContentObjectApiResponse' });
 
+/**
+ * Read shape for field-projected objects. Projection intentionally changes requiredness without
+ * weakening the full object or any create/update payload.
+ */
+export const ProjectedContentObjectApiResponseSchema = ContentObjectApiResponseSchema.partial().meta({
+    id: 'ProjectedContentObjectApiResponse',
+});
+
+export const ProjectedContentObjectApiResponseArraySchema = z
+    .array(ProjectedContentObjectApiResponseSchema)
+    .meta({ id: 'ProjectedContentObjectApiResponseArray' });
+
 export const ComputeObjectFacetPayloadSchema = z
     .strictObject({
         facets: z.array(FacetSpecSchema),
@@ -841,6 +895,25 @@ export const ContentObjectItemApiResponseSchema = z
         is_locked: z.boolean().optional(),
         score: z.number().optional(),
         user_permissions: ContentObjectUserPermissionsSchema.optional(),
+        searchTypeResult: z
+            .array(
+                z.strictObject({
+                    type: z.string(),
+                    score: z.number(),
+                    rank: z.number(),
+                }),
+            )
+            .optional(),
+        text: z.string().optional(),
+        text_etag: z.string().optional(),
+        embeddings: EmbeddingMapSchema.optional(),
+        parts: z.array(z.string()).optional(),
+        parts_etag: z.string().optional(),
+        transcript: z.looseObject({}).optional(),
+        security: StringArrayMapSchema.optional(),
+        sensitivity: z.number().nullable().optional(),
+        compartments: z.array(z.string()).optional(),
+        inherited_properties: z.array(InheritedPropertyMetadataSchema).optional(),
     })
     .meta({ id: 'ContentObjectItemApiResponse' });
 
@@ -882,7 +955,7 @@ export const ContentObjectItemApiResponseArraySchema = z
 
 export const ObjectSearchResponseSchema = z
     .strictObject({
-        results: z.array(ContentObjectItemApiResponseSchema),
+        results: z.array(ProjectedContentObjectApiResponseSchema),
         facets: ComputedFacetResponseSchema,
         aggregations: z.looseObject({}).optional(),
     })

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

@@ -69,13 +69,23 @@ describe('dashboard request validation', () => {
         );
     });
 
-    it('derives update as the partial create shape plus skip_versioning', () => {
-        expect(validateApiRequest('UpdateDashboardPayload', {})).toMatchObject({ valid: true });
-        expect(validateApiRequest('UpdateDashboardPayload', { spec: { mark: 'line' } })).toMatchObject({
+    it('accepts legacy updates without a revision while rejecting undeclared fields', () => {
+        expect(validateApiRequest('UpdateDashboardPayload', {}).valid).toBe(true);
+        expect(validateApiRequest('UpdateDashboardPayload', { summary: 'Legacy update' }).valid).toBe(true);
+        expect(
+            validateApiRequest('UpdateDashboardPayload', {
+                expected_edit_revision: 1,
+                spec: { mark: 'line' },
+            }),
+        ).toMatchObject({
             valid: true,
         });
-        expect(validateApiRequest('UpdateDashboardPayload', { skip_versioning: true })).toMatchObject({ valid: true });
-        expect(validateApiRequest('UpdateDashboardPayload', { unknown: true }).valid).toBe(false);
+        expect(
+            validateApiRequest('UpdateDashboardPayload', { expected_edit_revision: 1, skip_versioning: true }),
+        ).toMatchObject({ valid: true });
+        expect(validateApiRequest('UpdateDashboardPayload', { expected_edit_revision: 1, unknown: true }).valid).toBe(
+            false,
+        );
     });
 
     it('keeps the two bulk bodies as the free-form string-array map already published', () => {
@@ -88,6 +98,7 @@ describe('dashboard request validation', () => {
 describe('dashboard response validation', () => {
     const item = {
         id: 'dashboard-1',
+        edit_revision: 1,
         name: 'Revenue',
         tags: [],
         updated_by: 'user:editor',

package/src/api-schemas/dashboard.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { DashboardStatus } from '../data-platform.js';
 import { StringValueMapSchema } from './files.js';
+import { EditRevisionSchema, ExpectedEditRevisionSchema } from './schema-primitives.js';
 
 export const DashboardElasticsearchResultMappingSchema = z
     .discriminatedUnion('type', [
@@ -179,6 +180,7 @@ export const DashboardVersionItemArraySchema = z
 export const DashboardItemSchema = z
     .strictObject({
         id: z.string().meta({ description: 'Unique identifier for the object' }),
+        edit_revision: EditRevisionSchema,
         name: z.string().meta({ description: 'Human-readable name or title' }),
         description: z.string().meta({ description: 'Optional detailed description of the object' }).optional(),
         tags: z.array(z.string()).meta({ description: 'Tags for organization' }),
@@ -345,6 +347,7 @@ export const CreateDashboardPayloadSchema = z
 
 export const UpdateDashboardPayloadSchema = CreateDashboardPayloadSchema.partial()
     .extend({
+        expected_edit_revision: ExpectedEditRevisionSchema,
         name: z.string().meta({ description: 'Dashboard name' }).optional(),
         skip_versioning: z.boolean().meta({ description: 'Skip auto-version creation' }).optional(),
     })

package/src/api-schemas/events.ts

@@ -8,7 +8,12 @@ import * as AuditTrailSchemas from './audit-trail.js';
 import { StringValueMapSchema } from './files.js';
 import { ConversationVisibilitySchema, NumberValueMapSchema } from './interaction.js';
 import { JsonLogicRuleSchema, ProcessDefinitionBodySchema, ProcessRunTypeSchema } from './process.js';
-import { nullableNumberSchema, nullableStringSchema } from './schema-primitives.js';
+import {
+    EditRevisionSchema,
+    ExpectedEditRevisionSchema,
+    nullableNumberSchema,
+    nullableStringSchema,
+} from './schema-primitives.js';
 import { InteractionExecutionConfigurationSchema } from './store.js';
 
 export const ServerSentEventsResponseSchema = z.string().meta({ id: 'ServerSentEventsResponse' });
@@ -151,6 +156,7 @@ export const EventDeliverySortFieldSchema = z
 export const WorkflowRuleItemSchema = z
     .strictObject({
         id: z.string().meta({ description: 'Unique identifier for the object' }),
+        edit_revision: EditRevisionSchema,
         name: z.string().meta({ description: 'Human-readable name or title' }),
         description: z.string().meta({ description: 'Optional detailed description of the object' }).optional(),
         tags: z.array(z.string()).meta({ description: 'Optional array of categorization tags' }).optional(),
@@ -236,6 +242,7 @@ export const EventDeliveryQueueSortFieldSchema = z
 export const WorkflowRuleSchema = z
     .strictObject({
         id: z.string().meta({ description: 'Unique identifier for the object' }),
+        edit_revision: EditRevisionSchema,
         name: z.string().meta({ description: 'Human-readable name or title' }),
         description: z.string().meta({ description: 'Optional detailed description of the object' }).optional(),
         tags: z.array(z.string()).meta({ description: 'Optional array of categorization tags' }).optional(),
@@ -319,6 +326,7 @@ export const CreateWorkflowRulePayloadSchema = z
  */
 export const UpdateWorkflowRulePayloadSchema = z
     .strictObject({
+        expected_edit_revision: ExpectedEditRevisionSchema,
         ...workflowRulePayloadFields,
         endpoint: z.string().optional(),
         name: z.string().meta({ description: 'Human-readable name or title' }).optional(),

package/src/api-schemas/files.ts

@@ -31,6 +31,7 @@ export const FileMetadataResponseSchema = z
         contentType: z.string(),
         contentDisposition: z.string().optional(),
         etag: z.string().optional(),
+        generation: z.string().optional(),
         customMetadata: StringValueMapSchema.optional(),
     })
     .meta({ id: 'FileMetadataResponse' });
@@ -157,3 +158,29 @@ export const BucketReadAccessStatusResponseSchema = z
         hasAccess: z.boolean(),
     })
     .meta({ id: 'BucketReadAccessStatusResponse' });
+
+export const BucketCreateAccessQuerySchema = z
+    .strictObject({
+        principal: z.string(),
+    })
+    .meta({ id: 'BucketCreateAccessQuery' });
+
+export const EnsureBucketCreateAccessPayloadSchema = BucketCreateAccessQuerySchema.meta({
+    id: 'EnsureBucketCreateAccessPayload',
+});
+
+export const EnsureBucketCreateAccessResponseSchema = z
+    .strictObject({
+        bucket: z.string(),
+        principal: z.string(),
+        granted: z.boolean(),
+    })
+    .meta({ id: 'EnsureBucketCreateAccessResponse' });
+
+export const BucketCreateAccessStatusResponseSchema = z
+    .strictObject({
+        bucket: z.string(),
+        principal: z.string(),
+        hasAccess: z.boolean(),
+    })
+    .meta({ id: 'BucketCreateAccessStatusResponse' });

package/src/api-schemas/group.ts

@@ -64,6 +64,16 @@ export const UserGroupSchema = z
  */
 export const UserGroupArraySchema = z.array(UserGroupSchema).meta({ id: 'UserGroupArray' });
 
+export const ListUserGroupsQuerySchema = z
+    .object({
+        search: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+        limit: z.number().optional(),
+        offset: z.number().optional(),
+        project: z.string().optional(),
+    })
+    .meta({ id: 'ListUserGroupsQuery' });
+
 /**
  * Both payloads are picked from {@link UserGroupSchema}, for the same reason `UserRef` is: they are
  * subsets of the group, not parallel shapes. What each `.pick()` leaves out is the whitelist —

package/src/api-schemas/index.ts

@@ -11,12 +11,14 @@
  */
 export * from './account.js';
 export * from './adapter.js';
+export * from './agent-communication.js';
 export * from './agent-runs.js';
 export * from './analytics.js';
 export * from './apikey.js';
 export * from './app-runtime.js';
 export * from './bulk-operation.js';
 export * from './content.js';
+export * from './content-query.js';
 export * from './cost-analytics.js';
 export * from './dashboard.js';
 export * from './data-store.js';
@@ -26,10 +28,12 @@ export * from './environment.js';
 export * from './events.js';
 export * from './indexing.js';
 export * from './integrations.js';
+export * from './oauth-server.js';
 export * from './parameters.js';
 export * from './process.js';
 export * from './quota.js';
 export * from './registry.js';
 export * from './secrets.js';
+export { CreateContentObjectTypePayloadSchema, InteractionExecutionConfigurationSchema } from './store.js';
 export * from './view-execution.js';
 export * from './workflow-runs.js';

package/src/api-schemas/integrations.ts

@@ -5,6 +5,11 @@ import { SupportedIntegrations } from '../integrations.js';
 import { StringValueMapSchema } from './files.js';
 import { DSLActivityOptionsSchema } from './process.js';
 
+const agentOnlyDecryptedSecretSchema = z.string().meta({
+    description:
+        'Decrypted credential returned only to authenticated agent principals for runtime use. Human and service-account callers receive null; presence and hint fields report configuration status.',
+});
+
 export const SupportedIntegrations_ask_user_webhookSchema = z
     .literal(SupportedIntegrations.ask_user_webhook)
     .meta({ id: 'SupportedIntegrations_ask_user_webhook' });
@@ -45,9 +50,16 @@ export const AskUserWebhookConfigurationSchema = z
     .strictObject({
         integration: SupportedIntegrations_ask_user_webhookSchema,
         enabled: z.boolean(),
-        webhook_url: z.string().meta({ description: 'Webhook URL to receive ask_user events' }),
+        // Optional on the RESPONSE only — `AskUserWebhookConfigurationInputSchema` still requires it,
+        // because you cannot configure the integration without one. `getIntegrationConfig` reads
+        // `integrations?.[integrationId] ?? {}`, so a project that never set this integration up
+        // legitimately answers with the discriminator and `enabled` alone, and a required
+        // `webhook_url` made that answer fail its own response contract on every call. Same defect
+        // and same fix as `AwsConfiguration.s3_role_arn`.
+        webhook_url: z.string().meta({ description: 'Webhook URL to receive ask_user events' }).optional(),
         has_webhook_secret: z.boolean().optional(),
         webhook_secret_hint: z.string().optional(),
+        webhook_secret: agentOnlyDecryptedSecretSchema.nullable(),
         events: z
             .array(z.enum(['requested', 'resolved']))
             .meta({ description: "Which events to send: ['requested', 'resolved'] or subset (default: both)" })
@@ -68,6 +80,7 @@ export const ResendConfigurationSchema = z
         enabled: z.boolean(),
         has_api_key: z.boolean().optional(),
         api_key_hint: z.string().optional(),
+        api_key: agentOnlyDecryptedSecretSchema.nullable(),
         email_domain: z
             .string()
             .meta({ description: 'Domain for email (both sending and receiving). Must be verified in Resend.' }),
@@ -77,6 +90,7 @@ export const ResendConfigurationSchema = z
             .optional(),
         has_webhook_secret: z.boolean().optional(),
         webhook_secret_hint: z.string().optional(),
+        webhook_secret: agentOnlyDecryptedSecretSchema.nullable(),
         allowed_sender_domains: z
             .array(z.string())
             .meta({ description: 'Domains allowed to send emails TO start agents (for inbound validation)' })
@@ -98,6 +112,7 @@ export const LinkupConfigurationSchema = z
         enabled: z.boolean(),
         has_api_key: z.boolean().optional(),
         api_key_hint: z.string().optional(),
+        api_key: agentOnlyDecryptedSecretSchema.nullable(),
     })
     .meta({ id: 'LinkupConfiguration' });
 
@@ -107,6 +122,7 @@ export const ExaConfigurationSchema = z
         enabled: z.boolean(),
         has_api_key: z.boolean().optional(),
         api_key_hint: z.string().optional(),
+        api_key: agentOnlyDecryptedSecretSchema.nullable(),
     })
     .meta({ id: 'ExaConfiguration' });
 
@@ -116,6 +132,7 @@ export const SerperConfigurationSchema = z
         enabled: z.boolean(),
         has_api_key: z.boolean().optional(),
         api_key_hint: z.string().optional(),
+        api_key: agentOnlyDecryptedSecretSchema.nullable(),
         url: z.string().optional(),
     })
     .meta({ id: 'SerperConfiguration' });
@@ -145,6 +162,7 @@ export const GladiaConfigurationSchema = z
         enabled: z.boolean(),
         has_api_key: z.boolean().optional(),
         api_key_hint: z.string().optional(),
+        api_key: agentOnlyDecryptedSecretSchema.nullable(),
         url: z.string().optional(),
     })
     .meta({ id: 'GladiaConfiguration' });
@@ -269,7 +287,14 @@ export const AwsConfigurationSchema = z
     .strictObject({
         integration: SupportedIntegrations_awsSchema,
         enabled: z.boolean(),
-        s3_role_arn: z.string(),
+        // Optional because "declared but not configured" is a real state, not legacy data:
+        // `getIntegrationConfig` reads `integrations?.[integrationId] ?? {}`, so a project that has
+        // never set up AWS answers `{ integration: 'aws', enabled: false }` with no role ARN at all.
+        // Requiring it here made that answer fail its own response contract. The consumers already
+        // agree it is optional — the server guards on `s3_role_arn` being present before assuming a
+        // role, and every sibling integration marks its config fields optional for the same reason
+        // (`github_app_id`, `url`, ...).
+        s3_role_arn: z.string().optional(),
     })
     .meta({ id: 'AwsConfiguration' });
 

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

@@ -1,8 +1,84 @@
 import { describe, expect, it } from 'vitest';
 import type { AsyncConversationExecutionPayload } from '../interaction.js';
-import { AsyncConversationExecutionPayloadSchema } from './interaction.js';
+import {
+    AsyncConversationExecutionPayloadSchema,
+    ComputeRunFacetPayloadSchema,
+    ComputeRunFacetsResponseSchema,
+    ConversationStateSchema,
+    ExecutionRunRefSchema,
+    FindRunResultSchema,
+    InCodeInteractionSchema,
+    InteractionCreatePayloadSchema,
+    InteractionPromptSegmentInputSchema,
+    InteractionSchema,
+    InteractionUpdatePayloadSchema,
+    PromptSegmentDefSchema,
+    ResolvedCatalogInteractionSchema,
+} from './interaction.js';
+
+describe('conversation state contract', () => {
+    it('publishes the tool catalog storage scope used to resolve tool references', () => {
+        expect(ConversationStateSchema.shape.tool_catalog_storage_id.safeParse('process-run-1').success).toBe(true);
+    });
+});
+
+describe('in-code interaction contract', () => {
+    it('retains prompt schemas when resolving a catalog interaction', () => {
+        const interaction = InCodeInteractionSchema.parse({
+            type: 'sys',
+            id: 'sys:GeneralAgent',
+            name: 'GeneralAgent',
+            title: 'General Agent',
+            tags: ['agent'],
+            agent_runner_options: { is_agent: true, request_template: '{{user_prompt}}' },
+            prompts: [
+                {
+                    role: 'user',
+                    content: '{{user_prompt}}',
+                    content_type: 'handlebars',
+                    schema: {
+                        type: 'object',
+                        properties: { user_prompt: { type: 'string', editor: 'textarea' } },
+                    },
+                },
+            ],
+        });
+
+        expect(interaction.prompts[0]?.schema).toMatchObject({
+            properties: { user_prompt: { type: 'string' } },
+        });
+    });
+
+    it('requires normalized title and tags only on the resolved response', () => {
+        const authoringShape = {
+            type: 'sys',
+            id: 'sys:Untitled',
+            name: 'Untitled',
+            prompts: [],
+        };
+
+        expect(InCodeInteractionSchema.safeParse(authoringShape).success).toBe(true);
+        expect(ResolvedCatalogInteractionSchema.safeParse(authoringShape).success).toBe(false);
+        expect(
+            ResolvedCatalogInteractionSchema.safeParse({ ...authoringShape, title: 'Untitled', tags: [] }).success,
+        ).toBe(true);
+    });
+});
 
 describe('AsyncConversationExecutionPayload contract', () => {
+    it('accepts caller-provided metadata and enrichment controls', () => {
+        const payload: AsyncConversationExecutionPayload = {
+            type: 'conversation',
+            interaction: 'sys:AppTester',
+            title: 'Manual title',
+            topic: 'Manual topic',
+            generate_topic: false,
+            generate_lessons: false,
+        };
+
+        expect(AsyncConversationExecutionPayloadSchema.parse(payload)).toMatchObject(payload);
+    });
+
     it('retains an immutable app-version execution target', () => {
         const payload: AsyncConversationExecutionPayload = {
             type: 'conversation',
@@ -25,3 +101,130 @@ describe('AsyncConversationExecutionPayload contract', () => {
         ).toThrow();
     });
 });
+
+describe('run facet contracts', () => {
+    const facets = [
+        { name: 'environments', field: 'environment' },
+        { name: 'interactions', field: 'interaction' },
+        { name: 'models', field: 'modelId' },
+        { name: 'statuses', field: 'status' },
+        { name: 'finish_reason', field: 'finish_reason' },
+    ];
+
+    it('accepts exactly the supported run facet pairs', () => {
+        expect(ComputeRunFacetPayloadSchema.parse({ facets })).toEqual({ facets });
+    });
+
+    it.each(['tags', 'created_by', 'start', 'end'])('rejects the removed %s facet', (field) => {
+        expect(ComputeRunFacetPayloadSchema.safeParse({ facets: [{ name: field, field }] }).success).toBe(false);
+    });
+
+    it('rejects mismatched and additional facet names', () => {
+        expect(ComputeRunFacetPayloadSchema.safeParse({ facets: [{ name: 'models', field: 'status' }] }).success).toBe(
+            false,
+        );
+        expect(ComputeRunFacetPayloadSchema.safeParse({ facets: [{ name: 'custom', field: 'modelId' }] }).success).toBe(
+            false,
+        );
+    });
+
+    it('keeps removed facet fields available as query filters', () => {
+        const query = {
+            tags: ['visible'],
+            created_by: 'user:123',
+            start: '2026-08-01T00:00:00.000Z',
+            end: '2026-08-02T00:00:00.000Z',
+        };
+
+        expect(ComputeRunFacetPayloadSchema.parse({ facets: [], query })).toEqual({ facets: [], query });
+    });
+
+    it('rejects removed and custom response facets', () => {
+        expect(ComputeRunFacetsResponseSchema.safeParse({ tags: [] }).success).toBe(false);
+        expect(ComputeRunFacetsResponseSchema.safeParse({ custom: [] }).success).toBe(false);
+    });
+});
+
+describe('run response contracts', () => {
+    it('retains an environment ID when a run references a deleted environment', () => {
+        expect(ExecutionRunRefSchema.shape.environment.parse('env-deleted')).toBe('env-deleted');
+        expect(ExecutionRunRefSchema.shape.environment.parse(null)).toBeNull();
+    });
+
+    it('models the arbitrary stored-field projection returned by /runs/find', () => {
+        expect(
+            FindRunResultSchema.parse({
+                id: 'run-1',
+                environment: 'env-1',
+                account: 'account-1',
+                project: 'project-1',
+                interaction: 'interaction-1',
+                result: [],
+                parameters: { query: 'test' },
+            }),
+        ).toMatchObject({ environment: 'env-1', account: 'account-1', project: 'project-1' });
+    });
+
+    it('does not publish run persistence-only fields', () => {
+        expect(() => FindRunResultSchema.parse({ interaction_code: 'sys:Example' })).toThrow();
+        expect(() => FindRunResultSchema.parse({ tmp_prompt: [] })).toThrow();
+    });
+
+    it('models enriched supported run facet buckets', () => {
+        expect(
+            ComputeRunFacetsResponseSchema.parse({
+                environments: [{ _id: 'env-1', count: 2, name: 'Default' }],
+                interactions: [{ _id: 'interaction-1', count: 1, name: 'Example', status: 'published', version: 3 }],
+                models: [{ _id: 'gpt', count: 2 }],
+                total: 2,
+            }),
+        ).toMatchObject({ total: 2 });
+    });
+});
+
+describe('interaction contracts', () => {
+    const populatedPrompt = {
+        role: 'user',
+        content: 'Hello',
+        content_type: 'text',
+        id: 'prompt-1',
+        name: 'Greeting',
+        status: 'draft',
+        version: 1,
+        project: 'project-1',
+        created_by: 'user-1',
+        updated_by: 'user-1',
+        created_at: '2026-08-20T00:00:00.000Z',
+        updated_at: '2026-08-20T00:00:00.000Z',
+    };
+
+    it('accepts the media-result storage setting on interaction payloads and responses', () => {
+        expect(InteractionSchema.shape.store_media_results.parse(true)).toBe(true);
+        expect(InteractionCreatePayloadSchema.shape.store_media_results.parse(false)).toBe(false);
+        expect(InteractionUpdatePayloadSchema.shape.store_media_results.parse(true)).toBe(true);
+    });
+
+    it('keeps legacy populated prompts valid in interaction write payloads', () => {
+        const segment = { type: 'template', template: populatedPrompt };
+
+        expect(InteractionPromptSegmentInputSchema.safeParse(segment).success).toBe(true);
+        expect(
+            InteractionPromptSegmentInputSchema.safeParse({
+                ...segment,
+                template: { ...populatedPrompt, edit_revision: 3 },
+            }).success,
+        ).toBe(true);
+    });
+
+    it('still requires edit revisions on populated prompts returned by the API', () => {
+        const segment = { type: 'template', template: populatedPrompt };
+
+        expect(PromptSegmentDefSchema.safeParse(segment).success).toBe(false);
+        expect(
+            PromptSegmentDefSchema.safeParse({
+                ...segment,
+                template: { ...populatedPrompt, edit_revision: 3 },
+            }).success,
+        ).toBe(true);
+    });
+});