@vertesia/common 1.5.0 → 1.5.1

package/src/api-schemas/account.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 // From the values module, never from `user.ts`: `user.ts` derives its public types from the schemas
 // below, so importing it here would invert the dependency and make the source of truth circular.
 import { ACCOUNT_APP_ACCESS_MESSAGE_MAX_LENGTH, AccountType, BillingMethod, QuotaTier } from '../account-values.js';
+import { ApiVersions } from '../versions.js';
 
 /**
  * Runtime API schemas for the Accounts endpoints.
@@ -148,3 +149,10 @@ export type AccountBillingFromSchema = z.infer<typeof AccountBillingSchema>;
 export type AccountFromSchema = z.infer<typeof AccountSchema>;
 export type UpdateAccountPayloadFromSchema = z.infer<typeof UpdateAccountPayloadSchema>;
 export type StripeBillingStatusResponseFromSchema = z.infer<typeof StripeBillingStatusResponseSchema>;
+
+/** Account-wide defaults for request API version negotiation. */
+export const AccountApiVersionPolicySchema = z
+    .strictObject({
+        default_api_version: z.enum(ApiVersions).optional(),
+    })
+    .meta({ id: 'AccountApiVersionPolicy' });

package/src/api-schemas/app-runtime.ts

@@ -455,6 +455,13 @@ export const CompositeAppMenuNavItemSchema: z.ZodType<CompositeAppMenuNavItem> =
             .boolean()
             .meta({ description: 'When true, this item is excluded from the Composite App dashboard cards' })
             .optional(),
+        openInAppPortal: z
+            .boolean()
+            .meta({
+                description:
+                    'When true, this item navigates to the App Portal form of the URL (`/apps/<appName><route>`) instead of the Composite App form (`/app/<appName><route>`), so the app is opened standalone rather than inside the Composite App shell.',
+            })
+            .optional(),
         permissions: CompositeAppNavItemPermissionsSchema.meta({
             description: 'Optional access control settings for this nav item',
         }).optional(),

package/src/api-schemas/apps.ts

@@ -113,12 +113,15 @@ export const AppUIConfigSchema = z
     })
     .meta({ id: 'AppUIConfig' });
 
-export const ToolCollectionAuthTypeSchema = z.enum(['oauth', 'api_key', 'other']).meta({
+export const ToolCollectionAuthTypeSchema = z.enum(['none', 'oauth', 'api_key', 'other']).meta({
     id: 'ToolCollectionAuthType',
     description:
-        "Authentication type for tool collections.\n- 'oauth': the runtime resolves a per-user or per-project " +
+        "Authentication type for tool collections.\n- 'none': connect directly without credentials for MCP collections; " +
+        'does not disable authentication for Vertesia SDK collections\n' +
+        "- 'oauth': the runtime resolves a per-user or per-project " +
         "OAuth access token\n- 'api_key': a static key held in the project's secret store is sent as the RFC 6750 " +
-        'bearer token (`Authorization: Bearer <key>`)',
+        'bearer token (`Authorization: Bearer <key>`)\n' +
+        "- 'other' or omitted: use the legacy provider connection-details flow for MCP collections",
 });
 
 export const MCPOAuthConfigSchema = z

package/src/api-schemas/content.ts

@@ -499,6 +499,10 @@ export const CollectionSchema = z
                     "List of property names from the collection's properties that should be shared with (injected into) member objects. These properties will be propagated to all members of this collection and merged as arrays.",
             })
             .optional(),
+        user_permissions: ContentObjectUserPermissionsSchema.meta({
+            description:
+                "Computed per-request permissions for the current user on this collection. Not stored — computed on the fly from the collection's security field (same semantics as a content object's user_permissions).",
+        }).optional(),
     })
     .meta({ id: 'Collection' });
 

package/src/api-schemas/embeddings.ts

@@ -102,10 +102,40 @@ export const EmbeddingsApiRequestSchema = z
     })
     .meta({ id: 'EmbeddingsApiRequest' });
 
+export const EmbeddingBatchRunStateSchema = z.enum([
+    'preparing',
+    'submitted',
+    'running',
+    'applying',
+    'completed',
+    'completed_with_errors',
+    'cancelled',
+    'stale',
+    'failed',
+]);
+
+export const EmbeddingBatchRunSummarySchema = z
+    .strictObject({
+        id: z.string(),
+        state: EmbeddingBatchRunStateSchema,
+        model: z.string(),
+        created_at: z.string().meta({ format: 'date-time' }),
+        completed_at: z.string().meta({ format: 'date-time' }).optional(),
+        applied: z.number().int().nonnegative(),
+        skipped: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        stale: z.number().int().nonnegative(),
+    })
+    .meta({
+        id: 'EmbeddingBatchRunSummary',
+        description: 'Latest batch run for this embedding type, without provider payloads or input content.',
+    });
+
 export const EmbeddingsStatusResponseSchema = z
     .strictObject({
         status: z.string(),
         embeddingRunsInProgress: z.number().optional(),
+        latestBatchRun: EmbeddingBatchRunSummarySchema.optional(),
         totalIndexableObjects: z.number().optional(),
         embeddingsModels: z.array(z.string()).optional(),
         objectsWithEmbeddings: z.number().optional(),
@@ -117,6 +147,25 @@ export const EmbeddingsStatusResponseSchema = z
     })
     .meta({ id: 'EmbeddingsStatusResponse' });
 
+export const RecalculateEmbeddingsQuerySchema = z
+    .strictObject({
+        mode: z
+            .literal('sync')
+            .meta({
+                description:
+                    'Force synchronous per-object recalculation. When omitted, batch inference is used when supported.',
+            })
+            .optional(),
+        force: z
+            .boolean()
+            .meta({
+                description:
+                    'Recalculate all eligible objects, including current embeddings. Token limits still apply; existing renditions are reused.',
+            })
+            .optional(),
+    })
+    .meta({ id: 'RecalculateEmbeddingsQuery' });
+
 export const ProjectConfigurationEmbeddingEnablePayloadSchema = z
     .strictObject({
         environment: z.string(),
@@ -124,3 +173,138 @@ export const ProjectConfigurationEmbeddingEnablePayloadSchema = z
         model: z.string().optional(),
     })
     .meta({ id: 'ProjectConfigurationEmbeddingEnablePayload' });
+
+export const EmbeddingBatchProviderStateSchema = z.enum([
+    'pending',
+    'running',
+    'succeeded',
+    'failed',
+    'cancelled',
+    'paused',
+]);
+
+export const EmbeddingBatchCapabilityRequestSchema = z
+    .strictObject({ embedding_type: SupportedEmbeddingTypesSchema })
+    .meta({ id: 'EmbeddingBatchCapabilityRequest' });
+
+export const EmbeddingBatchCapabilityResponseSchema = z
+    .strictObject({
+        eligible: z.boolean(),
+        reason: z.string().optional(),
+        environment: z.string().optional(),
+        provider: z.string().optional(),
+        model: z.string().optional(),
+        dimensions: z.number().int().positive().optional(),
+        max_tokens: z.number().int().positive().optional(),
+        location: z.string().optional(),
+        input_format: z.string().optional(),
+        max_rows: z.number().int().positive().optional(),
+        artifact_uri: z.string().optional(),
+    })
+    .meta({ id: 'EmbeddingBatchCapabilityResponse' });
+
+export const EmbeddingBatchCreateRequestSchema = z
+    .strictObject({
+        embedding_type: SupportedEmbeddingTypesSchema,
+        model: z.string(),
+        dimensions: z.number().int().positive(),
+        display_name: z.string(),
+        input_uri: z.string(),
+        output_uri: z.string(),
+    })
+    .meta({ id: 'EmbeddingBatchCreateRequest' });
+
+export const EmbeddingBatchJobRequestSchema = z
+    .strictObject({
+        embedding_type: SupportedEmbeddingTypesSchema,
+        model: z.string(),
+        name: z.string(),
+        include_output_artifacts: z.boolean().optional().meta({
+            description:
+                'On get, resolve terminal result artifacts for application. Omit for lightweight status polling.',
+        }),
+    })
+    .meta({ id: 'EmbeddingBatchJobRequest' });
+
+export const EmbeddingBatchJobResponseSchema = z
+    .strictObject({
+        name: z.string(),
+        display_name: z.string().optional(),
+        state: EmbeddingBatchProviderStateSchema,
+        model: z.string().optional(),
+        input_uri: z.string().optional(),
+        output_uri: z.string().optional(),
+        output_artifacts: z.array(z.string()).optional().meta({
+            description:
+                'Terminal job result artifacts in application storage, including partial results. Never provider file IDs.',
+        }),
+        error_message: z.string().optional(),
+    })
+    .meta({ id: 'EmbeddingBatchJobResponse' });
+
+export const EmbeddingBatchPrepareRequestSchema = z
+    .strictObject({
+        run_id: z.string(),
+        embedding_type: SupportedEmbeddingTypesSchema,
+        capability: EmbeddingBatchCapabilityResponseSchema,
+    })
+    .meta({ id: 'EmbeddingBatchPrepareRequest' });
+
+export const EmbeddingBatchSubjobSchema = z.strictObject({
+    index: z.number().int().nonnegative(),
+    display_name: z.string(),
+    input_uri: z.string(),
+    output_uri: z.string(),
+    row_count: z.number().int().nonnegative(),
+    provider_name: z.string().optional(),
+    state: EmbeddingBatchProviderStateSchema.optional(),
+});
+
+export const EmbeddingBatchPrepareResponseSchema = z
+    .strictObject({
+        run_id: z.string(),
+        row_count: z.number().int().nonnegative(),
+        subjobs: z.array(EmbeddingBatchSubjobSchema),
+    })
+    .meta({ id: 'EmbeddingBatchPrepareResponse' });
+
+export const EmbeddingBatchRenditionPageRequestSchema = z
+    .strictObject({ run_id: z.string() })
+    .meta({ id: 'EmbeddingBatchRenditionPageRequest' });
+
+export const EmbeddingBatchRenditionPageResponseSchema = z
+    .strictObject({
+        status: z.enum(['running', 'page_completed', 'completed']),
+        page_index: z.number().int().nonnegative(),
+        page_scanned: z.number().int().nonnegative(),
+        page_ready: z.number().int().nonnegative(),
+        page_generated: z.number().int().nonnegative(),
+        page_failed: z.number().int().nonnegative(),
+        running: z.number().int().nonnegative(),
+    })
+    .meta({ id: 'EmbeddingBatchRenditionPageResponse' });
+
+export const EmbeddingBatchUpdateRequestSchema = z
+    .strictObject({
+        run_id: z.string(),
+        state: EmbeddingBatchRunStateSchema,
+        subjobs: z.array(EmbeddingBatchSubjobSchema).optional(),
+        error_code: z.string().optional(),
+        error_message: z.string().optional(),
+    })
+    .meta({ id: 'EmbeddingBatchUpdateRequest' });
+
+export const EmbeddingBatchApplyRequestSchema = z
+    .strictObject({ run_id: z.string() })
+    .meta({ id: 'EmbeddingBatchApplyRequest' });
+
+export const EmbeddingBatchApplyResponseSchema = z
+    .strictObject({
+        state: EmbeddingBatchRunStateSchema,
+        succeeded: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        stale: z.number().int().nonnegative(),
+        applied: z.number().int().nonnegative(),
+        failure_counts: z.record(z.string(), z.number().int().nonnegative()).optional(),
+    })
+    .meta({ id: 'EmbeddingBatchApplyResponse' });

package/src/api-schemas/files.ts

@@ -74,6 +74,7 @@ export const BulkUploadUrlsPayloadSchema = z
 export const FileBucketResponseSchema = z
     .strictObject({
         bucket: z.string(),
+        location: z.string().optional(),
     })
     .meta({ id: 'FileBucketResponse' });
 

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import type { GenericCommandResponse } from '../common.js';
+import type { RecalculateEmbeddingsQuery } from '../embeddings.js';
 import type {
     DriftAnalysisStatusResponse,
     EmbeddingsStatusResponse,
@@ -11,7 +12,11 @@ import type {
 } from '../project.js';
 import { WorkflowExecutionStatus } from '../store/workflow.js';
 import type { GenericCommandResponseSchema } from './commands.js';
-import type { EmbeddingsStatusResponseSchema, ProjectConfigurationEmbeddingEnablePayloadSchema } from './embeddings.js';
+import type {
+    EmbeddingsStatusResponseSchema,
+    ProjectConfigurationEmbeddingEnablePayloadSchema,
+    RecalculateEmbeddingsQuerySchema,
+} from './embeddings.js';
 import type {
     DriftAnalysisStatusResponseSchema,
     IndexingStatusResponseSchema,
@@ -28,6 +33,7 @@ describe('indexing and embedding API contracts', () => {
     it('derives every public type from its domain schema', () => {
         assertType<Equals<GenericCommandResponse, typeof GenericCommandResponseSchema._output>>(true);
         assertType<Equals<EmbeddingsStatusResponse, typeof EmbeddingsStatusResponseSchema._output>>(true);
+        assertType<Equals<RecalculateEmbeddingsQuery, typeof RecalculateEmbeddingsQuerySchema._output>>(true);
         assertType<Equals<IndexingStatusResponse, typeof IndexingStatusResponseSchema._output>>(true);
         assertType<Equals<DriftAnalysisStatusResponse, typeof DriftAnalysisStatusResponseSchema._output>>(true);
         assertType<
@@ -51,6 +57,39 @@ describe('indexing and embedding API contracts', () => {
         );
     });
 
+    it('allows only the explicit synchronous embedding recalculation override', () => {
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', {}).valid).toBe(true);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { mode: 'sync' }).valid).toBe(true);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { force: true }).valid).toBe(true);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { mode: 'sync', force: true }).valid).toBe(true);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { force_renditions: true }).valid).toBe(false);
+        expect(validateApiRequest('RecalculateEmbeddingsQuery', { mode: 'batch' }).valid).toBe(false);
+    });
+
+    it('validates the optional batch summary without exposing stored run fields', () => {
+        const summary = {
+            id: 'run-1',
+            state: 'completed_with_errors',
+            model: 'model-1',
+            created_at: '2026-01-01T00:00:00Z',
+            applied: 110,
+            skipped: 17,
+            failed: 0,
+            stale: 0,
+        };
+        expect(
+            validateApiResponse('EmbeddingsStatusResponse', {
+                status: 'success',
+                vectorIndex: { status: 'READY' },
+                latestBatchRun: summary,
+            }).valid,
+        ).toBe(true);
+        expect(validateApiResponse('EmbeddingBatchRunSummary', { ...summary, applied: -1 }).valid).toBe(false);
+        expect(validateApiResponse('EmbeddingBatchRunSummary', { ...summary, prefix_uri: 'private' }).valid).toBe(
+            false,
+        );
+    });
+
     it('keeps drift workflow status numeric and nullable identifiers explicit', () => {
         expect(
             validateApiResponse('DriftAnalysisStatusResponse', {

package/src/api-schemas/interaction.ts

@@ -487,6 +487,7 @@ export const InteractionPublishPayloadSchema = z
 
 export const InteractionForkPayloadSchema = z
     .strictObject({
+        newName: z.string().optional(),
         keepTags: z.boolean().optional(),
         forkPrompts: z.boolean().optional(),
         targetProject: z.string().optional(),
@@ -2410,6 +2411,7 @@ export const ResolveInteractionQuerySchema = z
     .strictObject({
         environment: z.string().optional(),
         model: z.string().optional(),
+        inherit_model_config: InteractionExecutionConfigurationSchema.shape.inherit_model_config,
         hasImage: z.boolean().optional(),
         hasVideo: z.boolean().optional(),
     })

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

@@ -1,4 +1,5 @@
 import type { JSONSchema, ModelOptions } from '@llumiverse/common';
+import { ModelOptionsSchema } from '@llumiverse/common/schemas';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import { describe, expect, it } from 'vitest';
 import type { JsonObject } from './adapter.js';
@@ -19,35 +20,12 @@ function compile(name: string) {
     return ajv.compile({ $ref: `vertesia://openapi${apiComponentRef(name as never)}` });
 }
 
-const UNION_MEMBERS = [
-    'TextFallbackOptions',
-    'AzureFoundryChatOptions',
-    'ImagenOptions',
-    'VertexAIClaudeOptions',
-    'VertexAIGeminiOptions',
-    'VertexAIGeminiOmniVideoOptions',
-    'VertexAIGrokOptions',
-    'NovaCanvasOptions',
-    'BedrockConverseOptions',
-    'BedrockNovaOptions',
-    'BedrockMistralOptions',
-    'BedrockAI21Options',
-    'BedrockCohereCommandOptions',
-    'BedrockClaudeOptions',
-    'BedrockPalmyraOptions',
-    'BedrockGptOssOptions',
-    'TwelvelabsPegasusOptions',
-    'BedrockMantleResponsesOptions',
-    'BedrockMantleChatCompletionsOptions',
-    'BedrockMantleClaudeOptions',
-    'OpenAiThinkingOptions',
-    'OpenAiTextOptions',
-    'OpenAiDalleOptions',
-    'OpenAiGptImageOptions',
-    'XAIGrokImageOptions',
-    'GroqOptions',
-    'MistralTextOptions',
-];
+// Follow the canonical union; do not maintain a second provider membership list here.
+const UNION_MEMBERS = ModelOptionsSchema.options.map((schema) => {
+    const id = schema.meta()?.id;
+    if (!id) throw new Error('Model option schemas must declare a component id');
+    return id;
+});
 
 describe('the ModelOptions closure is published whole and enforced closed', () => {
     it('hoists every union member and enum into its own component', () => {
@@ -59,18 +37,29 @@ describe('the ModelOptions closure is published whole and enforced closed', () =
         }
     });
 
-    it('publishes a discriminator whose mapping covers every member', () => {
-        const union = ApiSchemaComponents.ModelOptions as JsonObject & {
-            oneOf: { $ref: string }[];
-            discriminator: { propertyName: string; mapping: Record<string, string> };
-        };
-        expect(union.discriminator.propertyName).toBe('_option_id');
-        expect(union.oneOf.map((member) => member.$ref)).toEqual(
+    it('publishes every optional-ID family as anyOf, without a required discriminator', () => {
+        const union = ApiSchemaComponents.ModelOptions as JsonObject & { anyOf: { $ref: string }[] };
+        expect(union.discriminator).toBeUndefined();
+        expect(union.oneOf).toBeUndefined();
+        expect(union.required ?? []).not.toContain('_option_id');
+        expect(union.anyOf.map((member) => member.$ref)).toEqual(
             UNION_MEMBERS.map((name) => `#/components/schemas/${name}`),
         );
-        // A mapping short of the `oneOf` is the failure that matters: a generated Java or Go client
-        // reads the mapping to pick the concrete subtype and falls back to a loose map without it.
-        expect(new Set(Object.values(union.discriminator.mapping))).toEqual(new Set(union.oneOf.map((m) => m.$ref)));
+        for (const name of UNION_MEMBERS) {
+            expect((ApiSchemaComponents[name] as JsonObject).required ?? [], name).not.toContain('_option_id');
+        }
+    });
+
+    it.each([
+        {},
+        { temperature: 0.2, max_tokens: 1024 },
+        { cache_enabled: true, cache_ttl: '1h', thinking_budget_tokens: 1024 },
+        { extra_body: { provider_extension: true } },
+    ] satisfies ModelOptions[])('accepts untagged options through the run request contract: %j', (model_options) => {
+        const payload = { interaction: 'Chat', config: { model: 'claude-sonnet-4-6', model_options } };
+        expect(validateApiRequest('RunCreatePayload', payload).valid).toBe(true);
+        expect(payload.config.model_options).not.toHaveProperty('_option_id');
+        expect(compile('ModelOptions')(model_options)).toBe(true);
     });
 
     it('enforces the closure it documents — an undeclared option is rejected, not ignored', () => {
@@ -112,6 +101,48 @@ describe('the ModelOptions closure is published whole and enforced closed', () =
         expect(validate({ _option_id: 'openai-text', extra_body: ['invalid'] })).toBe(false);
     });
 
+    it('accepts Anthropic options through the run request contract', () => {
+        const payload = {
+            interaction: 'Chat',
+            config: {
+                model: 'claude-sonnet-4-6',
+                model_options: {
+                    _option_id: 'anthropic-claude',
+                    effort: 'high',
+                    cache_enabled: true,
+                    cache_ttl: '1h',
+                },
+            },
+        };
+        expect(validateApiRequest('RunCreatePayload', payload).valid).toBe(true);
+        expect(
+            validateApiRequest('RunCreatePayload', {
+                ...payload,
+                config: { ...payload.config, model_options: { ...payload.config.model_options, cache_ttl: '2h' } },
+            }).valid,
+        ).toBe(false);
+    });
+
+    it.each([
+        { _option_id: 'bedrock-nova', top_k: 12 },
+        { _option_id: 'bedrock-mistral', top_k: 12 },
+        { _option_id: 'bedrock-ai21', presence_penalty: 0.4, frequency_penalty: 0.2 },
+        { _option_id: 'bedrock-cohere-command', top_k: 12, presence_penalty: 0.4, frequency_penalty: 0.2 },
+        { _option_id: 'bedrock-mantle-responses', effort: 'max', reasoning_effort: 'max' },
+        { _option_id: 'vertexai-imagen', person_generation: 'allow_adult', mask_class: [0, 42] },
+        { _option_id: 'vertexai-imagen', person_generation: 'allow_adults' },
+        { _option_id: 'bedrock-nova-canvas', taskType: 'OUTPAINTING', outPaintingMode: 'DEFAULT' },
+    ] satisfies ModelOptions[])('accepts restored provider options: %j', (model_options) => {
+        const payload = { interaction: 'Chat', config: { model: 'model', model_options } };
+        expect(validateApiRequest('RunCreatePayload', payload).valid).toBe(true);
+        expect(
+            validateApiRequest('RunCreatePayload', {
+                ...payload,
+                config: { ...payload.config, model_options: { ...model_options, unknown_option: true } },
+            }).valid,
+        ).toBe(false);
+    });
+
     it('accepts Gemini Omni task and resolution options through the run request contract', () => {
         const result = validateApiRequest('RunCreatePayload', {
             interaction: 'GenerateVideo',

package/src/api-schemas/mcp-api-key.contract.test.ts

@@ -84,3 +84,42 @@ describe('McpApiKeyStatus', () => {
         );
     });
 });
+
+describe('MCP anonymous authentication — emitted contract', () => {
+    const collection = {
+        type: 'mcp',
+        id: 'public',
+        name: 'Public tools',
+        description: 'Public tools',
+        namespace: 'public',
+        url: 'https://example.com/mcp',
+    };
+
+    it.each(['none', 'oauth', 'api_key', 'other', undefined])('accepts auth=%s', (auth) => {
+        expect(
+            validateApiRequest('AppManifestData', {
+                name: 'public-mcp',
+                title: 'Public MCP',
+                description: 'Public tools',
+                publisher: 'Vertesia',
+                status: 'beta',
+                visibility: 'private',
+                tool_collections: [{ ...collection, auth }],
+            }).valid,
+        ).toBe(true);
+    });
+
+    it('rejects unknown authentication modes', () => {
+        expect(
+            validateApiRequest('AppManifestData', {
+                name: 'public-mcp',
+                title: 'Public MCP',
+                description: 'Public tools',
+                publisher: 'Vertesia',
+                status: 'beta',
+                visibility: 'private',
+                tool_collections: [{ ...collection, auth: 'anonymous' }],
+            }).valid,
+        ).toBe(false);
+    });
+});

package/src/api-schemas/project-configuration.ts

@@ -67,11 +67,12 @@ export const ProjectSearchTierSchema = z.enum(['standard', 'performance']).meta(
 export const ElasticsearchBackendSchema = z.enum(['serverless', 'hosted']).meta({ id: 'ElasticsearchBackend' });
 
 export const ProjectSearchPropertyTypeSchema = z
-    .enum(['keyword', 'text', 'boolean', 'long', 'double', 'date', 'geo_point'])
+    .enum(['keyword', 'text', 'boolean', 'long', 'double', 'date', 'geo_point', 'nested'])
     .meta({
         id: 'ProjectSearchPropertyType',
         description:
-            'Elasticsearch field types that may be explicitly assigned to content-object properties. Paths are ' +
+            'Elasticsearch field types that may be explicitly assigned to content-object properties. ' +
+            'Declare nested object-array paths with type `nested` and their children as separate dotted paths. Paths are ' +
             "relative to the object's `properties` field.",
     });
 
@@ -99,7 +100,8 @@ export const ProjectSearchPropertyMappingSchema = z
         id: 'ProjectSearchPropertyMapping',
         description:
             'Explicit search mapping for one content-object property.\n\nChanging a mapping requires a full ' +
-            'reindex. Existing Elasticsearch fields cannot change type in place.',
+            'reindex. Existing Elasticsearch fields cannot change type in place. A `nested` mapping accepts no ' +
+            'scalar options; declare its searchable child fields as separate mappings below its path.',
     });
 
 /**

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

@@ -242,6 +242,21 @@ describe('gate 2 — the closure is closed, bottom-up', () => {
         expect(SYSTEM_INTERACTION_CATEGORIES.ContentSearchReranker).toBe(SystemInteractionCategory.analysis);
     });
 
+    it('uses the agent model default for every app development agent', () => {
+        // Each is launched in-code without an environment or model of its own, so an uncategorised
+        // one silently resolves to the project BASE default instead of the agent default.
+        for (const endpoint of [
+            'AppDevelopmentOrchestrator',
+            'AppSolutionArchitect',
+            'AppDesigner',
+            'AppDeveloper',
+            'AppReviewer',
+            'AppTester',
+        ]) {
+            expect(SYSTEM_INTERACTION_CATEGORIES[endpoint]).toBe(SystemInteractionCategory.agent);
+        }
+    });
+
     it('publishes the property-mapping map without the propertyNames z.record adds', () => {
         // `Record<string, ProjectSearchPropertyMapping>` is inline in the interface and has no
         // TypeScript name, so it never becomes a canonical alias — it stays canonical AND derived,
@@ -253,6 +268,21 @@ describe('gate 2 — the closure is closed, bottom-up', () => {
         });
     });
 
+    it('accepts explicit nested paths through the project configuration contract', () => {
+        expect(ApiSchemaComponents.ProjectSearchPropertyType.enum).toContain('nested');
+        expect(
+            validateApiRequest('UpdateProjectConfigurationPayload', {
+                indexing: {
+                    property_mappings: {
+                        line_items: { type: 'nested' },
+                        'line_items.sku': { type: 'keyword' },
+                        'line_items.quantity': { type: 'long' },
+                    },
+                },
+            }).valid,
+        ).toBe(true);
+    });
+
     it('publishes geo_point as an explicit project property mapping type', () => {
         expect(ApiSchemaComponents.ProjectSearchPropertyType.enum).toContain('geo_point');
     });

package/src/api-schemas/prompt.ts

@@ -34,6 +34,7 @@ export const PromptTemplateInteractionVersionSchema = z
 
 export const PromptTemplateForkPayloadSchema = z
     .strictObject({
+        newName: z.string().optional(),
         keepTags: z.boolean().optional(),
         targetProject: z.string().optional(),
     })