@vertesia/common 1.5.0 → 1.5.1

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';
@@ -364,6 +369,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,
@@ -373,6 +394,7 @@ import {
     EmbeddingsApiVideoInputSchema,
     EmbeddingsStatusResponseSchema,
     ProjectConfigurationEmbeddingEnablePayloadSchema,
+    RecalculateEmbeddingsQuerySchema,
 } from './embeddings.js';
 import {
     EnableEnvironmentModelPayloadSchema,
@@ -809,6 +831,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,
@@ -1205,6 +1228,12 @@ const EXECUTION_RUN_SCHEMAS = {
     RunSearchQuery: RunSearchQuerySchema,
     RunListQuery: RunListQuerySchema,
     RunSearchPayload: RunSearchPayloadSchema,
+} as const satisfies Record<string, z.ZodType>;
+
+// Split out of EXECUTION_RUN_SCHEMAS rather than grown in place: one literal covering both halves
+// infers a type too large for tsc to serialize into the declaration file (TS7056). The split is
+// purely structural — `mergeComponentGroups` and `ApiSchemaMap` see the same component set.
+const INTERACTION_EXECUTION_SCHEMAS = {
     // Executing an interaction, synchronously or as a workflow.
     InteractionExecutionPayload: InteractionExecutionPayloadSchema,
     NamedInteractionExecutionPayload: NamedInteractionExecutionPayloadSchema,
@@ -1463,7 +1492,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 = {
@@ -2256,6 +2302,7 @@ const API_SCHEMA_GROUPS = [
     INTERACTION_AUTHORING_SCHEMAS,
     AGENT_CONVERSATION_SCHEMAS,
     EXECUTION_RUN_SCHEMAS,
+    INTERACTION_EXECUTION_SCHEMAS,
     PROMPT_AUTHORING_SCHEMAS,
     PROJECT_TOOL_SCHEMAS,
     REMOTE_MCP_SCHEMAS,
@@ -2318,6 +2365,7 @@ type ApiSchemaMap = typeof IAM_AND_ACCOUNT_SCHEMAS &
     typeof INTERACTION_AUTHORING_SCHEMAS &
     typeof AGENT_CONVERSATION_SCHEMAS &
     typeof EXECUTION_RUN_SCHEMAS &
+    typeof INTERACTION_EXECUTION_SCHEMAS &
     typeof PROMPT_AUTHORING_SCHEMAS &
     typeof PROJECT_TOOL_SCHEMAS &
     typeof REMOTE_MCP_SCHEMAS &
@@ -2435,7 +2483,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',
@@ -2558,33 +2606,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',
-    '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.
@@ -2752,6 +2779,8 @@ const STRICT_COMPONENTS: ReadonlySet<string> = new Set<string>([
     'DriftAnalysisResult',
     'DriftAnalysisProgress',
     'EmbeddingsStatusResponse',
+    'EmbeddingBatchRunSummary',
+    'RecalculateEmbeddingsQuery',
     'ProjectConfigurationEmbeddingEnablePayload',
     'GenericCommandResponse',
     'DriftAnalysisStatusResponse',
@@ -3384,13 +3413,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 emitRawSchemas(): Record<string, unknown> {
-    return Object.fromEntries(
-        Object.entries(API_SCHEMAS).map(([name, schema]) => [
-            name,
-            z.toJSONSchema(schema, { target: 'draft-2020-12', io: 'input' }),
-        ]),
+function emitSchema(name: string, schema: z.ZodType): unknown {
+    const emitted = z.toJSONSchema(schema, { target: 'draft-2020-12', io: 'input' }) 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, emitSchema(name, schema)]));
 }
 
 /**

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

@@ -6,7 +6,7 @@ import { ContentTypeIntakePolicySchema as GeneratedIntakePolicySchema } from '..
 import type { ContentObjectTypeRef, ContentTypeIntakePolicy, IntakePageRanges } from '../store/store.js';
 import type { JsonObject } from './adapter.js';
 import { ApiSchemaComponents, bundleCanonicalComponent, validateApiResponse } from './registry.js';
-import { ContentTypeIntakePolicySchema } from './store.js';
+import { ContentTypeIntakePolicySchema, InteractionExecutionConfigurationSchema } from './store.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;
@@ -103,26 +103,15 @@ describe.skipIf(!publishedDocument)('gate — generated artifact = canonical com
         }
     });
 
-    it('drops the discriminator hint the published component keeps, and only that', () => {
-        // The one place the artifact and the component are allowed to differ, pinned from both sides
-        // so neither can move alone. `synthesizeDiscriminator` restates `type` and `required` on the
-        // union node for the generated Java/Go clients; the node has no `properties`, and Gemini
-        // rejects the whole tool schema over it ("requires unspecified property '_option_id'") when
-        // the artifact reaches Vertex inside `create_or_update_type`'s input schema.
-        expect(published.ModelOptions).toMatchObject({
-            discriminator: { propertyName: '_option_id' },
-            type: 'object',
-            required: ['_option_id'],
-        });
-
+    it('preserves optional-ID anyOf semantics in the bundled option schema', () => {
         const bundled = ($defsOf(GeneratedIntakePolicySchema) as Record<string, Record<string, unknown>>).ModelOptions;
+        const component = published.ModelOptions as { anyOf: unknown[]; discriminator?: unknown; required?: string[] };
         expect(bundled.discriminator).toBeUndefined();
-        expect(bundled.required).toBeUndefined();
-        expect(bundled.type).toBeUndefined();
-        // The branches are what carried the contract all along, so nothing was validated away.
-        expect((bundled.oneOf as unknown[]).length).toBe(
-            ((published.ModelOptions as { oneOf: unknown[] }).oneOf ?? []).length,
-        );
+        expect(component.discriminator).toBeUndefined();
+        expect(bundled.required ?? []).not.toContain('_option_id');
+        expect(component.required ?? []).not.toContain('_option_id');
+        expect((bundled.anyOf as unknown[]).length).toBe(component.anyOf.length);
+        expect(bundled.oneOf).toBeUndefined();
     });
 
     it('registers the component the alias claims, under the id the alias name requires', () => {
@@ -385,8 +374,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({
@@ -394,11 +383,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', () => {
@@ -498,3 +487,14 @@ describe('the five content-type shapes are composed, not repeated', () => {
         ).toBe(true);
     });
 });
+
+describe('inherited execution model configuration', () => {
+    it.each([true, false, undefined])('preserves inherit_model_config=%s in the wire contract', (inherit) => {
+        const config = { environment: 'parent-env', model: 'parent-model', inherit_model_config: inherit };
+        expect(InteractionExecutionConfigurationSchema.parse(config)).toEqual(config);
+        const schema = bundleCanonicalComponent('InteractionExecutionConfiguration');
+        const validateConfig = ajv.compile(schema);
+        expect(validateConfig(config), ajv.errorsText(validateConfig.errors)).toBe(true);
+        expect(validateConfig({ ...config, inherit_model_config: 'true' })).toBe(false);
+    });
+});

package/src/api-schemas/store.ts

@@ -80,6 +80,10 @@ export const InteractionExecutionConfigurationSchema = z
         id: z.string().optional(),
         environment: z.string().optional(),
         model: z.string().optional(),
+        inherit_model_config: z.boolean().optional().meta({
+            description:
+                'Treat environment and model as inherited fallbacks after interaction settings, before project defaults.',
+        }),
         do_validate: z.boolean().optional(),
         run_data: RunDataStorageLevelSchema.optional(),
         configMode: ConfigModesSchema.optional(),

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

@@ -688,6 +688,12 @@ export interface CompositeAppMenuNavItem {
     description?: string | null;
     /** When true, this item is excluded from the Composite App dashboard cards */
     hideFromDashboard?: boolean;
+    /**
+     * 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.
+     */
+    openInAppPortal?: boolean;
     /** Optional access control settings for this nav item */
     permissions?: CompositeAppNavItemPermissions;
     /** Ordered child nav-items */

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>;

package/src/index.ts

@@ -8,7 +8,7 @@ export * from './analytics.js';
  */
 export type { UserGroupArrayFromSchema } from './api-schemas/group.js';
 export type {
-    PrincipalContextFromSchema,
+    AbacPrincipalContextFromSchema,
     UserArrayFromSchema,
     UserRefArrayFromSchema,
 } from './api-schemas/user.js';
@@ -51,6 +51,7 @@ export * from './schema-for-extraction.js';
 export * from './secrets.js';
 export * from './skill.js';
 export * from './store/index.js';
+export * from './store/rendering.js';
 export type {
     ContentObjectExportArtifact,
     ContentObjectExportArtifactFile,

package/src/interaction.ts

@@ -61,6 +61,7 @@ import type {
     ResolvedEnvironmentInfoSchema,
     ResolvedInteractionExecutionInfoSchema,
     ResolvedRuntimeConfigSchema,
+    ResolveInteractionQuerySchema,
     ResultStorageOptionsSchema,
     RunSourceSchema,
     SchemaRefSchema,
@@ -121,12 +122,7 @@ export interface ExecuteInteractionByEndpointHeaders {
     'x-interaction-tag'?: string;
 }
 
-export interface ResolveInteractionQuery {
-    environment?: string;
-    model?: string;
-    hasImage?: boolean;
-    hasVideo?: boolean;
-}
+export type ResolveInteractionQuery = z.infer<typeof ResolveInteractionQuerySchema>;
 
 export type InCodePrompt = z.infer<typeof InCodePromptSchema>;
 export type InCodeInteraction = z.infer<typeof InCodeInteractionSchema>;

package/src/principal-context.ts

@@ -1,23 +1,33 @@
 import type { z } from 'zod';
-import type { PrincipalContextFromSchema, PrincipalIdentitySchema } from './api-schemas/user.js';
+import type { AbacPrincipalContextFromSchema, PrincipalIdentitySchema } from './api-schemas/user.js';
 
 /**
- * Resolved per-user context consumed by PrincipalSet condition evaluation
- * (`matchConditions` / `resolveConditions`) and by ABAC client-side tooling.
+ * The resolved principal context matched by ResourceSet/PrincipalSet condition evaluation
+ * (`resolveConditions` / `matchConditions`) and offered by the UI condition editor. Every field is
+ * referenceable in a rule as `$principal.<field>`: the principal `kind`, its `id`, and the merged
+ * BLP attributes (clearance, compartments, email, tags, properties).
  *
- * Mirrors what the token server builds for `$principal.*` resolution at JWT
- * issue time, with the same defaults (clearance = 0, compartments = [],
- * tags = [], properties = {}). Lives in @vertesia/common so both server-side
- * builders and client-side consumers share the exact same shape.
+ * This is the single shape the token server writes into the JWT for `$principal.*` resolution at
+ * issue time, and the shared `buildPrincipalContext` in @vertesia/studio-utils produces — with the
+ * defaults that keep condition operators well-defined for absent values (clearance = 0,
+ * compartments = [], tags = [], properties = {}, id = '', email = '').
  *
- * Derived from `PrincipalContextSchema`, which is composed into `PrincipalIdentitySchema` rather
- * than published as a component of its own — the document has never carried a `PrincipalContext`
+ * Derived from `AbacPrincipalContextSchema`, which is composed into `PrincipalIdentitySchema` rather
+ * than published as a component of its own — the document has never carried an `AbacPrincipalContext`
  * schema, and inventing one would add a `$ref` to every generated client.
  */
-export type PrincipalContext = PrincipalContextFromSchema;
+export type AbacPrincipalContext = AbacPrincipalContextFromSchema;
 
 /**
- * Response shape of the `/iam/users/identity` endpoint. Derived from `PrincipalIdentitySchema`,
- * where its published description lives — Zod reads `.meta()`, not TSDoc.
+ * The principal subject kind. A resolvable field of {@link AbacPrincipalContext}, so rules may match
+ * on `$principal.kind`.
+ */
+export type PrincipalKind = AbacPrincipalContext['kind'];
+
+/**
+ * Response shape of the `/iam/users/identity` endpoint. Extends {@link AbacPrincipalContext} with
+ * identity-only fields (none today) — the invariant is that the ABAC context is always a subset of
+ * the identity, so a field added here never widens the `$principal.*` surface. Derived from
+ * `PrincipalIdentitySchema`, where its published description lives — Zod reads `.meta()`, not TSDoc.
  */
 export type PrincipalIdentity = z.infer<typeof PrincipalIdentitySchema>;

package/src/project-values.ts

@@ -24,6 +24,7 @@ export enum ResourceVisibility {
 export enum SystemRoles {
     owner = 'owner', // all permissions
     admin = 'admin', // all permissions
+    app_admin = 'app_admin', // all permissions but studio:access — admin driving a custom admin UI
     manager = 'manager', // all permissions but manage_account, manage_billing
     developer = 'developer', // all permissions but manage_account, manage_billing, manage_roles, delete
     application = 'application', // executor + request_pk