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

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

@@ -1,189 +0,0 @@
-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

@@ -1,147 +0,0 @@
-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/registry-groups.test.ts

@@ -1,99 +0,0 @@
-import { describe, expect, expectTypeOf, it } from 'vitest';
-import { z } from 'zod';
-import type { NamedInteractionExecutionPayloadSchema } from './interaction.js';
-import { type ApiComponentName, type ApiComponentType, ApiSchemaComponents, mergeComponentGroups } from './registry.js';
-
-/**
- * `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', () => {
-    it('preserves execution payload types and rejects unregistered component names', () => {
-        expectTypeOf<ApiComponentType<'NamedInteractionExecutionPayload'>>().toEqualTypeOf<
-            z.infer<typeof NamedInteractionExecutionPayloadSchema>
-        >();
-        expectTypeOf<'UnregisteredExecutionComponent'>().not.toMatchTypeOf<ApiComponentName>();
-    });
-
-    const A = z.strictObject({ a: z.string() });
-    const B = z.strictObject({ b: z.number() });
-
-    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);
-        }
-    });
-});