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

package/src/api-schemas/pruning-limits.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest';
+import { findUnprunablePaths, pruneToSchema, toOpenApiComponents } from './adapter.js';
+import { findUnprunableApiPaths } from './registry.js';
+
+/**
+ * Pins the shapes where pruning declines to narrow.
+ *
+ * These are limitations, not bugs: guessing which branch of an ambiguous schema applies risks
+ * deleting legitimate data. They are pinned here so the boundary is explicit and cannot be
+ * mistaken for a secret-removal guarantee — anything sensitive needs an explicit response mapper
+ * or a request/response type split.
+ */
+describe('shapes where pruning passes values through untouched', () => {
+    const SENSITIVE = { a: 'x', stripe_secret: 'sk_live_leak' };
+
+    it('an allOf intersection is not pruned', () => {
+        const components = toOpenApiComponents({
+            Merged: { allOf: [{ type: 'object', properties: { a: { type: 'string' } } }] },
+        });
+        expect(pruneToSchema(SENSITIVE, { $ref: '#/components/schemas/Merged' }, components)).toEqual(SENSITIVE);
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Merged' }, components)).toEqual([' (allOf)']);
+    });
+
+    it('a union without a discriminator is not pruned', () => {
+        const components = toOpenApiComponents({
+            Loose: {
+                anyOf: [
+                    { type: 'object', properties: { a: { type: 'string' } } },
+                    { type: 'object', properties: { b: { type: 'string' } } },
+                ],
+            },
+        });
+        expect(pruneToSchema(SENSITIVE, { $ref: '#/components/schemas/Loose' }, components)).toEqual(SENSITIVE);
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Loose' }, components)).toEqual([
+            ' (union without discriminator)',
+        ]);
+    });
+
+    it('a discriminator value with no mapping entry is not pruned', () => {
+        const components = toOpenApiComponents({
+            Union: {
+                anyOf: [{ $ref: '#/$defs/A' }, { $ref: '#/$defs/B' }],
+                $defs: {
+                    A: { type: 'object', properties: { kind: { const: 'a' } }, required: ['kind'] },
+                    B: { type: 'object', properties: { kind: { const: 'b' } }, required: ['kind'] },
+                },
+            },
+        });
+        const unknownBranch = { kind: 'c', stripe_secret: 'sk_live_leak' };
+        expect(pruneToSchema(unknownBranch, { $ref: '#/components/schemas/Union' }, components)).toEqual(unknownBranch);
+    });
+
+    it('an unresolvable reference is not pruned', () => {
+        expect(pruneToSchema(SENSITIVE, { $ref: '#/components/schemas/Absent' }, {})).toEqual(SENSITIVE);
+    });
+
+    it('patternProperties is not pruned — its keys are declared but absent from `properties`', () => {
+        const components = toOpenApiComponents({
+            Headers: {
+                type: 'object',
+                properties: { a: { type: 'string' } },
+                patternProperties: { '^x-': { type: 'string' } },
+            },
+        });
+        const payload = { a: 'x', 'x-trace': 'declared-by-pattern', stripe_secret: 'sk_live_leak' };
+        expect(pruneToSchema(payload, { $ref: '#/components/schemas/Headers' }, components)).toEqual(payload);
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Headers' }, components)).toEqual([
+            ' (patternProperties)',
+        ]);
+    });
+
+    it('prefixItems is not pruned — tuple positions have their own schemas', () => {
+        const components = toOpenApiComponents({
+            Pair: { type: 'array', prefixItems: [{ type: 'string' }, { type: 'object' }] },
+        });
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Pair' }, components)).toEqual([' (prefixItems)']);
+    });
+
+    it('a non-composable sibling further down a reference chain is not pruned', () => {
+        // The sibling sits on the alias, not on the node being pruned, so it is only visible once
+        // the chain is followed. Reporting it as an unresolved reference would send someone
+        // looking for a missing component that exists.
+        const components = toOpenApiComponents({
+            Alias: { $ref: '#/components/schemas/Closed', additionalProperties: true },
+            Closed: { type: 'object', properties: { a: { type: 'string' } }, additionalProperties: false },
+        });
+        const ref = { $ref: '#/components/schemas/Alias' };
+        expect(pruneToSchema(SENSITIVE, ref, components)).toEqual(SENSITIVE);
+        expect(findUnprunablePaths(ref, components)).toEqual([
+            ' ($ref with unsupported sibling: additionalProperties)',
+        ]);
+    });
+
+    it('a reference chain that cycles is not pruned', () => {
+        // Mutual aliases never reach a schema describing an object, so there is nothing to narrow
+        // against. Following them would loop forever.
+        const components = toOpenApiComponents({
+            Ping: { $ref: '#/components/schemas/Pong' },
+            Pong: { $ref: '#/components/schemas/Ping' },
+        });
+        const ref = { $ref: '#/components/schemas/Ping' };
+        expect(pruneToSchema(SENSITIVE, ref, components)).toEqual(SENSITIVE);
+        expect(findUnprunablePaths(ref, components)).toEqual([' (circular $ref)']);
+    });
+
+    it('a $ref with a non-composable sibling is not pruned', () => {
+        // Siblings apply conjunctively, so a sibling `additionalProperties: true` does NOT reopen
+        // a closed target. Composing that correctly is not something to guess at.
+        const components = toOpenApiComponents({
+            Wrapper: {
+                type: 'object',
+                properties: { inner: { $ref: '#/$defs/Closed', additionalProperties: true } },
+                $defs: {
+                    Closed: {
+                        type: 'object',
+                        properties: { a: { type: 'string' } },
+                        additionalProperties: false,
+                    },
+                },
+            },
+        });
+        const payload = { inner: { a: 'x', stripe_secret: 'sk_live_leak' } };
+        expect(pruneToSchema(payload, { $ref: '#/components/schemas/Wrapper' }, components)).toEqual(payload);
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Wrapper' }, components)).toEqual([
+            '/inner ($ref with unsupported sibling: additionalProperties)',
+        ]);
+    });
+});
+
+describe('findUnprunablePaths reports where a component is not closed', () => {
+    it('returns nothing for the fully prunable Account component', () => {
+        expect(findUnprunableApiPaths('Account')).toEqual([]);
+    });
+
+    it('returns nothing for the discriminated Stripe union', () => {
+        // A discriminated union IS prunable — the discriminator selects the branch.
+        expect(findUnprunableApiPaths('StripeBillingStatusResponse')).toEqual([]);
+    });
+
+    it('reports the path of a nested ambiguous schema', () => {
+        const components = toOpenApiComponents({
+            Outer: {
+                type: 'object',
+                properties: {
+                    payload: { allOf: [{ type: 'object', properties: { a: { type: 'string' } } }] },
+                    rows: {
+                        type: 'array',
+                        items: { anyOf: [{ type: 'object' }, { type: 'object', properties: {} }] },
+                    },
+                },
+            },
+        });
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Outer' }, components).sort()).toEqual([
+            '/payload (allOf)',
+            '/rows[] (union without discriminator)',
+        ]);
+    });
+
+    it('reports an ambiguous schema reached through a map value', () => {
+        // additionalProperties is the path every value in a Record<string, T> takes, so its
+        // limitations are the map's limitations.
+        const components = toOpenApiComponents({
+            Registry: {
+                type: 'object',
+                additionalProperties: { allOf: [{ type: 'object', properties: { a: { type: 'string' } } }] },
+            },
+        });
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Registry' }, components)).toEqual(['{} (allOf)']);
+    });
+
+    it('does not flag a scalar union expressed through references', () => {
+        // Every branch resolves to an enum, so there are no properties to narrow and the missing
+        // discriminator is irrelevant.
+        const components = toOpenApiComponents({
+            Choice: {
+                anyOf: [{ $ref: '#/$defs/Colour' }, { type: 'null' }],
+                $defs: { Colour: { type: 'string', enum: ['red', 'green'] } },
+            },
+        });
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Choice' }, components)).toEqual([]);
+    });
+
+    it('terminates on a recursive component', () => {
+        const components = toOpenApiComponents({
+            Node: { type: 'object', properties: { children: { type: 'array', items: { $ref: '#' } } } },
+        });
+        expect(findUnprunablePaths({ $ref: '#/components/schemas/Node' }, components)).toEqual([]);
+    });
+});

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

@@ -0,0 +1,147 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { describe, expect, it } from 'vitest';
+import type {
+    QuotaEffectiveTier,
+    QuotaStandingAdmissionClass,
+    QuotaStandingResource,
+    QuotaStandingResponse,
+    QuotaStandingWindow,
+    QuotaTierResponse,
+} from '../rate-limiter.js';
+import type { JsonObject } from './adapter.js';
+import { ApiSchemaComponents, apiComponentRef, 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 {}
+
+function compile(name: string, components: Readonly<Record<string, JsonObject>> = ApiSchemaComponents) {
+    const ajv = new Ajv2020({ strictSchema: false, allErrors: true });
+    ajv.addSchema({ $id: 'vertesia://openapi', components: { schemas: components } });
+    return ajv.compile({ $ref: `vertesia://openapi${apiComponentRef(name as never)}` });
+}
+
+const VALID_WINDOW = { limit: 600, used: 12, remaining: 588, window_ms: 60_000 };
+
+const VALID_STANDING = {
+    tenant_id: '1589ba_149d0b',
+    available: true,
+    base_tier: 'default',
+    effective_tier: 'enterprise',
+    api: [{ resource: 'objects', name: 'Content objects', burst: VALID_WINDOW, quota: VALID_WINDOW }],
+    admission: {
+        classes: [{ class: 'ExecuteConversationWorkflow', tenant_active: 3 }],
+        note: 'Budget is global and discovered.',
+    },
+    llm: { note: 'Shared per environment/model.' },
+};
+
+describe('gate 1 — the schema is the single source of truth for the public quota types', () => {
+    it('publishes the exact schema-derived type, not a hand-written twin', () => {
+        // The whole closure, not only the two types the endpoints return. A hand-written
+        // QuotaStandingWindow beside an inferred QuotaStandingResponse would leave the drift path
+        // open one level down, where it is harder to see.
+        expect(true).toBe(true);
+    });
+
+    it('resolves nested component references to concrete property types', () => {
+        // Schema-first only pays off if a $ref survives inference as the referenced type rather
+        // than degrading to `unknown` — that is what makes the SDK usable.
+        assertType<Equals<QuotaStandingResponse['api'], QuotaStandingResource[]>>(true);
+        assertType<Equals<QuotaStandingResource['burst'], QuotaStandingWindow>>(true);
+        assertType<Equals<QuotaStandingResponse['admission']['classes'], QuotaStandingAdmissionClass[]>>(true);
+        assertType<Equals<QuotaStandingResponse['effective_tier'], QuotaEffectiveTier>>(true);
+        assertType<Equals<QuotaTierResponse['tier'], QuotaEffectiveTier>>(true);
+        expect(true).toBe(true);
+    });
+
+    it('keeps every quota field required, as the published document declares', () => {
+        // `?:` on an inferred field is invisible at the call site until a consumer hits undefined.
+        // Identity above would catch a change here, but only by failing somewhere less obvious.
+        assertType<Equals<QuotaStandingResponse['available'], boolean>>(true);
+        assertType<Equals<QuotaStandingWindow['remaining'], number>>(true);
+        assertType<Equals<QuotaStandingResponse['llm'], { note: string }>>(true);
+        expect(true).toBe(true);
+    });
+});
+
+describe('gate 2 — the published components match the closure the types come from', () => {
+    it('hoists every id-bearing quota schema into its own component', () => {
+        // Six components for two endpoints: the registry must be self-contained, so a canonical
+        // component may not reference a TypeScript-derived one.
+        const quota = Object.keys(ApiSchemaComponents)
+            .filter((name) => name.startsWith('Quota'))
+            .sort();
+        expect(quota).toEqual([
+            'QuotaEffectiveTier',
+            'QuotaStandingAdmissionClass',
+            'QuotaStandingResource',
+            'QuotaStandingResponse',
+            'QuotaStandingWindow',
+            // QuotaTier is the account tier enum, converted with the account slice.
+            'QuotaTier',
+            'QuotaTierResponse',
+        ]);
+    });
+
+    it('shares one QuotaStandingWindow component across both referencing properties', () => {
+        // The literal pointer, not apiComponentRef: that helper only accepts registry entry names,
+        // and QuotaStandingWindow is a hoisted sub-component rather than a slot's contract.
+        const props = ApiSchemaComponents.QuotaStandingResource.properties as Record<string, JsonObject>;
+        expect(props.burst).toEqual({ $ref: '#/components/schemas/QuotaStandingWindow' });
+        expect(props.quota).toEqual({ $ref: '#/components/schemas/QuotaStandingWindow' });
+    });
+
+    it('keeps admission and llm anonymous, as the document publishes them', () => {
+        // Naming them would add a $ref the spec does not carry, changing the generated clients.
+        const props = ApiSchemaComponents.QuotaStandingResponse.properties as Record<string, JsonObject>;
+        expect(props.admission.$ref).toBeUndefined();
+        expect(props.admission.type).toBe('object');
+        expect(props.llm.$ref).toBeUndefined();
+        expect(Object.keys(ApiSchemaComponents)).not.toContain('QuotaStandingAdmission');
+    });
+});
+
+describe('gate 3 — AJV validates the same canonical objects that are published', () => {
+    it('accepts a full standing payload', () => {
+        expect(compile('QuotaStandingResponse')(VALID_STANDING)).toBe(true);
+        expect(compile('QuotaTierResponse')({ tier: 'enterprise' })).toBe(true);
+    });
+
+    it('rejects a missing required field', () => {
+        const { available: _dropped, ...incomplete } = VALID_STANDING;
+        expect(compile('QuotaStandingResponse')(incomplete)).toBe(false);
+    });
+
+    it('rejects a numeric window value sent as a string', () => {
+        // No coerceTypes: one AJV configuration serves bodies and responses, so a JSON number that
+        // arrives as text is a contract violation rather than something quietly repaired.
+        const bad = { ...VALID_WINDOW, used: '12' };
+        expect(compile('QuotaStandingWindow')(bad)).toBe(false);
+    });
+
+    it('closes the anonymous nested objects the strict policy reaches', () => {
+        const withExtra = { ...VALID_STANDING, llm: { note: 'x', rogue: 1 } };
+        expect(compile('QuotaStandingResponse')(withExtra)).toBe(false);
+    });
+});
+
+describe('gate 4 — the response path checks the same component the SDK types come from', () => {
+    it('accepts a conforming response and hands back the component type', () => {
+        const result = validateApiResponse('QuotaTierResponse', { tier: 'standard' });
+        expect(result.valid).toBe(true);
+        if (result.valid) {
+            assertType<Equals<typeof result.data, QuotaTierResponse>>(true);
+            expect(result.data.tier).toBe('standard');
+        }
+    });
+
+    it('reports a violation without mutating the payload', () => {
+        // Detection, not repair. Outside local development a response mismatch is logged drift, so
+        // this must never silently edit what a caller receives.
+        const response: Record<string, unknown> = { tier: 42, legacy_extra: 'still here' };
+        const pristine = structuredClone(response);
+        expect(validateApiResponse('QuotaTierResponse', response).valid).toBe(false);
+        expect(response).toEqual(pristine);
+    });
+});

package/src/api-schemas/quota.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+
+/**
+ * Runtime API schemas for quota standing and tier endpoints.
+ */
+
+/**
+ * Note the `id`: this is a hoisted component in the document, not an inline string. `z.string()` alone
+ * would inline it at every use site and change three published schemas.
+ */
+export const QuotaEffectiveTierSchema = z.string().meta({
+    id: 'QuotaEffectiveTier',
+    description:
+        'Effective quota tier name after account-level overrides and account-type derivation. ' +
+        'Code-defined tier names are currently `QuotaTier`, but this remains a string because deployments ' +
+        'can introduce quota tiers through configuration.',
+});
+
+/**
+ * Descriptions go in `.meta()`, not in TSDoc comments.
+ *
+ * Zod does not read comments, so public descriptions belong in schema metadata.
+ */
+export const QuotaStandingWindowSchema = z
+    .object({
+        limit: z.number().meta({
+            description: 'Effective limit for this window (after effective account tier + per-tenant override).',
+        }),
+        used: z.number().meta({ description: 'Requests used in the current window.' }),
+        remaining: z.number().meta({ description: 'Requests remaining (max(0, limit - used)).' }),
+        window_ms: z.number(),
+    })
+    .meta({
+        id: 'QuotaStandingWindow',
+        description:
+            'A caller\'s own quota standing (GET /api/v1/quota/standing) — "where am I". API rate limits are ' +
+            'genuinely per-tenant; workflow admission and the LLM limiter are global/discovered, so they are ' +
+            'reported as posture, not per-tenant numbers.',
+    });
+
+export const QuotaStandingResourceSchema = z
+    .object({
+        resource: z.string(),
+        name: z.string(),
+        burst: QuotaStandingWindowSchema,
+        quota: QuotaStandingWindowSchema,
+    })
+    .meta({ id: 'QuotaStandingResource' });
+
+export const QuotaStandingAdmissionClassSchema = z
+    .object({
+        class: z.string().meta({ description: 'Workflow class (e.g. ExecuteConversationWorkflow).' }),
+        tenant_active: z.number().meta({ description: "This tenant's currently active (leased) slots for the class." }),
+    })
+    .meta({ id: 'QuotaStandingAdmissionClass' });
+
+export const QuotaStandingResponseSchema = z
+    .object({
+        tenant_id: z.string(),
+        available: z.boolean().meta({
+            description:
+                'False when the limiter store (Redis) was unavailable, so `api`/`admission` are empty because ' +
+                'standing could not be read — NOT because there are no limits. Limiters fail open in this case.',
+        }),
+        base_tier: z
+            .string()
+            .meta({ description: 'Deployment base tier (env QUOTA_BASE_TIER); `default` = the static limits stand.' }),
+        effective_tier: QuotaEffectiveTierSchema.meta({
+            description:
+                'Tier used to compute the API limits below: explicit account `quota_tier`, else account_type ' +
+                'derived tier, else `base_tier` when the account tier could not be resolved.',
+        }),
+        api: z.array(QuotaStandingResourceSchema).meta({
+            description: 'Per-resource API rate-limit standing (effective limits + current usage).',
+        }),
+        // Anonymous in the interface and anonymous in the document, so it stays inline here rather than
+        // becoming a named component — naming it would add a `$ref` the spec does not currently publish.
+        admission: z
+            .object({
+                classes: z.array(QuotaStandingAdmissionClassSchema),
+                note: z.string(),
+            })
+            .meta({
+                description:
+                    'Workflow admission: per-tenant active slots per probed class. The budget itself is global and ' +
+                    'discovered (AIMD), not a per-tenant number — this is occupancy, not a limit.',
+            }),
+        llm: z.object({ note: z.string() }).meta({
+            description: 'The LLM interaction limiter is shared per environment/model, not per tenant.',
+        }),
+    })
+    .meta({ id: 'QuotaStandingResponse' });
+
+export const QuotaTierResponseSchema = z
+    .object({
+        tier: QuotaEffectiveTierSchema,
+    })
+    .meta({
+        id: 'QuotaTierResponse',
+        description:
+            'Lightweight per-account quota tier for the calling account — served by `GET /api/v1/quota/tier`. ' +
+            "A cheap, cacheable read that lets another service (e.g. zeno-server's API rate limiter) resolve " +
+            "the caller's tier through studio-server instead of reaching into the account store directly. " +
+            "`tier` is the SAME value  {@link  QuotaStandingResponse.effective_tier }  reports: the account's " +
+            'explicit `quota_tier`, else its account_type-derived tier, else the deployment base tier when the ' +
+            'account tier cannot be resolved.',
+    });
+
+/**
+ * The public quota types, inferred rather than written.
+ *
+ * Every schema in the closure gets one — not only the two the endpoints return. A hand-written
+ * `QuotaStandingWindow` sitting beside an inferred `QuotaStandingResponse` would create two
+ * definitions of one contract, only one of which OpenAPI publishes and AJV compiles.
+ * `../rate-limiter.ts` re-exports these under their public names.
+ */
+export type QuotaEffectiveTierFromSchema = z.infer<typeof QuotaEffectiveTierSchema>;
+export type QuotaStandingWindowFromSchema = z.infer<typeof QuotaStandingWindowSchema>;
+export type QuotaStandingResourceFromSchema = z.infer<typeof QuotaStandingResourceSchema>;
+export type QuotaStandingAdmissionClassFromSchema = z.infer<typeof QuotaStandingAdmissionClassSchema>;
+export type QuotaStandingResponseFromSchema = z.infer<typeof QuotaStandingResponseSchema>;
+export type QuotaTierResponseFromSchema = z.infer<typeof QuotaTierResponseSchema>;

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

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { type ApiComponentName, type ApiComponentType, ApiSchemaComponents, mergeComponentGroups } from './registry.js';
+
+/**
+ * `N` when `ApiComponentType` resolves it, and `never` when it does not.
+ *
+ * The conditional that maps a name to its inferred type tests the groups one by one and ends in
+ * `never`, so a group missing from that chain — the third place a new group has to be listed, after
+ * the merge array and the `ApiComponentName` union — makes every name in it resolve to `never`
+ * rather than fail. Distributing this over the whole union turns that into an assignment error on
+ * the list below, which `typecheck:test` reports.
+ */
+type ResolvedName<N extends ApiComponentName> = [ApiComponentType<N>] extends [never] ? never : N;
+
+/**
+ * Covers the one way the group split can corrupt the registry.
+ *
+ * The registry is declared in several objects because the compiler cannot serialize it as one, and
+ * the two public types are assembled from those objects: `ApiComponentName` is a union of `keyof`,
+ * `ApiComponentType` a conditional testing the groups IN ORDER. A plain spread merge would accept a
+ * name listed twice and keep the LAST group's schema, while `ApiComponentType` would resolve to the
+ * FIRST group's — validation enforcing one shape while every handler is typed against another, with
+ * nothing downstream to report it. The grouping is a compiler accommodation, so this failure mode is
+ * pure accident: a component moved between groups and left behind, or added to whichever group the
+ * author had open.
+ *
+ * The real groups are covered by the call itself, which runs at module load — a duplicate there
+ * throws on import and takes every test in the package with it. What is tested here is that the
+ * merge actually refuses, which no import of a correct registry can show.
+ */
+describe('mergeComponentGroups', () => {
+    const A = z.strictObject({ a: z.string() });
+    const B = z.strictObject({ b: z.number() });
+
+    it('merges disjoint groups into one object', () => {
+        const merged = mergeComponentGroups([{ Alpha: A }, { Beta: B }]);
+
+        expect(Object.keys(merged).sort()).toEqual(['Alpha', 'Beta']);
+        expect(merged.Alpha).toBe(A);
+        expect(merged.Beta).toBe(B);
+    });
+
+    it('refuses a name registered in two groups', () => {
+        expect(() => mergeComponentGroups([{ Alpha: A }, { Alpha: B }])).toThrow(
+            /registered in more than one group: Alpha/,
+        );
+    });
+
+    it('names every colliding component, not just the first', () => {
+        expect(() => mergeComponentGroups([{ Beta: B, Alpha: A }, { Alpha: B }, { Beta: A }])).toThrow(
+            /components registered in more than one group: Alpha, Beta/,
+        );
+    });
+
+    it('reports a collision across non-adjacent groups', () => {
+        // The failure is a name in ANY two groups, not only in two that happen to be listed together.
+        expect(() => mergeComponentGroups([{ Alpha: A }, { Beta: B }, { Alpha: B }])).toThrow(
+            /registered in more than one group: Alpha/,
+        );
+    });
+
+    it('emits a component from every group, and resolves its type', () => {
+        // The merge takes a list, so a group can be dropped from it as easily as duplicated in it —
+        // and dropping one is silent in a different way: `ApiComponentName` still names those
+        // components, so the code compiles and only the emitted document loses them. One known name
+        // per group is what notices — the `satisfies` for the type conditional, the loop for the
+        // merge.
+        const perGroup = [
+            'Account',
+            'ProjectModelDefaults',
+            'OAuthProvider',
+            'ExecutionEnvironment',
+            'JSONValue',
+            'Interaction',
+            'ImprovePromptPayload',
+            'AgentRunnerOptions',
+            'ExecutionRunStatus',
+            'RenderPromptResponse',
+            'AggregatedTool',
+            'OAuthAuthStatus',
+            'AuditTrailResponse',
+            'ViewExperience',
+            'CopyFilePayload',
+        ] as const satisfies readonly ResolvedName<ApiComponentName>[];
+
+        for (const name of perGroup) {
+            expect(ApiSchemaComponents).toHaveProperty(name);
+        }
+    });
+});