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

package/src/api-schemas/api-discriminators.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import { type ApiComponentName, ApiSchemaComponents, validateApiResponse } from './registry.js';
+
+/**
+ * The build-time half of `discriminator: true`.
+ *
+ * AJV applies its discriminator rules when it COMPILES a schema, not when it validates one, and it
+ * signals a union it cannot handle by throwing. Left unchecked that turns into a 500 on the first
+ * request to whichever endpoint publishes the offending component — a failure mode that depends on
+ * traffic and would reach a deployed environment before anyone saw it. Compiling every registered
+ * component here moves that to the build, and names the component when it happens.
+ *
+ * The rules a union has to satisfy, all of which `synthesizeDiscriminator` in the adapter already
+ * enforces before emitting a discriminator: `oneOf` members resolving to object schemas, a tag
+ * property present and REQUIRED in every branch, and a `const` or single-valued `enum` for the tag
+ * in each. A hand-written `.meta({ discriminator })` gets no such check when it is written, which
+ * is the case this test exists for.
+ *
+ * Generating a validator for each of the ~1000 components is real work: well under a second on a
+ * developer machine, ~8s on a loaded CI runner, past vitest's 5s default, hence the explicit budget
+ * below. It is generous on purpose — an unsupported discriminator makes AJV THROW during
+ * compilation, so a genuine regression is caught by the try/catch and never by the clock.
+ */
+const COMPILE_ALL_TIMEOUT_MS = 60_000;
+
+describe('published discriminators', () => {
+    it(
+        'compiles every registered component under AJV discriminator support',
+        () => {
+            const failures: string[] = [];
+            for (const name of Object.keys(ApiSchemaComponents)) {
+                try {
+                    // Compilation is the subject; the value only has to reach the validator. An
+                    // invalid result is expected and irrelevant.
+                    validateApiResponse(name as ApiComponentName, undefined);
+                } catch (err: unknown) {
+                    failures.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            expect(failures, `components AJV could not compile:\n${failures.join('\n')}`).toEqual([]);
+        },
+        COMPILE_ALL_TIMEOUT_MS,
+    );
+
+    it('keeps discriminator mapping in the published components for generated clients', () => {
+        // AJV's copy drops `mapping`; the OpenAPI document must not. A Java or Go client reads the
+        // mapping to pick a concrete subtype, so losing it here would be a silent codegen
+        // regression that no schema assertion elsewhere would catch.
+        const union = ApiSchemaComponents.ToolCollectionObject as {
+            discriminator?: { propertyName?: string; mapping?: Record<string, string> };
+        };
+        expect(union.discriminator?.propertyName).toBe('type');
+        expect(union.discriminator?.mapping).toMatchObject({
+            mcp: '#/components/schemas/MCPToolCollectionObject',
+        });
+    });
+
+    it('reports only the tagged branch when a legacy MCP collection is missing its id', () => {
+        // The `hubspot-mcp-dev` shape: created before the write path required `id`, still served by
+        // the five-level resolution chain in fetch-tools.ts. Without discriminator support AJV also
+        // reported `oauth_app` as an undeclared property and `type` as not matching a constant —
+        // both from the vertesia_sdk branch this value never claimed to be.
+        const legacy = {
+            type: 'mcp',
+            name: 'HubSpot',
+            namespace: 'hubspot',
+            description: 'HubSpot MCP',
+            auth: 'oauth',
+            url: 'https://mcp.hubspot.com',
+            oauth_app: 'hubspot',
+        };
+        const result = validateApiResponse('ToolCollectionObject', legacy);
+        expect(result.valid).toBe(false);
+        if (result.valid) return;
+        expect(result.errors).toEqual(["/ must have required property 'id'"]);
+    });
+
+    it('rejects a value whose tag names no branch', () => {
+        const result = validateApiResponse('ToolCollectionObject', { type: 'nonesuch', url: 'https://example.com' });
+        expect(result.valid).toBe(false);
+        if (result.valid) return;
+        expect(result.errors.join('; ')).toContain('tag');
+    });
+});

package/src/api-schemas/app-delete-summary.contract.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import type { AppDeleteSummary } from '../apps.js';
+import { AppDeleteSummarySchema } from './app-lifecycle.js';
+import { validateApiResponse } from './registry.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;
+function assertType<T extends true>(_ok: T): void {}
+
+/**
+ * `DeleteApp` published `CountResult` while returning this shape. Response validation therefore
+ * reported a missing `count` and every field below as unexpected — and where the check fails closed
+ * (local development) that surfaced as a 500 raised AFTER the app had already been deleted, which is
+ * the worst possible moment for it. These assertions pin the component to what the handler builds.
+ */
+const REAL_SUMMARY: AppDeleteSummary = {
+    confirmed: true,
+    app_id: '68b1779130afe5403a1589bc',
+    app_name: 'acme-app',
+    versions: 2,
+    installations: 1,
+    storage_prefix: 'apps/acme-app',
+    deleted: true,
+    warnings: [],
+};
+
+describe('AppDeleteSummary — as the DeleteApp response is validated', () => {
+    it('accepts what the handler returns after a confirmed delete', () => {
+        expect(validateApiResponse('AppDeleteSummary', REAL_SUMMARY).valid).toBe(true);
+    });
+
+    it('accepts the dry-run preview, which is the same shape with deleted: false', () => {
+        const preview = { ...REAL_SUMMARY, confirmed: false, deleted: false };
+        expect(validateApiResponse('AppDeleteSummary', preview).valid).toBe(true);
+    });
+
+    it('accepts a git-backed app, whose summary carries the repo URL', () => {
+        const withRepo = { ...REAL_SUMMARY, git_repo_url: 'https://git.example.com/acme/acme-app.git' };
+        expect(validateApiResponse('AppDeleteSummary', withRepo).valid).toBe(true);
+    });
+
+    it('accepts the warnings a partially-degraded cascade collects', () => {
+        const warned = {
+            ...REAL_SUMMARY,
+            warnings: ['git repo delete failed: 502', 'version cleanup failed: timeout'],
+        };
+        expect(validateApiResponse('AppDeleteSummary', warned).valid).toBe(true);
+    });
+
+    it('is NOT interchangeable with CountResult, the component this endpoint used to publish', () => {
+        // The regression in one line: neither validates as the other, so the mismatch was total.
+        expect(validateApiResponse('CountResult', REAL_SUMMARY).valid).toBe(false);
+        expect(validateApiResponse('AppDeleteSummary', { count: 1 }).valid).toBe(false);
+    });
+
+    it('rejects an undeclared field, so the component cannot silently drift from the handler', () => {
+        expect(validateApiResponse('AppDeleteSummary', { ...REAL_SUMMARY, secrets_purged: 3 }).valid).toBe(false);
+    });
+
+    it('keeps the public type derived from the schema rather than hand-written beside it', () => {
+        assertType<Equals<AppDeleteSummary, ReturnType<typeof AppDeleteSummarySchema.parse>>>(true);
+        // Every field the handler always sets is required; only git_repo_url is optional.
+        expect(AppDeleteSummarySchema.safeParse({ ...REAL_SUMMARY, warnings: undefined }).success).toBe(false);
+        const { git_repo_url: _omitted, ...withoutRepo } = { ...REAL_SUMMARY, git_repo_url: 'https://x' };
+        expect(AppDeleteSummarySchema.safeParse(withoutRepo).success).toBe(true);
+    });
+});

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

@@ -180,6 +180,8 @@ export const AppPackageScopeSchema = z
         'settings',
         'widgets',
         'activities',
+        'hooks',
+        'subscriptions',
         'all',
     ])
     .meta({ id: 'AppPackageScope' });
@@ -324,6 +326,35 @@ export const DeleteAppVersionResponseSchema = z
     })
     .meta({ id: 'DeleteAppVersionResponse' });
 
+export const AppDeleteSummarySchema = z
+    .strictObject({
+        confirmed: z.boolean().meta({
+            description:
+                'Whether `?confirm=true` was sent. Without it the endpoint reports what WOULD be removed and ' +
+                'deletes nothing — `deleted` stays false.',
+        }),
+        app_id: z.string(),
+        app_name: z.string(),
+        versions: z.number().meta({ description: 'AppVersion records the cascade covers.' }),
+        installations: z.number().meta({ description: 'AppInstallation records the cascade covers.' }),
+        storage_prefix: z.string(),
+        git_repo_url: z.string().optional(),
+        deleted: z.boolean().meta({
+            description: 'Whether the app record itself was removed. False for a dry run.',
+        }),
+        warnings: z.array(z.string()).meta({
+            description:
+                'Cascade steps that failed without aborting the deletion. Credential cleanup is NOT among them — ' +
+                'a failed API key purge fails the request outright and keeps the app row.',
+        }),
+    })
+    .meta({
+        id: 'AppDeleteSummary',
+        description:
+            'Result of `DELETE /apps/:id`. Doubles as the dry-run preview: without `?confirm=true` the same ' +
+            'shape comes back with `deleted: false` describing what the cascade would remove.',
+    });
+
 export const AppRepoBranchSchema = z
     .strictObject({
         name: z.string(),
@@ -469,6 +500,28 @@ export const OAuthClientCredentialsMapSchema = z
 
 export const AppOAuthCollectionParamsSchema = OAuthClientCredentialsMapSchema.meta({ id: 'AppOAuthCollectionParams' });
 
+export const McpApiKeyCredentialSchema = z
+    .strictObject({
+        // Matches SetMcpApiKeyRequest, including the `\S` pattern — see the note there on why the
+        // trim alone does not survive into the AJV-enforced JSON Schema.
+        api_key: z
+            .string()
+            .trim()
+            .min(1)
+            .regex(/\S/, 'API key must not be blank')
+            .meta({
+                description:
+                    'The key the installer holds for this collection. Surrounding whitespace is stripped. Stored ' +
+                    'encrypted in the installing project and never returned.',
+            }),
+    })
+    .meta({ id: 'McpApiKeyCredential' });
+
+export const AppApiKeyCollectionParamsSchema = z
+    .object({})
+    .catchall(McpApiKeyCredentialSchema)
+    .meta({ id: 'AppApiKeyCollectionParams' });
+
 export const AppInspectionIssueSchema = z
     .strictObject({
         severity: z.enum(['error', 'warning']),
@@ -775,6 +828,12 @@ export const AppInstallationPayloadSchema = z
             description:
                 'OAuth credentials for named providers, keyed by the provider key from oauth_providers. Collected from the user at install time for providers with required_at_install. Separate from oauth_params to avoid key collisions between provider keys and collection ids.',
         }).optional(),
+        api_key_params: AppApiKeyCollectionParamsSchema.meta({
+            description:
+                "API keys for auth: 'api_key' collections, keyed by collection.id. Collected from the user at " +
+                'install time for collections with api_key_config.required_at_install. Each key is stored in the ' +
+                "installing project's encrypted secret store, replacing any key already held for that collection.",
+        }).optional(),
     })
     .meta({ id: 'AppInstallationPayload' });
 

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

@@ -3,12 +3,15 @@
 import type { JSONSchema } from '@llumiverse/common';
 import { z } from 'zod';
 import type { CompositeAppMenuNavItem } from '../apps.js';
+import type { PlatformEvent } from '../platform-event.js';
 import type { InCodeProcessDefinition } from '../store/process.js';
+import { SystemRolesSchema } from './apikey.js';
 import {
     AgentToolDefinitionSchema,
     AppInstallationOAuthBindingSchema,
     AppInstallationProviderBindingSchema,
     AppVersionRecordSchema,
+    EventRefSchema,
 } from './app-lifecycle.js';
 import {
     AppAccessControlSchema,
@@ -19,12 +22,14 @@ import {
     MCPOAuthConfigSchema,
     ToolCollectionObjectSchema,
 } from './apps.js';
+import { AuditMeterSchema } from './audit-trail.js';
 import {
     DashboardDataSourceSchema,
     DashboardLayoutSchema,
     DashboardPanelSchema,
     DashboardQuerySchema,
 } from './dashboard.js';
+import { EventPrioritySchema, EventSubscriptionFilterSchema } from './events.js';
 import { StringValueMapSchema } from './files.js';
 import { RemoteActivityDefinitionSchema } from './integrations.js';
 import { CatalogInteractionRefSchema } from './interaction.js';
@@ -804,6 +809,99 @@ export const CompositeAppConfigSchema = z
             'CompositeApp shell configuration. This is the main configuration interface for storing CompositeApp settings. Used as the MongoDB model for persisting CompositeApp configurations.',
     });
 
+export const AppPackageEventHookSchema = z
+    .strictObject({
+        name: z.string().meta({ description: 'Registered event hook name.' }),
+        path: z.string().meta({ description: 'Authenticated endpoint that receives the event delivery envelope.' }),
+        description: z.string().meta({ description: 'Optional description of the event hook behavior.' }).optional(),
+    })
+    .meta({
+        id: 'AppPackageEventHook',
+        description: 'An authenticated event hook exposed by the app runtime.',
+    });
+
+export const AppPackageHooksSchema = z
+    .strictObject({
+        install: z.string().meta({ description: 'Authenticated endpoint for the app install hook.' }).optional(),
+        uninstall: z.string().meta({ description: 'Authenticated endpoint for the app uninstall hook.' }).optional(),
+        events: z
+            .array(AppPackageEventHookSchema)
+            .meta({ description: 'Named event hooks exposed by the app runtime.' })
+            .optional(),
+    })
+    .meta({
+        id: 'AppPackageHooks',
+        description:
+            'Lifecycle and event hooks exposed by the app runtime. Lifecycle entries are informational; Studio invokes their conventional sibling endpoints directly.',
+    });
+
+const AppEventHookPlatformEventSchema = EventRefSchema.extend({
+    timestamp: z.string(),
+    source: z.string(),
+    audit_trail: z.boolean().optional(),
+    replay_of: z.string().optional(),
+    replay_root_event_id: z.string().optional(),
+    replayed_by: z.string().optional(),
+    request_id: z.string().nullable().optional(),
+    status: z.number().optional(),
+    success: z.boolean().optional(),
+    principal_id: z.string().nullable().optional(),
+    principal_type: z.string().nullable().optional(),
+    effective_principal_id: z.string().nullable().optional(),
+    roles: z.array(z.string()).optional(),
+    account_name: z.string().nullable().optional(),
+    project_name: z.string().nullable().optional(),
+    provider: z.string().nullable().optional(),
+    meters: z.array(AuditMeterSchema).optional(),
+    resource_data: z.record(z.string(), z.unknown()).optional(),
+    resource_version: z.string().optional(),
+    details: z.record(z.string(), z.unknown()).optional(),
+}) satisfies z.ZodType<PlatformEvent>;
+
+export const AppEventHookDeliverySchema = z
+    .strictObject({
+        id: z.string().meta({ description: 'Event-delivery intent id.' }),
+        subscription_id: z.string().meta({ description: 'Event subscription id.' }),
+        attempt: z.number().finite().meta({ description: 'Current delivery attempt number.' }),
+    })
+    .meta({
+        id: 'AppEventHookDelivery',
+        description: 'Delivery metadata accompanying an app event-hook invocation.',
+    });
+
+export const AppEventHookPayloadSchema = z
+    .strictObject({
+        event: AppEventHookPlatformEventSchema,
+        delivery: AppEventHookDeliverySchema,
+    })
+    .meta({
+        id: 'AppEventHookPayload',
+        description: 'Canonical platform event envelope delivered to an authenticated app event hook.',
+    });
+
+export const AppEventSubscriptionDefinitionSchema = z
+    .strictObject({
+        id: z
+            .string()
+            .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+            .meta({ description: 'Stable app-local subscription id in kebab case.' }),
+        name: z.string().meta({ description: 'Human-readable subscription name.' }),
+        description: z.string().meta({ description: 'Optional description of the subscription behavior.' }).optional(),
+        hook: z.string().meta({ description: 'Name of an event hook registered by the same app package.' }),
+        filter: EventSubscriptionFilterSchema,
+        run_as_role: SystemRolesSchema.meta({
+            description:
+                'Identity used for event delivery. Use automation for the standard event-triggered execution identity.',
+        }),
+        enabled: z.boolean().meta({ description: 'Whether the installed subscription is enabled.' }).optional(),
+        priority: EventPrioritySchema.meta({ description: 'Delivery priority for matching events.' }).optional(),
+    })
+    .meta({
+        id: 'AppEventSubscriptionDefinition',
+        description:
+            'An app-owned event subscription. Studio derives its project scope and delivery target from the app installation and referenced event hook.',
+    });
+
 export const AppPackageSchema = z
     .strictObject({
         ui: AppUIConfigSchema.meta({ description: 'The UI configuration of the app' }).optional(),
@@ -850,6 +948,11 @@ export const AppPackageSchema = z
         settings_schema: JSONSchemaRefSchema.meta({
             description: 'A JSON chema for the app installation settings.',
         }).optional(),
+        hooks: AppPackageHooksSchema.optional(),
+        subscriptions: z
+            .array(AppEventSubscriptionDefinitionSchema)
+            .meta({ description: 'Event subscriptions contributed by the app.' })
+            .optional(),
     })
     .meta({ id: 'AppPackage' });
 

package/src/api-schemas/apps.ts

@@ -112,9 +112,13 @@ export const AppUIConfigSchema = z
     })
     .meta({ id: 'AppUIConfig' });
 
-export const ToolCollectionAuthTypeSchema = z
-    .enum(['oauth', 'other'])
-    .meta({ id: 'ToolCollectionAuthType', description: 'Authentication type for tool collections' });
+export const ToolCollectionAuthTypeSchema = z.enum(['oauth', 'api_key', 'other']).meta({
+    id: 'ToolCollectionAuthType',
+    description:
+        "Authentication type for tool 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>`)',
+});
 
 export const MCPOAuthConfigSchema = z
     .strictObject({
@@ -162,6 +166,33 @@ export const MCPOAuthConfigSchema = z
             'oauth_bindings on AppInstallation.',
     });
 
+export const MCPApiKeyConfigSchema = z
+    .strictObject({
+        required_at_install: z
+            .boolean()
+            .optional()
+            .meta({
+                description:
+                    'When true, the installer must supply the key in the install dialog. Use this for a manifest ' +
+                    'published to projects that each hold their own key. Leave unset when the key was already ' +
+                    'stored by whoever registered the server.',
+            }),
+        instructions: z
+            .string()
+            .optional()
+            .meta({
+                description:
+                    'Shown in the install dialog above the key field — typically where to generate the key on the ' +
+                    'remote service.',
+            }),
+    })
+    .meta({
+        id: 'MCPApiKeyConfig',
+        description:
+            "Install-time provisioning blueprint for an `auth: 'api_key'` MCP collection. Declares whether the " +
+            'installer is prompted for the key. Never holds the key itself — manifests are shareable documents.',
+    });
+
 /**
  * The two collection kinds share a base interface, so their published components both begin with
  * `url` and `auth`. Spreading one shape is what keeps that true of the emission as well.
@@ -211,6 +242,11 @@ export const MCPToolCollectionObjectSchema = z
                 'required_at_install params. The created app is recorded in AppInstallation.oauth_bindings. ' +
                 'Mutually exclusive with oauth_provider.',
         }),
+        api_key_config: MCPApiKeyConfigSchema.optional().meta({
+            description:
+                "Install-time provisioning blueprint for auth: 'api_key' collections. Only meaningful alongside " +
+                "auth: 'api_key'; ignored otherwise.",
+        }),
         oauth_provider: z
             .string()
             .optional()
@@ -371,6 +407,39 @@ export const McpOAuthTokenRequestSchema = z
     })
     .meta({ id: 'McpOAuthTokenRequest' });
 
+export const SetMcpApiKeyRequestSchema = z
+    .strictObject({
+        // `.regex(/\S/)` rather than `.trim().min(1)` alone: request bodies are validated by AJV
+        // against the EMITTED JSON Schema, where a Zod transform like `.trim()` leaves no trace —
+        // `minLength: 1` on its own happily accepts "   ". The pattern emits and is enforced, so a
+        // whitespace-only key is rejected at the boundary instead of becoming an encrypted empty
+        // key that still reports `configured: true`. The trim still normalizes for Zod consumers.
+        api_key: z
+            .string()
+            .trim()
+            .min(1)
+            .regex(/\S/, 'API key must not be blank')
+            .meta({
+                description:
+                    'The static key issued by the remote MCP server. Surrounding whitespace is stripped. Stored ' +
+                    'encrypted in the project secret store and sent as the RFC 6750 bearer token on every request ' +
+                    'to the collection URL. Never returned by the API.',
+            }),
+    })
+    .meta({ id: 'SetMcpApiKeyRequest' });
+
+export const McpApiKeyStatusSchema = z
+    .strictObject({
+        configured: z.boolean().meta({ description: 'Whether a key is stored for this collection.' }),
+        // Always present — null when unset, never absent. `.nullable()` rather than `.nullish()`
+        // so the published contract says so and generated clients do not treat it as optional.
+        hint: z
+            .string()
+            .nullable()
+            .meta({ description: 'Last few characters of the stored key, for display only. Null when unset.' }),
+    })
+    .meta({ id: 'McpApiKeyStatus', description: 'Whether an API key is configured for an MCP tool collection' });
+
 export const OAuthAuthStatusSchema = z
     .strictObject({
         collection_id: z.string(),

package/src/api-schemas/content.ts

@@ -787,6 +787,19 @@ export const ContentObjectApiResponseSchema = z
         parts_etag: z.string().optional(),
         transcript: z.looseObject({}).optional(),
         security: StringArrayMapSchema.optional(),
+        sensitivity: z
+            .number()
+            .meta({
+                description:
+                    'BLP sensitivity level — set directly or inherited from collections (max across collections).',
+            })
+            .optional(),
+        compartments: z
+            .array(z.string())
+            .meta({
+                description: 'Compartments — set directly or inherited from collections (union across collections).',
+            })
+            .optional(),
         inherited_properties: z.array(InheritedPropertyMetadataSchema).optional(),
     })
     .meta({ id: 'ContentObjectApiResponse' });

package/src/api-schemas/events.ts

@@ -184,6 +184,17 @@ export const WebhookEventDeliveryTargetSchema = z
     })
     .meta({ id: 'WebhookEventDeliveryTarget' });
 
+export const AppEventDeliveryTargetSchema = z
+    .strictObject({
+        type: z.literal('app'),
+        app_id: z.string(),
+        installation_id: z.string(),
+        hook: z.string(),
+        url: z.string(),
+        timeout_ms: z.number().optional(),
+    })
+    .meta({ id: 'AppEventDeliveryTarget' });
+
 export const WorkflowEventDeliveryTargetSchema = z
     .strictObject({
         type: z.literal('workflow'),
@@ -432,6 +443,17 @@ export const WebhookEventDeliveryTargetInputSchema = z
     })
     .meta({ id: 'WebhookEventDeliveryTargetInput' });
 
+export const AppEventDeliveryTargetInputSchema = z
+    .strictObject({
+        type: z.literal('app'),
+        app_id: z.string(),
+        installation_id: z.string(),
+        hook: z.string(),
+        url: z.string(),
+        timeout_ms: z.number().optional(),
+    })
+    .meta({ id: 'AppEventDeliveryTargetInput' });
+
 export const WorkflowEventDeliveryTargetInputSchema = z
     .strictObject({
         type: z.literal('workflow'),
@@ -615,7 +637,7 @@ export const EventDeliveryQueueSubscriptionSummarySchema = z
     .strictObject({
         subscription_id: z.string(),
         subscription_name: z.string(),
-        target_type: z.enum(['workflow', 'webhook', 'agent', 'process']),
+        target_type: z.enum(['workflow', 'webhook', 'app', 'agent', 'process']),
         total: z.number(),
         queued: z.number(),
         deferred: z.number(),
@@ -632,12 +654,45 @@ export const EventDeliveryQueueSubscriptionSummarySchema = z
 export const EventDeliveryQueueSummaryPayloadSchema = z
     .strictObject({
         subscription_id: z.string().optional(),
-        target_type: z.array(z.enum(['workflow', 'webhook', 'agent', 'process'])).optional(),
+        target_type: z.array(z.enum(['workflow', 'webhook', 'app', 'agent', 'process'])).optional(),
         sort_by: EventDeliveryQueueSortFieldSchema.optional(),
         sort_order: z.enum(['asc', 'desc']).optional(),
     })
     .meta({ id: 'EventDeliveryQueueSummaryPayload' });
 
+export const CancelEventDeliveryIntentsPayloadSchema = z
+    .strictObject({
+        subscription_id: z
+            .string()
+            .min(1)
+            .meta({ description: 'Restrict cancellation to one subscription.' })
+            .optional(),
+        target_type: z
+            .array(z.enum(['workflow', 'webhook', 'app', 'agent', 'process']))
+            .min(1)
+            .meta({ description: 'Restrict cancellation to one or more delivery target types.' })
+            .optional(),
+    })
+    .meta({ id: 'CancelEventDeliveryIntentsPayload' });
+
+export const CancelEventDeliveryIntentsResponseSchema = z
+    .strictObject({
+        environment: z.string().meta({ description: 'Deployment environment whose queue was changed.' }),
+        cleared_through: z.string().meta({
+            description: 'Server-side watermark; intents created after this time were not changed.',
+            format: 'date-time',
+        }),
+        cancelled: z
+            .number()
+            .int()
+            .nonnegative()
+            .meta({ description: 'Pending or retrying intents moved to the cancelled terminal state.' }),
+        active_untouched: z.number().int().nonnegative().meta({
+            description: 'Matching evaluating, starting, or running intents left for normal reconciliation.',
+        }),
+    })
+    .meta({ id: 'CancelEventDeliveryIntentsResponse' });
+
 export const EventIngestChannelMutationResponseSchema = z
     .strictObject({
         channel: EventIngestChannelSchema,
@@ -724,7 +779,7 @@ export const EventDeliveryIntentSummarySchema = z
         event_id: z.string(),
         subscription_id: z.string(),
         subscription_name: z.string(),
-        target_type: z.enum(['workflow', 'webhook', 'agent', 'process']),
+        target_type: z.enum(['workflow', 'webhook', 'app', 'agent', 'process']),
         workflow_class: nullableStringSchema.optional(),
         priority: EventPrioritySchema,
         status: EventDeliveryIntentStatusSchema,
@@ -812,6 +867,7 @@ export const EventDeliveryTargetSchema: z.ZodType = z
     .discriminatedUnion('type', [
         WorkflowEventDeliveryTargetSchema,
         WebhookEventDeliveryTargetSchema,
+        AppEventDeliveryTargetSchema,
         AgentEventDeliveryTargetSchema,
         z.lazy(() => ProcessEventDeliveryTargetSchema) as unknown as z.ZodObject,
     ])
@@ -821,6 +877,7 @@ export const EventDeliveryTargetInputSchema: z.ZodType = z
     .discriminatedUnion('type', [
         WorkflowEventDeliveryTargetInputSchema,
         WebhookEventDeliveryTargetInputSchema,
+        AppEventDeliveryTargetInputSchema,
         AgentEventDeliveryTargetSchema,
         z.lazy(() => ProcessEventDeliveryTargetSchema) as unknown as z.ZodObject,
     ])
@@ -841,6 +898,9 @@ export const EventSubscriptionSchema: z.ZodType = z
         protected: z.boolean(),
         enabled: z.boolean(),
         priority: EventPrioritySchema.optional(),
+        app_installation_id: z.string().optional(),
+        app_id: z.string().optional(),
+        app_subscription_id: z.string().optional(),
         created_by: z.string().optional(),
         updated_by: z.string().optional(),
         created_at: z.string().optional(),

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

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import type { AsyncConversationExecutionPayload } from '../interaction.js';
+import { AsyncConversationExecutionPayloadSchema } from './interaction.js';
+
+describe('AsyncConversationExecutionPayload contract', () => {
+    it('retains an immutable app-version execution target', () => {
+        const payload: AsyncConversationExecutionPayload = {
+            type: 'conversation',
+            interaction: 'sys:AppTester',
+            app_version: '20260804T022611971Z',
+        };
+
+        expect(AsyncConversationExecutionPayloadSchema.parse(payload)).toMatchObject({
+            app_version: '20260804T022611971Z',
+        });
+    });
+
+    it('rejects a non-string app-version target', () => {
+        expect(() =>
+            AsyncConversationExecutionPayloadSchema.parse({
+                type: 'conversation',
+                interaction: 'sys:AppTester',
+                app_version: 42,
+            }),
+        ).toThrow();
+    });
+});

package/src/api-schemas/interaction.ts

@@ -1996,6 +1996,13 @@ export const AsyncConversationExecutionPayloadSchema = z
             description:
                 'The interaction name and suffixed by an optional tag or version separated from the name using a @ character If no version/tag part is specified then the latest version is used. Example: ReviewContract, ReviewContract@draft, ReviewContract@1, ReviewContract@some-tag',
         }),
+        app_version: z
+            .string()
+            .meta({
+                description:
+                    'Immutable app-version target inherited by this conversation execution. The workflow applies it to app-owned resource resolution; callers normally set the x-vertesia-app-version header instead of populating this field directly.',
+            })
+            .optional(),
         data: z
             .unknown()
             .meta({