@vertesia/common 1.6.0-dev.20260918.090710Z → 1.6.0-dev.20260923.085325Z

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,

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(),
     })

package/src/api-schemas/registry-groups.test.ts

@@ -1,5 +1,6 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, expectTypeOf, it } from 'vitest';
 import { z } from 'zod';
+import type { NamedInteractionExecutionPayloadSchema } from './interaction.js';
 import { type ApiComponentName, type ApiComponentType, ApiSchemaComponents, mergeComponentGroups } from './registry.js';
 
 /**
@@ -30,6 +31,13 @@ type ResolvedName<N extends ApiComponentName> = [ApiComponentType<N>] extends [n
  * merge actually refuses, which no import of a correct registry can show.
  */
 describe('mergeComponentGroups', () => {
+    it('preserves execution payload types and rejects unregistered component names', () => {
+        expectTypeOf<ApiComponentType<'NamedInteractionExecutionPayload'>>().toEqualTypeOf<
+            z.infer<typeof NamedInteractionExecutionPayloadSchema>
+        >();
+        expectTypeOf<'UnregisteredExecutionComponent'>().not.toMatchTypeOf<ApiComponentName>();
+    });
+
     const A = z.strictObject({ a: z.string() });
     const B = z.strictObject({ b: z.number() });
 

package/src/api-schemas/registry.ts

@@ -77,7 +77,12 @@ import {
     RoleDefinitionArraySchema,
     SystemRoleDefinitionArraySchema,
 } from './access-control.js';
-import { AccountSchema, StripeBillingStatusResponseSchema, UpdateAccountPayloadSchema } from './account.js';
+import {
+    AccountApiVersionPolicySchema,
+    AccountSchema,
+    StripeBillingStatusResponseSchema,
+    UpdateAccountPayloadSchema,
+} from './account.js';
 import { type JsonObject, toOpenApiComponents } from './adapter.js';
 import * as AgentCommunicationSchemas from './agent-communication.js';
 import * as AgentRunSchemas from './agent-runs.js';
@@ -175,6 +180,7 @@ import {
     StartAppScaffoldResponseSchema,
     StoredTypeRefSchema,
     SystemPackageQuerySchema,
+    UpdateAppInstallationOAuthApprovalPayloadSchema,
     UpdateAppInstallationToolAllowlistPayloadSchema,
     UpsertAppVersionRequestSchema,
     ValidateUrlRequestSchema,
@@ -370,6 +376,22 @@ import {
     WorkflowExecutionStatusSchema,
 } from './document-processing.js';
 import {
+    EmbeddingBatchApplyRequestSchema,
+    EmbeddingBatchApplyResponseSchema,
+    EmbeddingBatchCapabilityRequestSchema,
+    EmbeddingBatchCapabilityResponseSchema,
+    EmbeddingBatchCreateRequestSchema,
+    EmbeddingBatchJobRequestSchema,
+    EmbeddingBatchJobResponseSchema,
+    EmbeddingBatchPrepareRequestSchema,
+    EmbeddingBatchPrepareResponseSchema,
+    EmbeddingBatchProviderStateSchema,
+    EmbeddingBatchRenditionPageRequestSchema,
+    EmbeddingBatchRenditionPageResponseSchema,
+    EmbeddingBatchRunStateSchema,
+    EmbeddingBatchRunSummarySchema,
+    EmbeddingBatchSubjobSchema,
+    EmbeddingBatchUpdateRequestSchema,
     EmbeddingsApiAudioInputSchema,
     EmbeddingsApiImageInputSchema,
     EmbeddingsApiInputSchema,
@@ -379,6 +401,7 @@ import {
     EmbeddingsApiVideoInputSchema,
     EmbeddingsStatusResponseSchema,
     ProjectConfigurationEmbeddingEnablePayloadSchema,
+    RecalculateEmbeddingsQuerySchema,
 } from './embeddings.js';
 import { emitJsonSchema } from './emit-json-schema.js';
 import {
@@ -613,6 +636,7 @@ import {
     CreateOAuthClientPayloadSchema,
     ListOAuthGrantsQuerySchema,
     OAuthAuthorizationDecisionResponseSchema,
+    OAuthAuthorizationRequestGeneratedAppSchema,
     OAuthAuthorizationRequestSchema,
     OAuthAuthorizationRequestStatusSchema,
     OAuthAuthorizationServerMetadataSchema,
@@ -635,6 +659,9 @@ import {
     OAuthGrantSortOrderSchema,
     OAuthGrantStatusSchema,
     OAuthGrantTypeSchema,
+    OAuthLoginDecisionResponseSchema,
+    OAuthLoginPayloadSchema,
+    OAuthLoginUserNotFoundResponseSchema,
     OAuthProjectBindingModeSchema,
     OAuthRegistrationSourceSchema,
     OAuthResponseTypeSchema,
@@ -816,6 +843,7 @@ import * as WorkflowRunSchemas from './workflow-runs.js';
  * group approaches the proven-safe size.
  */
 const IAM_AND_ACCOUNT_SCHEMAS = {
+    AccountApiVersionPolicy: AccountApiVersionPolicySchema,
     Account: AccountSchema,
     UpdateAccountPayload: UpdateAccountPayloadSchema,
     StripeBillingStatusResponse: StripeBillingStatusResponseSchema,
@@ -958,6 +986,10 @@ const OAUTH_SCHEMAS = {
     OAuthAuthorizeQuery: OAuthAuthorizeQuerySchema,
     CreateOAuthAuthorizationRequestPayload: CreateOAuthAuthorizationRequestPayloadSchema,
     OAuthAuthorizationRequest: OAuthAuthorizationRequestSchema,
+    OAuthAuthorizationRequestGeneratedApp: OAuthAuthorizationRequestGeneratedAppSchema,
+    OAuthLoginPayload: OAuthLoginPayloadSchema,
+    OAuthLoginUserNotFoundResponse: OAuthLoginUserNotFoundResponseSchema,
+    OAuthLoginDecisionResponse: OAuthLoginDecisionResponseSchema,
     ApproveOAuthAuthorizationRequestPayload: ApproveOAuthAuthorizationRequestPayloadSchema,
     OAuthGrantableScopesResponse: OAuthGrantableScopesResponseSchema,
     OAuthAuthorizationDecisionResponse: OAuthAuthorizationDecisionResponseSchema,
@@ -1199,7 +1231,55 @@ const AGENT_CONVERSATION_SCHEMAS = {
     ConversationState: ConversationStateSchema,
 } as const satisfies Record<string, z.ZodType>;
 
-const EXECUTION_RUN_SCHEMAS = {
+// Reference schema types by name to keep declaration output bounded without erasing payload types.
+type ExecutionRunSchemaMap = {
+    ExecutionRunStatus: typeof ExecutionRunStatusSchema;
+    RunSourceTypes: typeof RunSourceTypesSchema;
+    RunSource: typeof RunSourceSchema;
+    ExecutionRunDocRef: typeof ExecutionRunDocRefSchema;
+    ExecutionRunWorkflow: typeof ExecutionRunWorkflowSchema;
+    ExecutionRunInteraction: typeof ExecutionRunInteractionSchema;
+    ExecutionRun: typeof ExecutionRunSchema;
+    ExecutionRunRef: typeof ExecutionRunRefSchema;
+    ExecutionRunRefArray: typeof ExecutionRunRefArraySchema;
+    UpdateExecutionRunPayload: typeof UpdateExecutionRunPayloadSchema;
+    RunCreatePayload: typeof RunCreatePayloadSchema;
+    SortOrder: typeof SortOrderSchema;
+    SortOption: typeof SortOptionSchema;
+    RunSearchQuery: typeof RunSearchQuerySchema;
+    RunListQuery: typeof RunListQuerySchema;
+    RunSearchPayload: typeof RunSearchPayloadSchema;
+    InteractionExecutionPayload: typeof InteractionExecutionPayloadSchema;
+    NamedInteractionExecutionPayload: typeof NamedInteractionExecutionPayloadSchema;
+    InteractionExecutionResult: typeof InteractionExecutionResultSchema;
+    FindRunResult: typeof FindRunResultSchema;
+    FindRunResultArray: typeof FindRunResultArraySchema;
+    PopulatedExecutionRunResult: typeof PopulatedExecutionRunResultSchema;
+    LegacyExecutionRunResult: typeof LegacyExecutionRunResultSchema;
+    LegacyPopulatedExecutionRunResult: typeof LegacyPopulatedExecutionRunResultSchema;
+    InteractionExecutionConfiguration: typeof InteractionExecutionConfigurationSchema;
+    InteractionExecutionError: typeof InteractionExecutionErrorSchema;
+    ResultStorageOptions: typeof ResultStorageOptionsSchema;
+    ExecuteInteractionByEndpointQuery: typeof ExecuteInteractionByEndpointQuerySchema;
+    ExecuteInteractionByEndpointHeaders: typeof ExecuteInteractionByEndpointHeadersSchema;
+    AsyncCompletionMode: typeof AsyncCompletionModeSchema;
+    AsyncCompletionOptions: typeof AsyncCompletionOptionsSchema;
+    AsyncExecutionPayload: typeof AsyncExecutionPayloadSchema;
+    AsyncInteractionExecutionPayload: typeof AsyncInteractionExecutionPayloadSchema;
+    AsyncConversationExecutionPayload: typeof AsyncConversationExecutionPayloadSchema;
+    AsyncExecutionResult: typeof AsyncExecutionResultSchema;
+    RateLimitRequestPayload: typeof RateLimitRequestPayloadSchema;
+    RateLimitRequestResponse: typeof RateLimitRequestResponseSchema;
+    ComputeRunFacetPayload: typeof ComputeRunFacetPayloadSchema;
+    ComputeRunFacetsResponse: typeof ComputeRunFacetsResponseSchema;
+    RunSearchMetaResponse: typeof RunSearchMetaResponseSchema;
+    ToolResultsPayload: typeof ToolResultsPayloadSchema;
+    UserMessagePayload: typeof UserMessagePayloadSchema;
+    ExecutionResponse: typeof ExecutionResponseSchema;
+    RunClonePayload: typeof RunClonePayloadSchema;
+};
+
+const EXECUTION_RUN_SCHEMAS: ExecutionRunSchemaMap = {
     // A run: what was executed, by whom, and how it ended.
     ExecutionRunStatus: ExecutionRunStatusSchema,
     RunSourceTypes: RunSourceTypesSchema,
@@ -1476,7 +1556,24 @@ const INDEXING_SCHEMAS = {
 
 const EMBEDDING_ADMIN_SCHEMAS = {
     EmbeddingsStatusResponse: EmbeddingsStatusResponseSchema,
+    RecalculateEmbeddingsQuery: RecalculateEmbeddingsQuerySchema,
     ProjectConfigurationEmbeddingEnablePayload: ProjectConfigurationEmbeddingEnablePayloadSchema,
+    EmbeddingBatchProviderState: EmbeddingBatchProviderStateSchema,
+    EmbeddingBatchCapabilityRequest: EmbeddingBatchCapabilityRequestSchema,
+    EmbeddingBatchCapabilityResponse: EmbeddingBatchCapabilityResponseSchema,
+    EmbeddingBatchCreateRequest: EmbeddingBatchCreateRequestSchema,
+    EmbeddingBatchJobRequest: EmbeddingBatchJobRequestSchema,
+    EmbeddingBatchJobResponse: EmbeddingBatchJobResponseSchema,
+    EmbeddingBatchRunState: EmbeddingBatchRunStateSchema,
+    EmbeddingBatchRunSummary: EmbeddingBatchRunSummarySchema,
+    EmbeddingBatchSubjob: EmbeddingBatchSubjobSchema,
+    EmbeddingBatchPrepareRequest: EmbeddingBatchPrepareRequestSchema,
+    EmbeddingBatchPrepareResponse: EmbeddingBatchPrepareResponseSchema,
+    EmbeddingBatchRenditionPageRequest: EmbeddingBatchRenditionPageRequestSchema,
+    EmbeddingBatchRenditionPageResponse: EmbeddingBatchRenditionPageResponseSchema,
+    EmbeddingBatchUpdateRequest: EmbeddingBatchUpdateRequestSchema,
+    EmbeddingBatchApplyRequest: EmbeddingBatchApplyRequestSchema,
+    EmbeddingBatchApplyResponse: EmbeddingBatchApplyResponseSchema,
 } as const satisfies Record<string, z.ZodType>;
 
 const COMMAND_SCHEMAS = {
@@ -2049,6 +2146,7 @@ const VIEW_EXPERIENCE_SCHEMAS = {
 const APP_LIFECYCLE_SCHEMAS = {
     // What an app does once it exists: versions, builds, scaffolds, git repositories,
     // development tasks, installations and inspection.
+    UpdateAppInstallationOAuthApprovalPayload: UpdateAppInstallationOAuthApprovalPayloadSchema,
     UpdateAppInstallationToolAllowlistPayload: UpdateAppInstallationToolAllowlistPayloadSchema,
     ValidateUrlResponse: ValidateUrlResponseSchema,
     ValidateUrlRequest: ValidateUrlRequestSchema,
@@ -2246,6 +2344,8 @@ const STS_SCHEMAS = {
     EnvironmentTokenRequest: StsSchemas.EnvironmentTokenRequestSchema,
     AgentTokenRequest: StsSchemas.AgentTokenRequestSchema,
     ServiceAccountTokenRequest: StsSchemas.ServiceAccountTokenRequestSchema,
+    AppSessionTokenRequest: StsSchemas.AppSessionTokenRequestSchema,
+    AppSessionTokenResponse: StsSchemas.AppSessionTokenResponseSchema,
     IssueTokenRequest: StsSchemas.IssueTokenRequestSchema,
     IssueTokenResponse: StsSchemas.IssueTokenResponseSchema,
     IssueTokenForbiddenResponse: StsSchemas.IssueTokenForbiddenResponseSchema,
@@ -2466,6 +2566,8 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'EnvironmentTokenRequest',
     'AgentTokenRequest',
     'ServiceAccountTokenRequest',
+    'AppSessionTokenRequest',
+    'AppSessionTokenResponse',
     'IssueTokenResponse',
     'IssueTokenForbiddenResponse',
     'IssueTokenUnavailableResponse',
@@ -2481,7 +2583,7 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'QuotaStandingWindow',
     'QuotaStandingAdmissionClass',
     'QuotaTierResponse',
-    // The IAM closure. PrincipalContext is composed into PrincipalIdentity rather than hoisted,
+    // The IAM closure. AbacPrincipalContext is composed into PrincipalIdentity rather than hoisted,
     // so it has no component of its own to list.
     'User',
     'UpdateUserPayload',
@@ -2604,34 +2706,12 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     //
     // `JSONSchema` is deliberately absent: it is OPEN by design and by long-standing publication —
     // a JSON Schema carries keywords the type never enumerated. `JSONSchemaProperties` is a map.
-    'TextFallbackOptions',
-    'AzureFoundryChatOptions',
-    'ImagenOptions',
-    'VertexAIClaudeOptions',
-    'VertexAIGeminiOptions',
-    'VertexAIGeminiOmniVideoOptions',
-    'VertexAIGrokOptions',
-    'NovaCanvasOptions',
-    'BedrockConverseOptions',
-    'BedrockNovaOptions',
-    'BedrockMistralOptions',
-    'BedrockAI21Options',
-    'BedrockCohereCommandOptions',
-    'BedrockClaudeOptions',
-    'BedrockPalmyraOptions',
-    'BedrockGptOssOptions',
-    'TwelvelabsPegasusOptions',
-    'BedrockMantleResponsesOptions',
-    'BedrockMantleChatCompletionsOptions',
-    'BedrockMantleClaudeOptions',
-    'OpenAiThinkingOptions',
-    'OpenAiTextOptions',
-    'OpenRouterTextOptions',
-    'OpenAiDalleOptions',
-    'OpenAiGptImageOptions',
-    'XAIGrokImageOptions',
-    'GroqOptions',
-    'MistralTextOptions',
+    // Derive membership so new provider schemas inherit this enforcement check automatically.
+    ...ModelOptionsSchema.options.map((schema) => {
+        const id = schema.meta()?.id;
+        if (!id) throw new Error('Model option schemas must declare a component id');
+        return id;
+    }),
     // The app-manifest leaves. Every object among them is published closed today, the nested `git`
     // block included, and it is spelled `strictObject` so the emission carries it directly. The five
     // enums take no `additionalProperties` at all.
@@ -2799,6 +2879,8 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'DriftAnalysisResult',
     'DriftAnalysisProgress',
     'EmbeddingsStatusResponse',
+    'EmbeddingBatchRunSummary',
+    'RecalculateEmbeddingsQuery',
     'ProjectConfigurationEmbeddingEnablePayload',
     'GenericCommandResponse',
     'DriftAnalysisStatusResponse',
@@ -3040,6 +3122,10 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'OAuthAuthorizeQuery',
     'CreateOAuthAuthorizationRequestPayload',
     'OAuthAuthorizationRequest',
+    'OAuthAuthorizationRequestGeneratedApp',
+    'OAuthLoginPayload',
+    'OAuthLoginUserNotFoundResponse',
+    'OAuthLoginDecisionResponse',
     'ApproveOAuthAuthorizationRequestPayload',
     'OAuthGrantableScopesResponse',
     'OAuthAuthorizationDecisionResponse',
@@ -3280,6 +3366,7 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'AuditTrailQuery',
     'ViewExperienceListQuery',
     'UpdateAppInstallationToolAllowlistPayload',
+    'UpdateAppInstallationOAuthApprovalPayload',
     'ValidateUrlResponse',
     'ValidateUrlRequest',
     'AppVersionUrls',
@@ -3438,8 +3525,25 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
  * divergence. Note that `.refine()` is silently DROPPED rather than rejected, so refinements must
  * not be used to express contract rules — they would be invisible to both the spec and AJV.
  */
+function emitSchema(name: string, schema: z.ZodType): unknown {
+    const emitted = emitJsonSchema(schema) as Record<string, unknown>;
+    const rootRef = emitted.$ref;
+    const defs = emitted.$defs;
+    const expectedRef = `#/$defs/${name}`;
+    if (rootRef !== expectedRef || !defs || typeof defs !== 'object' || Array.isArray(defs)) return emitted;
+
+    const root = (defs as Record<string, unknown>)[name];
+    if (!root || typeof root !== 'object' || Array.isArray(root)) return emitted;
+    const remainingDefs = Object.fromEntries(
+        Object.entries(defs as Record<string, unknown>).filter(([id]) => id !== name),
+    );
+    return Object.keys(remainingDefs).length === 0
+        ? root
+        : { ...(root as Record<string, unknown>), $defs: remainingDefs };
+}
+
 function emitRawSchemas(): Record<string, unknown> {
-    return Object.fromEntries(Object.entries(API_SCHEMAS).map(([name, schema]) => [name, emitJsonSchema(schema)]));
+    return Object.fromEntries(Object.entries(API_SCHEMAS).map(([name, schema]) => [name, emitSchema(name, schema)]));
 }
 
 /**

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

@@ -263,8 +263,8 @@ describe('runtime tightenings — recorded as operation 25 of the 1.5 runbook',
 
     it('validates model_options against the union instead of accepting any object', () => {
         // Same class: `model_options` was `{type: object, additionalProperties: true}` in the
-        // hand-written schema and `$ref: ModelOptions` in the published component. It now has to name
-        // a driver through `_option_id`, which is the discriminator generated clients already use.
+        // hand-written schema and `$ref: ModelOptions` in the published component. The family hint
+        // is optional, but known field types and supplied IDs remain validated.
         expect(ApiSchemaComponents.ContentTypeIntakePolicy).toBeDefined();
         expect(
             validate({
@@ -272,11 +272,11 @@ describe('runtime tightenings — recorded as operation 25 of the 1.5 runbook',
             }),
             errors(),
         ).toBe(true);
-        expect(validate({ extraction: { config: { model_options: { temperature: 0.5 } } } })).toBe(false);
+        expect(validate({ extraction: { config: { model_options: { temperature: 0.5 } } } })).toBe(true);
         expect(validate({ extraction: { config: { model_options: { _option_id: 'not-a-driver' } } } })).toBe(false);
-        // The empty object is rejected for the same reason, which is why nothing may PUT it on the
-        // wire — see `normalizeModelOptions`, which drops an options bag with no options in it.
-        expect(validate({ extraction: { config: { model_options: {} } } })).toBe(false);
+        expect(validate({ extraction: { config: { model_options: {} } } })).toBe(true);
+        expect(validate({ extraction: { config: { model_options: { temperature: 'hot' } } } })).toBe(false);
+        expect(validate({ extraction: { config: { model_options: { unknown_option: true } } } })).toBe(false);
     });
 
     it('constrains the two config enums that were unconstrained strings', () => {

package/src/api-schemas/sts.ts

@@ -124,3 +124,19 @@ export const IssueTokenForbiddenResponseSchema = z
 export const IssueTokenUnavailableResponseSchema = z
     .strictObject({ error: z.string(), message: z.string() })
     .meta({ id: 'IssueTokenUnavailableResponse' });
+
+export const AppSessionTokenRequestSchema = z
+    .strictObject({
+        app_name: z.string().min(1),
+        scopes: z.array(z.string()).optional(),
+        ttl_seconds: z.number().int().min(1).max(900).optional(),
+    })
+    .meta({ id: 'AppSessionTokenRequest' });
+
+export const AppSessionTokenResponseSchema = z
+    .strictObject({
+        token: z.string(),
+        token_type: z.literal('Bearer'),
+        expires_in: z.number().int(),
+    })
+    .meta({ id: 'AppSessionTokenResponse' });

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

@@ -1,10 +1,10 @@
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import { describe, expect, it } from 'vitest';
-import type { PrincipalContext, PrincipalIdentity } from '../principal-context.js';
+import type { AbacPrincipalContext, PrincipalIdentity } from '../principal-context.js';
 import type { UpdateUserPayload, User } from '../user.js';
 import type { JsonObject } from './adapter.js';
 import { ApiSchemaComponents, apiComponentRef, validateApiRequest, validateApiResponse } from './registry.js';
-import type { PrincipalContextFromSchema, UserArrayFromSchema } from './user.js';
+import type { AbacPrincipalContextFromSchema, UserArrayFromSchema } from './user.js';
 
 /** Exact type identity — `extends` in both directions is too weak (any/unknown slip through). */
 type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
@@ -27,19 +27,23 @@ const VALID_USER = {
 describe('gate 1 — the schema is the single source of truth for the public IAM types', () => {
     it('publishes the exact schema-derived type, not a hand-written twin', () => {
         assertType<Equals<UserArrayFromSchema, User[]>>(true);
-        assertType<Equals<PrincipalContext, PrincipalContextFromSchema>>(true);
+        assertType<Equals<AbacPrincipalContext, AbacPrincipalContextFromSchema>>(true);
         expect(true).toBe(true);
     });
 
-    it('derives the inherited principal fields rather than restating them', () => {
-        // PrincipalIdentity used to `extends PrincipalContext`, so composing the schemas is what
-        // keeps the five inherited fields from becoming a twin one level down — the failure mode
-        // this batch was scoped to avoid.
-        assertType<Equals<PrincipalIdentity['clearance'], PrincipalContext['clearance']>>(true);
-        assertType<Equals<PrincipalIdentity['compartments'], PrincipalContext['compartments']>>(true);
-        assertType<Equals<PrincipalIdentity['email'], PrincipalContext['email']>>(true);
-        assertType<Equals<PrincipalIdentity['tags'], PrincipalContext['tags']>>(true);
-        assertType<Equals<PrincipalIdentity['properties'], PrincipalContext['properties']>>(true);
+    it('derives the identity fields from the ABAC context rather than restating them', () => {
+        // PrincipalIdentity `extends AbacPrincipalContext`, so composing the schemas is what keeps
+        // the inherited fields from becoming a twin one level down — the failure mode this batch was
+        // scoped to avoid. `kind` and `id` are part of the ABAC context itself (resolvable as
+        // `$principal.*`), not identity-only metadata.
+        assertType<Equals<PrincipalIdentity['kind'], AbacPrincipalContext['kind']>>(true);
+        assertType<Equals<PrincipalIdentity['id'], AbacPrincipalContext['id']>>(true);
+        assertType<Equals<PrincipalIdentity['clearance'], AbacPrincipalContext['clearance']>>(true);
+        assertType<Equals<PrincipalIdentity['compartments'], AbacPrincipalContext['compartments']>>(true);
+        assertType<Equals<PrincipalIdentity['email'], AbacPrincipalContext['email']>>(true);
+        assertType<Equals<PrincipalIdentity['tags'], AbacPrincipalContext['tags']>>(true);
+        assertType<Equals<PrincipalIdentity['properties'], AbacPrincipalContext['properties']>>(true);
+        assertType<Equals<PrincipalIdentity['kind'], 'user' | 'apikey'>>(true);
         assertType<Equals<PrincipalIdentity['id'], string>>(true);
         expect(true).toBe(true);
     });
@@ -80,20 +84,22 @@ describe('gate 1 — the schema is the single source of truth for the public IAM
 });
 
 describe('gate 2 — the published components match the closure the types come from', () => {
-    it('does not hoist PrincipalContext into a component of its own', () => {
+    it('does not hoist AbacPrincipalContext into a component of its own', () => {
         // It is a public TYPE but has never been a published component. Hoisting it would add a
         // $ref to PrincipalIdentity that every generated client would have to follow.
-        expect(Object.keys(ApiSchemaComponents)).not.toContain('PrincipalContext');
+        expect(Object.keys(ApiSchemaComponents)).not.toContain('AbacPrincipalContext');
         const props = ApiSchemaComponents.PrincipalIdentity.properties as Record<string, JsonObject>;
+        expect(props.kind).toEqual({ type: 'string', enum: ['user', 'apikey'] });
         expect(props.clearance).toEqual({ type: 'number' });
         expect(props.id).toEqual({ type: 'string' });
     });
 
-    it('publishes the composed property order, id last', () => {
-        // `.extend()` appends, which is what `interface … extends …` produced and what the document
-        // already carries.
+    it('publishes the composed property order — kind and id first', () => {
+        // `AbacPrincipalContext` lists its discriminators (kind, id) ahead of the merged BLP
+        // attributes; PrincipalIdentity `.extend({})`s it, adding nothing, so the order is the
+        // context's own.
         const props = ApiSchemaComponents.PrincipalIdentity.properties as JsonObject;
-        expect(Object.keys(props)).toEqual(['clearance', 'compartments', 'email', 'tags', 'properties', 'id']);
+        expect(Object.keys(props)).toEqual(['kind', 'id', 'clearance', 'compartments', 'email', 'tags', 'properties']);
     });
 
     it('declares the timestamps the endpoint has always shipped', () => {

package/src/api-schemas/user.ts

@@ -9,15 +9,22 @@ import { z } from 'zod';
  */
 
 /**
- * Not hoisted: no `id` in `.meta()`, so the adapter inlines it into `PrincipalIdentity` instead of
- * emitting a `PrincipalContext` component and a `$ref` the document has never published.
+ * The full principal context resolved at token-issue time — every field a rule can reference through
+ * `$principal.*`: the principal `kind`, its `id`, and the merged BLP attributes. This is the single
+ * source of truth the token server mirrors into the JWT, the shared `buildPrincipalContext`
+ * produces, and the UI condition editor offers. `kind` and `id` are first-class members here, not
+ * identity-only metadata: they are resolvable in ResourceSet/PrincipalSet conditions, so hiding them
+ * (as an earlier split of this schema did) under-declared what the server actually matches against.
  *
- * It still exists as a schema rather than being spelled out inside `PrincipalIdentitySchema`,
- * because `PrincipalContext` is a public type in its own right — consumed by PrincipalSet condition
- * evaluation and client-side ABAC tooling. Composing the two is what keeps the five inherited fields
- * from becoming a hand-written twin of the schema that publishes them.
+ * Not hoisted: no `id` in `.meta()`, so the adapter inlines it into `PrincipalIdentity` instead of
+ * emitting an `AbacPrincipalContext` component and a `$ref` the document has never published. It
+ * still exists as a schema in its own right because it is a public type composed into
+ * `PrincipalIdentitySchema` — composing is what keeps the shared fields from becoming a hand-written
+ * twin of the schema that publishes them.
  */
-export const PrincipalContextSchema = z.object({
+export const AbacPrincipalContextSchema = z.object({
+    kind: z.enum(['user', 'apikey']),
+    id: z.string(),
     clearance: z.number(),
     compartments: z.array(z.string()),
     email: z.string().optional(),
@@ -26,19 +33,18 @@ export const PrincipalContextSchema = z.object({
 });
 
 /**
- * `.extend()` rather than a fresh object literal: it appends `id` after the inherited five, which is
- * both what `interface PrincipalIdentity extends PrincipalContext` produced and the property order
- * the document already publishes.
+ * Response shape of the `/iam/users/identity` endpoint. Extends {@link AbacPrincipalContextSchema}
+ * adding nothing today: the two are kept as distinct names so identity-only fields — ones that must
+ * NOT become resolvable as `$principal.*` — can be added here later without widening the ABAC
+ * surface. Invariant: the ABAC principal context is always a subset of the identity. At this
+ * endpoint `kind` is always `user`.
  */
-export const PrincipalIdentitySchema = PrincipalContextSchema.extend({
-    id: z.string(),
-}).meta({
+export const PrincipalIdentitySchema = AbacPrincipalContextSchema.extend({}).meta({
     id: 'PrincipalIdentity',
     description:
-        "Response shape of the `/iam/users/identity` endpoint: the current principal's  {@link  " +
-        'PrincipalContext }  plus its id. Distinct from `PrincipalContext` itself because the id is ' +
-        'identity metadata, not a merged BLP field — adding it to `PrincipalContext` would ' +
-        'unintentionally expose `$principal.id` to PrincipalSet rule evaluation.',
+        "Response shape of the `/iam/users/identity` endpoint: the current principal's full ABAC " +
+        'context — its `kind` (always `user` here), `id`, and the merged BLP attributes a rule can ' +
+        'reference through `$principal.*`.',
 });
 
 /**
@@ -194,7 +200,7 @@ export const SignupPayloadSchema = z
  * The public IAM types, inferred rather than written. `../principal-context.ts`, `../user.ts` and
  * `../common.ts` re-export these under their public names.
  */
-export type PrincipalContextFromSchema = z.infer<typeof PrincipalContextSchema>;
+export type AbacPrincipalContextFromSchema = z.infer<typeof AbacPrincipalContextSchema>;
 export type PrincipalIdentityFromSchema = z.infer<typeof PrincipalIdentitySchema>;
 export type UserFromSchema = z.infer<typeof UserSchema>;
 export type UserArrayFromSchema = z.infer<typeof UserArraySchema>;

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

@@ -70,19 +70,12 @@ describe('ViewExperienceConfiguration', () => {
         ).toBe(false);
     });
 
-    it('accepts View model options that name no driver, while the shared config still requires one', () => {
-        // The regression: a View's `model_options` are authored in the editor and saved before any
-        // driver is resolved, so they carry no `_option_id`. Validating them against the
-        // `ModelOptions` driver union — every branch of which requires that discriminator — meant a
-        // stored View could not satisfy its own response schema, and `GET /views` logged a contract
-        // violation on every call.
+    it('accepts untagged View options and preserves the shared options schema reference', () => {
+        // View options and shared model options both permit an omitted family ID.
         const authored = { model_options: { temperature: 0.2, max_tokens: 1024 } };
         expect(validateApiResponse('ViewAgenticExecutionConfiguration', authored).valid).toBe(true);
 
-        // The split is the point: agent runs, events and workflow runs record options a driver
-        // already resolved, so the shared component keeps the union. Asserted on the published
-        // schema because `InteractionExecutionConfiguration` is not itself a response slot — if it
-        // ever stops pointing at `ModelOptions`, the relaxation leaked out of Views.
+        // Keep the shared component wired to the canonical options contract.
         const modelOptions = (name: string) =>
             (ApiSchemaComponents[name] as { properties: Record<string, unknown> }).properties.model_options;
         expect(modelOptions('InteractionExecutionConfiguration')).toEqual({

package/src/apps.ts

@@ -51,6 +51,7 @@ import type {
     StartAppDevelopmentTaskRequestSchema,
     StartAppScaffoldRequestSchema,
     StartAppScaffoldResponseSchema,
+    UpdateAppInstallationOAuthApprovalPayloadSchema,
     UpdateAppInstallationToolAllowlistPayloadSchema,
     UpsertAppVersionRequestSchema,
     ValidateUrlRequestSchema,
@@ -752,3 +753,5 @@ export type ValidateUrlResponse = z.infer<typeof ValidateUrlResponseSchema>;
  * already deleted. Deriving the type is what keeps the two from drifting again.
  */
 export type AppDeleteSummary = z.infer<typeof AppDeleteSummarySchema>;
+
+export type UpdateAppInstallationOAuthApprovalPayload = z.infer<typeof UpdateAppInstallationOAuthApprovalPayloadSchema>;

package/src/embeddings.ts

@@ -1,6 +1,22 @@
 import type { EmbeddingsResult } from '@llumiverse/common';
 import type { z } from 'zod';
 import type {
+    EmbeddingBatchApplyRequestSchema,
+    EmbeddingBatchApplyResponseSchema,
+    EmbeddingBatchCapabilityRequestSchema,
+    EmbeddingBatchCapabilityResponseSchema,
+    EmbeddingBatchCreateRequestSchema,
+    EmbeddingBatchJobRequestSchema,
+    EmbeddingBatchJobResponseSchema,
+    EmbeddingBatchPrepareRequestSchema,
+    EmbeddingBatchPrepareResponseSchema,
+    EmbeddingBatchProviderStateSchema,
+    EmbeddingBatchRenditionPageRequestSchema,
+    EmbeddingBatchRenditionPageResponseSchema,
+    EmbeddingBatchRunStateSchema,
+    EmbeddingBatchRunSummarySchema,
+    EmbeddingBatchSubjobSchema,
+    EmbeddingBatchUpdateRequestSchema,
     EmbeddingsApiAudioInputSchema,
     EmbeddingsApiImageInputSchema,
     EmbeddingsApiInputSchema,
@@ -8,6 +24,7 @@ import type {
     EmbeddingsApiSourceSchema,
     EmbeddingsApiTextInputSchema,
     EmbeddingsApiVideoInputSchema,
+    RecalculateEmbeddingsQuerySchema,
 } from './api-schemas/embeddings.js';
 
 /**
@@ -36,3 +53,20 @@ export type EmbeddingsApiRequest = z.infer<typeof EmbeddingsApiRequestSchema>;
  * that prefer to consume types from @vertesia/common.
  */
 export type EmbeddingsApiResult = EmbeddingsResult;
+export type RecalculateEmbeddingsQuery = z.infer<typeof RecalculateEmbeddingsQuerySchema>;
+export type EmbeddingBatchCapabilityRequest = z.infer<typeof EmbeddingBatchCapabilityRequestSchema>;
+export type EmbeddingBatchCapabilityResponse = z.infer<typeof EmbeddingBatchCapabilityResponseSchema>;
+export type EmbeddingBatchCreateRequest = z.infer<typeof EmbeddingBatchCreateRequestSchema>;
+export type EmbeddingBatchJobRequest = z.infer<typeof EmbeddingBatchJobRequestSchema>;
+export type EmbeddingBatchJobResponse = z.infer<typeof EmbeddingBatchJobResponseSchema>;
+export type EmbeddingBatchProviderState = z.infer<typeof EmbeddingBatchProviderStateSchema>;
+export type EmbeddingBatchRunState = z.infer<typeof EmbeddingBatchRunStateSchema>;
+export type EmbeddingBatchRunSummary = z.infer<typeof EmbeddingBatchRunSummarySchema>;
+export type EmbeddingBatchSubjob = z.infer<typeof EmbeddingBatchSubjobSchema>;
+export type EmbeddingBatchPrepareRequest = z.infer<typeof EmbeddingBatchPrepareRequestSchema>;
+export type EmbeddingBatchPrepareResponse = z.infer<typeof EmbeddingBatchPrepareResponseSchema>;
+export type EmbeddingBatchRenditionPageRequest = z.infer<typeof EmbeddingBatchRenditionPageRequestSchema>;
+export type EmbeddingBatchRenditionPageResponse = z.infer<typeof EmbeddingBatchRenditionPageResponseSchema>;
+export type EmbeddingBatchUpdateRequest = z.infer<typeof EmbeddingBatchUpdateRequestSchema>;
+export type EmbeddingBatchApplyRequest = z.infer<typeof EmbeddingBatchApplyRequestSchema>;
+export type EmbeddingBatchApplyResponse = z.infer<typeof EmbeddingBatchApplyResponseSchema>;