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

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

@@ -0,0 +1,450 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Ajv } from 'ajv';
+import { describe, expect, it } from 'vitest';
+import { ContentTypeIntakePolicySchema as GeneratedIntakePolicySchema } from '../store/intake-policy-schema.generated.js';
+import type { ContentObjectTypeRef, ContentTypeIntakePolicy, IntakePageRanges } from '../store/store.js';
+import type { JsonObject } from './adapter.js';
+import { ApiSchemaComponents, bundleCanonicalComponent, validateApiResponse } from './registry.js';
+import { ContentTypeIntakePolicySchema } from './store.js';
+
+/** 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 {}
+
+/**
+ * The intake policy is now stated once, in Zod, and reaches its consumers three ways: as the
+ * published OpenAPI component, as the checked-in JSON artifact that zeno-server / the workflow tool /
+ * the web editor compiles, and as the TypeScript type. This file is the gate that keeps all three
+ * the same statement.
+ *
+ * It also pins the behaviour changes the conversion makes, because the schema it replaced was
+ * hand-written and disagreed with the contract in both directions. Each is asserted rather than
+ * described: the whole point of the migration is that a disagreement fails a build instead of
+ * shipping.
+ */
+const ajv = new Ajv({ strict: false, allErrors: true });
+const validate = ajv.compile<ContentTypeIntakePolicy>(GeneratedIntakePolicySchema);
+
+function errors(): string {
+    return ajv.errorsText(validate.errors, { separator: '\n' });
+}
+
+/**
+ * Reads a file from the studio repository this package is a submodule of.
+ *
+ * `undefined` when it is not there, which is the normal state in this repository's own CI: it clones
+ * composableai alone, so nothing above the submodule root exists. Two of the gates below compare
+ * against the published document and the generated-client fixture, both of which live up there — so
+ * they are skipped when they cannot be read rather than failing the whole file at import time, which
+ * is what used to happen and what left this suite red on every commit.
+ *
+ * They still run where they are the actual gate: a checkout of the parent repository, which is what
+ * the migration's own verification and the studio CI use.
+ */
+function readFromStudioRepo(relativePath: string): unknown {
+    try {
+        return JSON.parse(readFileSync(fileURLToPath(new URL(relativePath, import.meta.url)), 'utf8'));
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+        throw error;
+    }
+}
+
+const publishedDocument = readFromStudioRepo('../../../../../packages/api-specs/vertesia-openapi.json') as
+    | { components: { schemas: Record<string, Record<string, unknown>> } }
+    | undefined;
+const published = publishedDocument?.components.schemas ?? {};
+
+/**
+ * The published component minus the OpenAPI-only discriminator hint the bundler drops.
+ *
+ * Written out here rather than imported from the registry on purpose: reusing the production
+ * function to check the production function would make the comparison below pass by construction.
+ * The rule is small enough to state twice, and stating it twice is what makes it a gate.
+ */
+function withoutDiscriminatorHints(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(withoutDiscriminatorHints);
+    if (!value || typeof value !== 'object') return value;
+    const node = value as Record<string, unknown>;
+    const restated = node.discriminator !== undefined && node.properties === undefined;
+    return Object.fromEntries(
+        Object.entries(node)
+            .filter(([key]) => key !== 'discriminator' && !(restated && (key === 'type' || key === 'required')))
+            .map(([key, item]) => [key, withoutDiscriminatorHints(item)]),
+    );
+}
+
+function $defsOf(schema: unknown): unknown {
+    return (schema as { $defs: unknown }).$defs;
+}
+
+describe.skipIf(!publishedDocument)('gate — generated artifact = canonical component = published component', () => {
+    it('is the exact bundle the registry emits, so the artifact is compiled output', () => {
+        // Deep equality, not a spot check: the file is generated by `pnpm run gen:schemas` from this
+        // same function, so any difference means someone hand-edited it or forgot to regenerate.
+        expect(GeneratedIntakePolicySchema).toEqual(bundleCanonicalComponent('ContentTypeIntakePolicy'));
+    });
+
+    it('describes the same shape as the component the OpenAPI document publishes', () => {
+        // The artifact re-roots `#/components/schemas/X` to `#/$defs/X` so AJV and Monaco can compile
+        // it standalone. Undoing that is what makes the two directly comparable.
+        const { $defs, ...body } = GeneratedIntakePolicySchema as { $defs: Record<string, unknown> };
+        const rerooted = JSON.parse(JSON.stringify(body).replaceAll('#/$defs/', '#/components/schemas/'));
+        expect(rerooted).toEqual(withoutDiscriminatorHints(published.ContentTypeIntakePolicy));
+
+        // ...and every definition it carries is the published component of that name, so the bundle
+        // cannot describe a private variant of a shared type.
+        for (const [name, definition] of Object.entries($defs)) {
+            const asComponent = JSON.parse(JSON.stringify(definition).replaceAll('#/$defs/', '#/components/schemas/'));
+            expect(asComponent, `$defs.${name} disagrees with the published component`).toEqual(
+                withoutDiscriminatorHints(published[name]),
+            );
+        }
+    });
+
+    it('drops the discriminator hint the published component keeps, and only that', () => {
+        // The one place the artifact and the component are allowed to differ, pinned from both sides
+        // so neither can move alone. `synthesizeDiscriminator` restates `type` and `required` on the
+        // union node for the generated Java/Go clients; the node has no `properties`, and Gemini
+        // rejects the whole tool schema over it ("requires unspecified property '_option_id'") when
+        // the artifact reaches Vertex inside `create_or_update_type`'s input schema.
+        expect(published.ModelOptions).toMatchObject({
+            discriminator: { propertyName: '_option_id' },
+            type: 'object',
+            required: ['_option_id'],
+        });
+
+        const bundled = ($defsOf(GeneratedIntakePolicySchema) as Record<string, Record<string, unknown>>).ModelOptions;
+        expect(bundled.discriminator).toBeUndefined();
+        expect(bundled.required).toBeUndefined();
+        expect(bundled.type).toBeUndefined();
+        // The branches are what carried the contract all along, so nothing was validated away.
+        expect((bundled.oneOf as unknown[]).length).toBe(
+            ((published.ModelOptions as { oneOf: unknown[] }).oneOf ?? []).length,
+        );
+    });
+
+    it('registers the component the alias claims, under the id the alias name requires', () => {
+        expect(Object.keys(ApiSchemaComponents)).toContain('ContentTypeIntakePolicy');
+        assertType<Equals<ContentTypeIntakePolicy, (typeof ContentTypeIntakePolicySchema)['_zod']['output']>>(true);
+    });
+});
+
+/**
+ * Bodies that probe where the two validators could disagree.
+ *
+ * The gate above compares the artifact to the component, and both are produced by the SAME adapter
+ * from the SAME Zod schema — so any transform applied on the way out is invisible to it. That blind
+ * spot shipped once: an adapter pass stripped the bounds `z.int()` attaches for the JavaScript
+ * safe-integer range, on the reasoning that no JSON value could fall outside them. `1e20` does, and
+ * the Zod schema rejected it while the generated schema accepted it. Nothing in a
+ * schema-versus-schema comparison can see that; only running both validators over the same value can.
+ */
+const PROBES: unknown[] = [
+    // Numeric range, including the values that made the sentinel-stripping bug observable.
+    {},
+    { extraction: { max_pages: 1 } },
+    { extraction: { max_pages: 0 } },
+    { extraction: { max_pages: 2.5 } },
+    { extraction: { max_pages: 1e20 } },
+    { extraction: { max_pages: 2147483647 } },
+    { extraction: { max_pages: 2147483648 } },
+    { extraction: { max_pages: Number.MAX_SAFE_INTEGER + 1 } },
+    { extraction: { max_pages: -1 } },
+    { locate: { instructions: 'x', min_pages: 0 } },
+    { locate: { instructions: 'x', min_pages: -1 } },
+    { locate: { instructions: 'x', min_pages: 1e20 } },
+    { locate: { detail: 8 } },
+    { text_conversion: { render_dpi: 72 } },
+    { text_conversion: { render_dpi: 71 } },
+    { text_conversion: { render_dpi: 1e20 } },
+    { extraction: { verification: { threshold: 0 } } },
+    { extraction: { verification: { threshold: 1 } } },
+    { extraction: { verification: { threshold: 1.000001 } } },
+    { extraction: { verification: { max_retries: 1e20 } } },
+    { extraction: { vision: { max_image_tokens: 1e20, max_payload_mb: 1e20 } } },
+    { extraction: { grounding: { window_pages: 1e20, grid_cell_pt: 1e20 } } },
+    { extraction: { grounding: { hardness_threshold: 1e20 } } },
+    // Page ranges: length, element type, and element magnitude.
+    { extraction: { page_ranges: [[1, 2]] } },
+    { extraction: { page_ranges: [[-1, -1]] } },
+    { extraction: { page_ranges: [[1]] } },
+    { extraction: { page_ranges: [[1, 2, 3]] } },
+    { extraction: { page_ranges: [[1.5, 2]] } },
+    { extraction: { page_ranges: [[1e20, 2]] } },
+    // Nullability, unknown keys, and the enums.
+    { generate_toc: null },
+    { extraction: null },
+    { extraction: { max_pages: null } },
+    { grounded_extraction: { enabled: true } },
+    { locate: { instructions: 'x', dpi: 300 } },
+    { extraction: { scope: 'first-two' } },
+    { extraction: { vision: { default_detail: 'ultra' } } },
+    { default_view: 'pdf' },
+    { mode: 'agentic' },
+    // The execution config: closedness, the option union, the two enums.
+    { extraction: { config: { model: 'm' } } },
+    { extraction: { config: { temperature: 0.5 } } },
+    { extraction: { config: { http_timeout: { bodyTimeout: 1000 } } } },
+    { extraction: { config: { http_timeout: { socketTimeout: 1000 } } } },
+    { extraction: { config: { model_options: { _option_id: 'openai-text', temperature: 0.5 } } } },
+    { extraction: { config: { model_options: { temperature: 0.5 } } } },
+    { extraction: { config: { model_options: { _option_id: 'not-a-driver' } } } },
+    { extraction: { config: { run_data: 'STANDARD' } } },
+    { extraction: { config: { run_data: 'WHATEVER' } } },
+    { extraction: { config: { configMode: 'RUN_CONFIG_ONLY' } } },
+    // Wrong types where a shape is expected.
+    { extraction: 'nope' },
+    { embeddings: { text: 'yes' } },
+    { identification: { examples: 'not-a-list' } },
+];
+
+describe('gate — the artifact accepts exactly what the Zod schema accepts', () => {
+    it.each(PROBES.map((probe) => [JSON.stringify(probe), probe] as const))('agrees on %s', (_label, probe) => {
+        // The point of the migration is that ONE schema is enforced. Two validators built from it
+        // that disagree on a value means one of the consumers is enforcing something the source
+        // never said, which is the drift this whole exercise removes.
+        expect(validate(probe)).toBe(ContentTypeIntakePolicySchema.safeParse(probe).success);
+    });
+});
+
+describe.skipIf(!publishedDocument)('the fixture the generated Java and Go clients deserialize', () => {
+    // `openapi/fixtures/content-type-intake-policy.json` is read by
+    // `openapi/java/src/test/.../ContentTypeIntakePolicyDeserializationTest.java` and by
+    // `openapi/go/tests/intake_policy_deserialization_test.go`. Asserting it HERE is what stops it
+    // going stale: a schema change that the fixture no longer satisfies fails in this package,
+    // beside the schema, rather than in a client harness that only CI runs.
+    const fixture = readFromStudioRepo('../../../../../openapi/fixtures/content-type-intake-policy.json') ?? {};
+
+    it('is a policy the canonical schema and the generated artifact both accept', () => {
+        expect(ContentTypeIntakePolicySchema.safeParse(fixture).success).toBe(true);
+        expect(validate(fixture), errors()).toBe(true);
+    });
+
+    it('exercises the shapes the number -> integer correction changed', () => {
+        // The fields whose generated Java type moved from Double to Integer and whose Go type moved
+        // from float32 to int32. A fixture that omitted them would let the clients compile and
+        // deserialize while proving nothing about the change this batch makes.
+        const policy = fixture as ContentTypeIntakePolicy;
+        expect(policy.extraction?.max_pages).toBe(6);
+        expect(policy.extraction?.page_ranges).toEqual([
+            [1, 2],
+            [-1, -1],
+        ]);
+        expect(policy.text_conversion?.render_dpi).toBe(150);
+        expect(policy.extraction?.vision?.max_image_tokens).toBe(9000);
+        expect(policy.extraction?.grounding?.window_pages).toBe(4);
+        // ...and the discriminated union, which is what a Go oneOf decoder gets wrong when the
+        // discriminator is missing from the document.
+        expect(policy.extraction?.config?.model_options?._option_id).toBe('vertexai-claude');
+    });
+});
+
+describe('the TypeScript type says what the schema says', () => {
+    it('widens page ranges to number[][], which is what the component has always described', () => {
+        // `[number, number][]` is what the interface used to claim. The published component is
+        // `items: {type: integer}` with `minItems`/`maxItems` — a two-element ARRAY, not a tuple —
+        // because a Zod tuple emits `prefixItems`, which generated Java and Go clients read
+        // differently. The wire shape is unchanged; the SDK type is corrected to match it.
+        assertType<Equals<IntakePageRanges, number[][]>>(true);
+        expect(validate({ extraction: { page_ranges: [[1, 2]] } }), errors()).toBe(true);
+    });
+
+    it('keeps the two type refs’ default_view in step with the policy', () => {
+        // Those refs spell the union out rather than writing `ContentTypeIntakePolicy['default_view']`,
+        // because indexing into a canonical alias makes the generator DROP the property instead of
+        // failing. This is what stops the restatement from drifting.
+        assertType<
+            Equals<
+                NonNullable<ContentObjectTypeRef['default_view']>,
+                NonNullable<ContentTypeIntakePolicy['default_view']>
+            >
+        >(true);
+    });
+});
+
+describe('parity with the hand-written AJV schema it replaces', () => {
+    it('still accepts a full policy across every block', () => {
+        const policy: ContentTypeIntakePolicy = {
+            mode: 'programmatic',
+            identification: { guidance: 'Investor reports' },
+            locate: { instructions: 'allocation tables', detail: 8, min_pages: 10 },
+            text_conversion: { method: 'llm', scope: 'located', render_dpi: 150 },
+            extraction: {
+                source: 'vision',
+                page_ranges: [
+                    [1, 2],
+                    [-1, -1],
+                ],
+                max_pages: 6,
+                vision: { default_detail: 'high', max_image_tokens: 9000, max_payload_mb: 12 },
+                verification: { threshold: 0.7, max_retries: 2 },
+                grounding: {
+                    enabled: true,
+                    max_pages: 12,
+                    hardness_threshold: 0.5,
+                    config: { model: 'claude-sonnet-4-5' },
+                    review: { threshold: 0.7, coverage_threshold: 0.2 },
+                },
+            },
+            embeddings: { text: true, properties: true },
+            default_view: 'pdf',
+        };
+        expect(validate(policy), errors()).toBe(true);
+    });
+
+    it('keeps every numeric bound the hand-written schema enforced', () => {
+        // These were NOT in the published component — the interface carried no `@minimum` tags — so
+        // converting to Zod dropped all eighteen of them until this test caught it. They are restored
+        // in the schema, which means the document now publishes constraints the server has enforced
+        // all along.
+        expect(validate({ locate: { instructions: 'x', min_pages: -1 } })).toBe(false);
+        expect(validate({ text_conversion: { render_dpi: 71 } })).toBe(false);
+        expect(validate({ extraction: { max_pages: 0 } })).toBe(false);
+        expect(validate({ extraction: { verification: { threshold: 1.2 } } })).toBe(false);
+        expect(validate({ extraction: { verification: { max_retries: -1 } } })).toBe(false);
+        expect(validate({ extraction: { vision: { max_image_tokens: 0 } } })).toBe(false);
+        expect(validate({ extraction: { vision: { max_payload_mb: 0 } } })).toBe(false);
+        expect(validate({ extraction: { vision: { max_pages_per_call: 0 } } })).toBe(false);
+        expect(validate({ extraction: { grounding: { max_pages: 0 } } })).toBe(false);
+        expect(validate({ extraction: { grounding: { window_pages: 0 } } })).toBe(false);
+        expect(validate({ extraction: { grounding: { grid_cell_pt: 0 } } })).toBe(false);
+        expect(validate({ extraction: { grounding: { hardness_threshold: -0.1 } } })).toBe(false);
+        expect(validate({ extraction: { grounding: { min_citation_density: 1.1 } } })).toBe(false);
+        expect(validate({ extraction: { grounding: { review: { threshold: 1.1 } } } })).toBe(false);
+        expect(validate({ extraction: { grounding: { review: { coverage_threshold: -0.1 } } } })).toBe(false);
+    });
+
+    it('keeps the page and DPI counters integral', () => {
+        // `type: 'integer'`, which the published component also never stated. A fractional page cap
+        // was rejected before this conversion and is rejected after it.
+        expect(validate({ extraction: { max_pages: 2.5 } })).toBe(false);
+        expect(validate({ text_conversion: { render_dpi: 150.5 } })).toBe(false);
+        expect(validate({ extraction: { page_ranges: [[1.5, 2]] } })).toBe(false);
+        expect(validate({ extraction: { page_ranges: [[1]] } })).toBe(false);
+        expect(validate({ locate: { instructions: 'x', min_pages: 8.5 } })).toBe(false);
+    });
+
+    it('keeps rejecting unknown keys and the obsolete root block', () => {
+        expect(validate({ grounded_extraction: { enabled: true } })).toBe(false);
+        expect(validate({ locate: { instructions: 'x', dpi: 300 } })).toBe(false);
+        expect(validate({ extraction: { vision: { default_detail: 'ultra' } } })).toBe(false);
+    });
+});
+
+describe('runtime tightenings — recorded as operation 25 of the 1.5 runbook', () => {
+    it('rejects an explicit null where the hand-written schema accepted one', () => {
+        // The replaced schema carried `nullable: true` on 112 subschemas and AJV honours that keyword
+        // for OpenAPI compatibility, so 101 of them accepted `null` — which neither the TypeScript
+        // type nor the published component has ever allowed. The fields are optional, not nullable.
+        expect(validate({ generate_toc: null })).toBe(false);
+        expect(validate({ rendering_template: null })).toBe(false);
+        expect(validate({ extraction: { max_pages: null } })).toBe(false);
+        expect(validate({ extraction: null })).toBe(false);
+        // Omission is still how you say "inherit", which is what every one of those fields meant.
+        expect(validate({}), errors()).toBe(true);
+        expect(validate({ extraction: {} }), errors()).toBe(true);
+    });
+
+    it('closes the execution config, which the published component already described closed', () => {
+        // `config` was `additionalProperties: true` in the hand-written schema while
+        // `InteractionExecutionConfiguration` has always been published closed. A stored policy
+        // carrying an undeclared key there is now rejected at write time.
+        expect(ApiSchemaComponents.InteractionExecutionConfiguration.additionalProperties).toBe(false);
+        expect(validate({ extraction: { config: { model: 'claude-sonnet-4-5' } } }), errors()).toBe(true);
+        expect(validate({ extraction: { config: { temperature: 0.5 } } })).toBe(false);
+        expect(validate({ extraction: { config: { http_timeout: { socketTimeout: 1000 } } } })).toBe(false);
+    });
+
+    it('validates model_options against the union instead of accepting any object', () => {
+        // Same class: `model_options` was `{type: object, additionalProperties: true}` in the
+        // hand-written schema and `$ref: ModelOptions` in the published component. It now has to name
+        // a driver through `_option_id`, which is the discriminator generated clients already use.
+        expect(ApiSchemaComponents.ContentTypeIntakePolicy).toBeDefined();
+        expect(
+            validate({
+                extraction: { config: { model_options: { _option_id: 'openai-text', temperature: 0.5 } } },
+            }),
+            errors(),
+        ).toBe(true);
+        expect(validate({ extraction: { config: { model_options: { temperature: 0.5 } } } })).toBe(false);
+        expect(validate({ extraction: { config: { model_options: { _option_id: 'not-a-driver' } } } })).toBe(false);
+        // The empty object is rejected for the same reason, which is why nothing may PUT it on the
+        // wire — see `normalizeModelOptions`, which drops an options bag with no options in it.
+        expect(validate({ extraction: { config: { model_options: {} } } })).toBe(false);
+    });
+
+    it('constrains the two config enums that were unconstrained strings', () => {
+        expect(validate({ extraction: { config: { run_data: 'STANDARD' } } }), errors()).toBe(true);
+        expect(validate({ extraction: { config: { run_data: 'WHATEVER' } } })).toBe(false);
+        expect(validate({ extraction: { config: { configMode: 'RUN_CONFIG_ONLY' } } }), errors()).toBe(true);
+        expect(validate({ extraction: { config: { configMode: 'WHATEVER' } } })).toBe(false);
+    });
+});
+
+describe('the five content-type shapes are composed, not repeated', () => {
+    const properties = (name: string) =>
+        Object.keys((ApiSchemaComponents[name] as { properties: Record<string, unknown> }).properties);
+    const property = (name: string, key: string) =>
+        (ApiSchemaComponents[name] as { properties: Record<string, JsonObject> }).properties[key];
+
+    it('gives every shape the same definition for a shared field', () => {
+        // The drift this guards: five hand-transcribed copies of `table_layout` could disagree about
+        // its item type or its description and nothing would notice. They come from one dictionary now.
+        const shapes = [
+            'ContentObjectTypeItem',
+            'ContentObjectType',
+            'ContentObjectTypeCatalogEntry',
+            'InCodeTypeDefinition',
+            'CreateContentObjectTypePayload',
+        ];
+        for (const field of ['table_layout', 'object_schema', 'strict_mode', 'intake', 'editing', 'status']) {
+            const rendered = shapes.map((shape) => JSON.stringify(property(shape, field)));
+            expect(new Set(rendered).size, `${field} differs across the content-type shapes`).toBe(1);
+        }
+    });
+
+    it('keeps the published property order, which composition must not reshuffle', () => {
+        // Order is contract: it decides the order of the generated clients' constructor arguments and
+        // model fields. The five orders differ because they were derived from five different types.
+        expect(properties('ContentObjectTypeItem')).toEqual(properties('ContentObjectType'));
+        expect(properties('ContentObjectTypeCatalogEntry').slice(0, 11)).toEqual(properties('InCodeTypeDefinition'));
+        expect(properties('CreateContentObjectTypePayload')).toEqual([
+            'status',
+            'is_chunkable',
+            'intake',
+            'editing',
+            'table_layout',
+            'object_schema',
+            'strict_mode',
+            'name',
+            'description',
+            'tags',
+        ]);
+    });
+
+    it('keeps the audit fields required on a stored type and optional in the catalog', () => {
+        // Not a detail: a catalog entry may be an in-code type contributed by a plugin, which nobody
+        // created and nobody has modified. Requiring the four there would reject a legitimate entry.
+        const audit = ['updated_by', 'created_by', 'created_at', 'updated_at'];
+        const required = (name: string) => (ApiSchemaComponents[name] as { required?: string[] }).required ?? [];
+
+        expect(required('ContentObjectTypeItem')).toEqual(expect.arrayContaining(audit));
+        expect(required('ContentObjectType')).toEqual(expect.arrayContaining(audit));
+        for (const field of audit) {
+            expect(required('ContentObjectTypeCatalogEntry')).not.toContain(field);
+            expect(property('ContentObjectTypeCatalogEntry', field)).toEqual({ type: 'string' });
+        }
+    });
+
+    it('accepts a catalog entry for an in-code type that has no audit trail', () => {
+        expect(
+            validateApiResponse('ContentObjectTypeCatalogEntry', {
+                id: 'sys:Invoice',
+                name: 'Invoice',
+                is_chunkable: false,
+            }).valid,
+        ).toBe(true);
+    });
+});