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

package/src/api-schemas/files.ts

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+
+export const StringValueMapSchema = z.object({}).catchall(z.string()).meta({ id: 'StringValueMap' });
+
+export const FileMetadataUpdateResultSchema = z
+    .strictObject({
+        success: z.boolean(),
+        file: z.string(),
+    })
+    .meta({ id: 'FileMetadataUpdateResult' });
+
+export const FileListResponseSchema = z
+    .strictObject({
+        files: z.array(z.string()),
+    })
+    .meta({ id: 'FileListResponse' });
+
+export const GetUploadUrlPayloadSchema = z
+    .strictObject({
+        name: z.string(),
+        id: z.string().optional(),
+        mime_type: z.string().optional(),
+        ttl: z.number().optional(),
+    })
+    .meta({ id: 'GetUploadUrlPayload' });
+
+export const FileMetadataResponseSchema = z
+    .strictObject({
+        name: z.string(),
+        size: z.number(),
+        contentType: z.string(),
+        contentDisposition: z.string().optional(),
+        etag: z.string().optional(),
+        customMetadata: StringValueMapSchema.optional(),
+    })
+    .meta({ id: 'FileMetadataResponse' });
+
+export const GetFileUrlResponseSchema = z
+    .strictObject({
+        url: z.string(),
+        id: z.string(),
+        mime_type: z.string().optional(),
+        path: z.string(),
+    })
+    .meta({ id: 'GetFileUrlResponse' });
+
+export const GetFileUrlPayloadSchema = z
+    .strictObject({
+        file: z.string(),
+        name: z.string().optional(),
+        disposition: z.enum(['inline', 'attachment']).optional(),
+    })
+    .meta({ id: 'GetFileUrlPayload' });
+
+export const BulkUploadUrlsResponseSchema = z
+    .strictObject({
+        files: z.array(GetFileUrlResponseSchema),
+    })
+    .meta({ id: 'BulkUploadUrlsResponse' });
+
+export const BulkUploadUrlsPayloadSchema = z
+    .strictObject({
+        files: z.array(
+            z.strictObject({
+                name: z.string(),
+                mime_type: z.string().optional(),
+                id: z.string().optional(),
+            }),
+        ),
+    })
+    .meta({ id: 'BulkUploadUrlsPayload' });
+
+export const FileBucketResponseSchema = z
+    .strictObject({
+        bucket: z.string(),
+    })
+    .meta({ id: 'FileBucketResponse' });
+
+export const DeleteFileResultSchema = z
+    .strictObject({
+        success: z.boolean(),
+        count: z.number(),
+        message: z.string().optional(),
+        file: z.string().optional(),
+    })
+    .meta({ id: 'DeleteFileResult' });
+
+export const CopyFileResponseSchema = z
+    .strictObject({
+        success: z.boolean(),
+        source: z.string(),
+        dest: z.string(),
+    })
+    .meta({ id: 'CopyFileResponse' });
+
+export const CopyFilePayloadSchema = z
+    .strictObject({
+        source: z.string(),
+        dest: z.string(),
+    })
+    .meta({ id: 'CopyFilePayload' });
+
+export const SetFileMetadataPayloadSchema = z
+    .strictObject({
+        file: z.string().meta({ description: 'The file path (relative to bucket) or full URI' }),
+        metadata: StringValueMapSchema.meta({ description: 'Custom metadata key-value pairs to set on the file' }),
+    })
+    .meta({ id: 'SetFileMetadataPayload' });
+
+/**
+ * The file query contracts.
+ *
+ * `file` and `prefix` are required, which the document already said and each handler restated as its
+ * own `ctx.throw(400, 'The … query parameter is required')`. Enforcing the component removes the
+ * restatement; the message changes wording and the status does not.
+ */
+export const FileMetadataQuerySchema = z
+    .strictObject({
+        file: z.string(),
+    })
+    .meta({ id: 'FileMetadataQuery' });
+
+export const FileListQuerySchema = z
+    .strictObject({
+        prefix: z.string(),
+    })
+    .meta({ id: 'FileListQuery' });
+
+export const FileDeleteQuerySchema = z
+    .strictObject({
+        prefix: z.boolean().optional(),
+    })
+    .meta({ id: 'FileDeleteQuery' });
+
+export const BucketReadAccessQuerySchema = z
+    .strictObject({
+        principal: z.string(),
+    })
+    .meta({ id: 'BucketReadAccessQuery' });
+
+export const EnsureBucketReadAccessPayloadSchema = BucketReadAccessQuerySchema.meta({
+    id: 'EnsureBucketReadAccessPayload',
+});
+
+export const EnsureBucketReadAccessResponseSchema = z
+    .strictObject({
+        bucket: z.string(),
+        principal: z.string(),
+        granted: z.boolean(),
+    })
+    .meta({ id: 'EnsureBucketReadAccessResponse' });
+
+export const BucketReadAccessStatusResponseSchema = z
+    .strictObject({
+        bucket: z.string(),
+        principal: z.string(),
+        hasAccess: z.boolean(),
+    })
+    .meta({ id: 'BucketReadAccessStatusResponse' });

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

@@ -0,0 +1,205 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { describe, expect, it } from 'vitest';
+import type { CreateUserGroupPayload, UpdateUserGroupPayload, UserGroup } from '../group.js';
+import type { User, UserRef } from '../user.js';
+import type { JsonObject } from './adapter.js';
+import type { UserGroupArrayFromSchema } from './group.js';
+import { ApiSchemaComponents, apiComponentRef, validateApiRequest, validateApiResponse } from './registry.js';
+import type { UserRefArrayFromSchema } 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;
+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_GROUP = {
+    id: 'g1',
+    account: 'a1',
+    name: 'Engineering',
+    tags: ['eng'],
+    created_at: '2026-07-30T10:00:00.000Z',
+    updated_at: '2026-07-30T10:00:00.000Z',
+};
+
+const VALID_REF = { id: 'u1', name: 'Someone', email: 'someone@acme.com' };
+
+describe('gate 1 — the schema is the single source of truth for the public group types', () => {
+    it('publishes the exact schema-derived type, not a hand-written twin', () => {
+        assertType<Equals<UserGroupArrayFromSchema, UserGroup[]>>(true);
+        assertType<Equals<UserRefArrayFromSchema, UserRef[]>>(true);
+        expect(true).toBe(true);
+    });
+
+    it('types the timestamps as the strings a client actually receives', () => {
+        // They were `Date` on the public type while the document published `format: date-time`
+        // strings. JSON has no date type, so the old declaration described the Mongoose document
+        // rather than the response — this is the correction, and the reason it is a compile-time
+        // break for anyone who was calling `.getTime()` on one.
+        assertType<Equals<UserGroup['created_at'], string>>(true);
+        assertType<Equals<UserGroup['updated_at'], string>>(true);
+        assertType<Equals<UserGroup['tags'], string[]>>(true);
+        assertType<Equals<UserGroup['allowed_projects'], string[] | undefined>>(true);
+        expect(true).toBe(true);
+    });
+
+    it('derives UserRef from User rather than restating four fields', () => {
+        // `.pick()` on UserSchema, so a change to how `User` declares one of these follows through
+        // instead of leaving a twin behind. The requiredness comes with it: `email` is required on
+        // both, which is why the members listing has to map rather than serialize.
+        assertType<Equals<UserRef['id'], User['id']>>(true);
+        assertType<Equals<UserRef['name'], User['name']>>(true);
+        assertType<Equals<UserRef['email'], User['email']>>(true);
+        assertType<Equals<UserRef['picture'], User['picture']>>(true);
+        // And nothing else came across.
+        assertType<Equals<keyof UserRef, 'id' | 'name' | 'email' | 'picture'>>(true);
+        expect(true).toBe(true);
+    });
+
+    it('derives both payloads from the group rather than restating its fields', () => {
+        // Same reasoning as UserRef, applied to the write side: each payload is a subset of the
+        // group, so the field types follow the response. Only requiredness differs, and only where
+        // it should — `tags` is required on a group the server always populates and optional in a
+        // payload the caller need not send.
+        assertType<Equals<CreateUserGroupPayload['name'], UserGroup['name']>>(true);
+        assertType<Equals<CreateUserGroupPayload['description'], UserGroup['description']>>(true);
+        assertType<Equals<CreateUserGroupPayload['tags'], string[] | undefined>>(true);
+        assertType<Equals<keyof CreateUserGroupPayload, 'name' | 'description' | 'tags' | 'allowed_projects'>>(true);
+        assertType<Equals<UpdateUserGroupPayload['properties'], UserGroup['properties']>>(true);
+        assertType<Equals<UpdateUserGroupPayload['clearance'], UserGroup['clearance']>>(true);
+        assertType<Equals<UpdateUserGroupPayload['compartments'], UserGroup['compartments']>>(true);
+        // The whitelist is what the pick leaves out: nothing server-owned is writable.
+        assertType<
+            Equals<
+                keyof UpdateUserGroupPayload,
+                'name' | 'description' | 'tags' | 'properties' | 'clearance' | 'compartments' | 'allowed_projects'
+            >
+        >(true);
+        expect(true).toBe(true);
+    });
+});
+
+describe('gate 2 — the published components match the closure the types come from', () => {
+    it('does not declare members on the group component', () => {
+        // Three handlers were shipping `members` — two by populating a `select: false` path, one by
+        // returning the in-memory document — while the component is closed and has never declared
+        // it. Members are published by their own route as UserRef[].
+        expect(Object.keys(ApiSchemaComponents.UserGroup.properties as JsonObject)).not.toContain('members');
+        expect(ApiSchemaComponents.UserGroup.additionalProperties).toBe(false);
+    });
+
+    it('publishes UserRef as its own component, not a $ref back to User', () => {
+        // `.pick()` drops the `id: 'User'` metadata, which is what keeps the projection a separate
+        // component. If it carried the id across, every UserRef slot would suddenly promise a whole
+        // User to generated clients.
+        expect(JSON.stringify(ApiSchemaComponents.UserRef)).not.toContain('$ref');
+        expect(ApiSchemaComponents.UserRef.required).toEqual(['id', 'name', 'email']);
+        expect(ApiSchemaComponents.UserRefArray).toEqual({
+            type: 'array',
+            items: { $ref: '#/components/schemas/UserRef' },
+        });
+    });
+
+    it('keeps the timestamps enforceable rather than merely documented', () => {
+        const props = ApiSchemaComponents.UserGroup.properties as Record<string, JsonObject>;
+        expect(props.created_at).toEqual({ type: 'string', format: 'date-time' });
+        expect(ApiSchemaComponents.UserGroup.required).toEqual([
+            'id',
+            'account',
+            'name',
+            'tags',
+            'created_at',
+            'updated_at',
+        ]);
+    });
+});
+
+describe('gate 3 — AJV validates the same canonical objects that are published', () => {
+    it('accepts a minimal group and rejects a missing required field', () => {
+        const validate = compile('UserGroup');
+        expect(validate(VALID_GROUP)).toBe(true);
+        const { tags: _dropped, ...incomplete } = VALID_GROUP;
+        expect(validate(incomplete)).toBe(false);
+    });
+
+    it('rejects the internal fields a serialized document would have leaked', () => {
+        const validate = compile('UserGroup');
+        expect(validate({ ...VALID_GROUP, members: ['u1'] })).toBe(false);
+        expect(validate({ ...VALID_GROUP, _id: 'deadbeef' })).toBe(false);
+        expect(validate({ ...VALID_GROUP, __v: 0 })).toBe(false);
+    });
+
+    it('requires a name on the update payload, which both handlers checked by hand', () => {
+        const validate = compile('UpdateUserGroupPayload');
+        expect(validate({ name: 'Renamed' })).toBe(true);
+        expect(validate({})).toBe(false);
+        expect(validate({ name: 'Renamed', rogue_field: 1 })).toBe(false);
+    });
+
+    it('accepts a create payload with only a name', () => {
+        const validate = compile('CreateUserGroupPayload');
+        expect(validate({ name: 'Engineering' })).toBe(true);
+        expect(validate({ name: 'Engineering', allowed_projects: [] })).toBe(true);
+        // `properties` and `clearance` are updatable but not settable at creation, and never were.
+        expect(validate({ name: 'Engineering', clearance: 3 })).toBe(false);
+    });
+
+    it('documents allowed_projects for the request rather than inheriting the response text', () => {
+        // The one field where picking is not enough: the response explains what an empty list MEANS,
+        // the request explains what sending one DOES. Overriding the picked field is how a payload
+        // keeps request-specific documentation — and the same mechanism a field with genuinely
+        // different request semantics would need.
+        const create = (ApiSchemaComponents.CreateUserGroupPayload.properties as Record<string, JsonObject>)
+            .allowed_projects;
+        const group = (ApiSchemaComponents.UserGroup.properties as Record<string, JsonObject>).allowed_projects;
+        expect(create.description).toBe('Restrict the new group to the given projects (empty/absent = org-wide).');
+        expect(create.description).not.toBe(group.description);
+        // Everything except the description still comes from the group.
+        expect({ ...create, description: undefined }).toEqual({ ...group, description: undefined });
+    });
+});
+
+describe('gate 4 — runtime enforcement uses the published components', () => {
+    it('enforces the date-time format the timestamps claim', () => {
+        // Through the registry rather than the local `compile` helper: the production validator
+        // registers ajv-formats, and a bare Ajv2020 ignores `format` entirely.
+        expect(validateApiResponse('UserGroup', { ...VALID_GROUP, created_at: 'yesterday' }).valid).toBe(false);
+        expect(validateApiResponse('UserGroup', VALID_GROUP).valid).toBe(true);
+    });
+
+    it('rejects an undeclared update field without removing it', () => {
+        const payload: Record<string, unknown> = { name: 'Acme', rogue_field: 42 };
+        const result = validateApiRequest('UpdateUserGroupPayload', payload);
+        expect(result.valid).toBe(false);
+        expect(payload.rogue_field).toBe(42);
+    });
+
+    it('checks every member of the group listing against the same UserGroup component', () => {
+        expect(validateApiResponse('UserGroupArray', [VALID_GROUP, VALID_GROUP]).valid).toBe(true);
+        expect(validateApiResponse('UserGroupArray', []).valid).toBe(true);
+        // One group still carrying its members is what the unmapped listing would have produced.
+        expect(validateApiResponse('UserGroupArray', [VALID_GROUP, { ...VALID_GROUP, members: [] }]).valid).toBe(false);
+    });
+
+    it('checks every member of the members listing against UserRef', () => {
+        expect(validateApiResponse('UserRefArray', [VALID_REF]).valid).toBe(true);
+        // A user Mongo holds with no email — required on the wire, which is why the handler maps.
+        const { email: _dropped, ...withoutEmail } = VALID_REF;
+        expect(validateApiResponse('UserRefArray', [withoutEmail]).valid).toBe(false);
+        expect(validateApiResponse('UserRefArray', [{ ...VALID_REF, email: '' }]).valid).toBe(true);
+        // And the whole user document, which is what serializing the populated doc would send.
+        expect(validateApiResponse('UserRefArray', [{ ...VALID_REF, clearance: 3 }]).valid).toBe(false);
+    });
+
+    it('hands back the component type on the valid branch', () => {
+        const result = validateApiResponse('UserGroup', VALID_GROUP);
+        expect(result.valid).toBe(true);
+        if (result.valid) {
+            assertType<Equals<typeof result.data, UserGroup>>(true);
+        }
+    });
+});

package/src/api-schemas/group.ts

@@ -0,0 +1,155 @@
+import { z } from 'zod';
+
+/**
+ * Runtime API schemas for the IAM user-group endpoints.
+ *
+ * These contracts cross a persistence boundary, and the gap between document and wire is
+ * wider here. Three things the stored document carries are NOT in this contract and never were:
+ * `members` (the model marks it `select: false`, yet two handlers `populate()` it straight back into
+ * the response), `_id`, and `__v`. `UserGroup` is published `additionalProperties: false`, so those
+ * responses have been violating their own schema; the server now maps the document explicitly
+ * instead of serializing it, which is what makes the published contract true.
+ *
+ * `UserRef` lives in `./user.js` rather than here — it is the shape of a USER, published by the
+ * group members listing but not owned by it.
+ */
+
+/**
+ * The user group as it crosses the wire.
+ *
+ * `created_at`/`updated_at` are declared `z.string()` while the public TypeScript type used to say
+ * `Date`. The document has always published `type: string, format: date-time`, and JSON has no date
+ * type, so the old type was wrong about what a client receives — it described the Mongoose document,
+ * not the response. Inferring the public type from this schema corrects it.
+ */
+export const UserGroupSchema = z
+    .object({
+        id: z.string(),
+        account: z.string(),
+        name: z.string(),
+        description: z.string().optional(),
+        tags: z.array(z.string()),
+        created_at: z.string().meta({ format: 'date-time' }),
+        updated_at: z.string().meta({ format: 'date-time' }),
+        created_by: z.string().optional(),
+        updated_by: z.string().optional(),
+        properties: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .meta({ description: 'Custom properties for dynamic permission matching' }),
+        clearance: z
+            .number()
+            .optional()
+            .meta({ description: 'BLP clearance level — merged with user clearance using max()' }),
+        compartments: z
+            .array(z.string())
+            .optional()
+            .meta({ description: 'Compartments — merged with user compartments using array union' }),
+        allowed_projects: z
+            .array(z.string())
+            .optional()
+            .meta({
+                description:
+                    'Projects this group is allowed to be used in. When empty or absent the group is org-wide ' +
+                    '(usable in any project). When set, the group may only be used to grant permissions in the ' +
+                    'listed projects.',
+            }),
+    })
+    .meta({ id: 'UserGroup' });
+
+/**
+ * The group listing. Converted with `UserGroup` rather than later: its items `$ref` the canonical
+ * component, so publishing the array while returning an unmapped document would document the
+ * contract for every group and enforce it for none — the gap the account members listing had.
+ */
+export const UserGroupArraySchema = z.array(UserGroupSchema).meta({ id: 'UserGroupArray' });
+
+/**
+ * Both payloads are picked from {@link UserGroupSchema}, for the same reason `UserRef` is: they are
+ * subsets of the group, not parallel shapes. What each `.pick()` leaves out is the whitelist —
+ * `id`, `account`, the timestamps and `created_by`/`updated_by` are server-owned — and it can no
+ * longer widen silently, because adding a writable field means naming it here.
+ *
+ * `tags` is the one field whose requiredness genuinely differs: a group always HAS tags (the model
+ * defaults to `[]`), but neither payload makes the caller send them.
+ */
+const UserGroupWritableSchema = UserGroupSchema.pick({
+    name: true,
+    description: true,
+    tags: true,
+    allowed_projects: true,
+});
+
+/**
+ * `allowed_projects` is overridden rather than inherited: on the response it explains what an empty
+ * list MEANS, while on a create request it tells the caller what sending one DOES. Same field, and
+ * genuinely different documentation — which is the general rule for picking. Anything where the
+ * request semantics differ (a `null` that clears a value, a coercion, a request-only bound) has to be
+ * overridden the same way instead of inherited.
+ */
+export const CreateUserGroupPayloadSchema = UserGroupWritableSchema.partial({ tags: true })
+    .extend({
+        allowed_projects: z
+            .array(z.string())
+            .optional()
+            .meta({ description: 'Restrict the new group to the given projects (empty/absent = org-wide).' }),
+    })
+    .meta({ id: 'CreateUserGroupPayload' });
+
+/**
+ * The update payload writes more than create does — the BLP and dynamic-matching fields are settable
+ * only after the group exists — so it picks a wider subset of the same schema.
+ *
+ * `name` is required, which the published component has always said and both update handlers
+ * enforced by hand with a 400. Validation now does it, so the hand-rolled check is redundant rather
+ * than load-bearing — it is kept for the same reason the user update whitelist was: removing it is a
+ * behaviour change that does not belong in a contract change.
+ */
+export const UpdateUserGroupPayloadSchema = UserGroupSchema.pick({
+    name: true,
+    description: true,
+    tags: true,
+    properties: true,
+    clearance: true,
+    compartments: true,
+    allowed_projects: true,
+})
+    .partial({ tags: true })
+    .meta({ id: 'UpdateUserGroupPayload' });
+
+/**
+ * The group as it appears embedded in a token payload, and the one place a group crosses the wire
+ * without being the response of a group endpoint.
+ *
+ * Picked from {@link UserGroupSchema} for the same reason the payloads are — it is a subset of the
+ * group, not a parallel shape — and the subset is decided by what an authorization decision needs:
+ * identity (`id`, `name`), the dynamic-matching input (`tags`, `properties`) and the BLP inputs
+ * (`clearance`, `compartments`, `allowed_projects`). `account` and the audit fields are deliberately
+ * out: a token is not a place to restate who edited a group.
+ *
+ * `tags` is optional here while the group always has them, matching the payloads: the token mapper
+ * omits an empty list rather than emitting one.
+ *
+ * This is NOT the Mongoose projection that feeds it. The projection is a `select()` string that lives
+ * beside its query — token-server has one, studio-server's resource-reference endpoint has a
+ * different and much narrower one — and a single shared string would have to be the union of every
+ * caller's needs, which is how the previous `UserGroupRefPopulate` came to select a `description`
+ * that nothing emits.
+ */
+export const UserGroupRefSchema = UserGroupSchema.pick({
+    id: true,
+    name: true,
+    tags: true,
+    properties: true,
+    clearance: true,
+    compartments: true,
+    allowed_projects: true,
+})
+    .partial({ tags: true })
+    .meta({ id: 'UserGroupRef' });
+
+/**
+ * The array components have no public alias of their own — `UserGroup[]` is what the client sees —
+ * so this exists only for the gate in `./group.contract.test.ts` to assert that equivalence.
+ */
+export type UserGroupArrayFromSchema = z.infer<typeof UserGroupArraySchema>;

package/src/api-schemas/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Runtime API schema entry point — `@vertesia/common/api-schemas`.
+ *
+ * Kept OUT of the package root on purpose. `lib/index.js` is bundled wholesale into
+ * `lib/vertesia-common.js` (see `rolldown.config.js`) and served to browsers as a single shared
+ * library (see `apps/composable-ui/build/shared-libs.ts`), with no per-consumer tree-shaking. A
+ * runtime `export *` from the root would therefore ship zod to every UI user. The root re-exports
+ * only the derived TYPES, via `export type`, which tsc erases.
+ *
+ * Servers and the OpenAPI scanner import from this subpath explicitly.
+ */
+export * from './account.js';
+export * from './adapter.js';
+export * from './agent-runs.js';
+export * from './analytics.js';
+export * from './apikey.js';
+export * from './app-runtime.js';
+export * from './bulk-operation.js';
+export * from './content.js';
+export * from './cost-analytics.js';
+export * from './dashboard.js';
+export * from './data-store.js';
+export * from './document-processing.js';
+export * from './embeddings.js';
+export * from './environment.js';
+export * from './events.js';
+export * from './indexing.js';
+export * from './integrations.js';
+export * from './parameters.js';
+export * from './process.js';
+export * from './quota.js';
+export * from './registry.js';
+export * from './secrets.js';
+export * from './view-execution.js';
+export * from './workflow-runs.js';

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

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import type { GenericCommandResponse } from '../common.js';
+import type {
+    DriftAnalysisStatusResponse,
+    EmbeddingsStatusResponse,
+    IndexingStatusResponse,
+    ProjectConfigurationEmbeddingEnablePayload,
+    ReindexAgentRunsPayload,
+    ReindexAgentRunsResponse,
+    StartProjectReindexPayload,
+} from '../project.js';
+import { WorkflowExecutionStatus } from '../store/workflow.js';
+import type { GenericCommandResponseSchema } from './commands.js';
+import type { EmbeddingsStatusResponseSchema, ProjectConfigurationEmbeddingEnablePayloadSchema } from './embeddings.js';
+import type {
+    DriftAnalysisStatusResponseSchema,
+    IndexingStatusResponseSchema,
+    ReindexAgentRunsPayloadSchema,
+    ReindexAgentRunsResponseSchema,
+    StartProjectReindexPayloadSchema,
+} from './indexing.js';
+import { validateApiRequest, validateApiResponse } from './registry.js';
+
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+function assertType<T extends true>(_value: T): void {}
+
+describe('indexing and embedding API contracts', () => {
+    it('derives every public type from its domain schema', () => {
+        assertType<Equals<GenericCommandResponse, typeof GenericCommandResponseSchema._output>>(true);
+        assertType<Equals<EmbeddingsStatusResponse, typeof EmbeddingsStatusResponseSchema._output>>(true);
+        assertType<Equals<IndexingStatusResponse, typeof IndexingStatusResponseSchema._output>>(true);
+        assertType<Equals<DriftAnalysisStatusResponse, typeof DriftAnalysisStatusResponseSchema._output>>(true);
+        assertType<
+            Equals<
+                ProjectConfigurationEmbeddingEnablePayload,
+                typeof ProjectConfigurationEmbeddingEnablePayloadSchema._output
+            >
+        >(true);
+        assertType<Equals<StartProjectReindexPayload, typeof StartProjectReindexPayloadSchema._output>>(true);
+        assertType<Equals<ReindexAgentRunsPayload, typeof ReindexAgentRunsPayloadSchema._output>>(true);
+        assertType<Equals<ReindexAgentRunsResponse, typeof ReindexAgentRunsResponseSchema._output>>(true);
+    });
+
+    it('rejects undeclared request fields while allowing both optional reindex bodies', () => {
+        expect(validateApiRequest('StartProjectReindexPayload', undefined).valid).toBe(false);
+        expect(validateApiRequest('StartProjectReindexPayload', {}).valid).toBe(true);
+        expect(validateApiRequest('StartProjectReindexPayload', { unexpected: true }).valid).toBe(false);
+        expect(validateApiRequest('ReindexAgentRunsPayload', {}).valid).toBe(true);
+        expect(validateApiRequest('ReindexAgentRunsPayload', { recreate_index: true, unexpected: true }).valid).toBe(
+            false,
+        );
+    });
+
+    it('keeps drift workflow status numeric and nullable identifiers explicit', () => {
+        expect(
+            validateApiResponse('DriftAnalysisStatusResponse', {
+                workflow_id: null,
+                workflow_run_id: null,
+                status: WorkflowExecutionStatus.UNKNOWN,
+            }).valid,
+        ).toBe(true);
+        expect(
+            validateApiResponse('DriftAnalysisStatusResponse', {
+                workflow_id: null,
+                workflow_run_id: null,
+                status: 'NOT_FOUND',
+            }).valid,
+        ).toBe(false);
+    });
+
+    it('validates command and embedding responses against the published components', () => {
+        expect(validateApiResponse('GenericCommandResponse', { status: 'ok', message: 'done' }).valid).toBe(true);
+        expect(
+            validateApiResponse('GenericCommandResponse', { status: 'ok', message: 'done', extra: true }).valid,
+        ).toBe(false);
+        expect(
+            validateApiResponse('EmbeddingsStatusResponse', {
+                status: 'success',
+                vectorIndex: { status: 'READY' },
+            }).valid,
+        ).toBe(true);
+    });
+});