@qvac/sdk 0.14.1 → 0.16.0

package/dist/scripts/contract/build-contract.js

@@ -0,0 +1,620 @@
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import prettier from 'prettier';
+import { requestSchema, responseSchema } from '../../schemas/common.js';
+import { methodShapes } from '../../server/rpc/method-shapes.js';
+import { constantsRegistry } from '../../schemas/constants-registry.js';
+import { buildModelsRegistry } from './build-models-registry.js';
+import { buildModelTypeMaps } from './build-model-type-maps.js';
+import { buildErrorCodes } from './build-error-codes.js';
+export const contractDir = new URL('../../contract/', import.meta.url);
+export const callShapeByHandlerType = {
+    reply: 'request-reply',
+    stream: 'server-stream',
+    duplex: 'duplex'
+};
+/**
+ * Wire `type` literal(s) of a request/response schema. Union members all
+ * carry the same literal (one method can have several request variants),
+ * pipes are read on their input side, intersections on both sides.
+ */
+function wireTypesOf(schema) {
+    if (schema instanceof z.ZodObject) {
+        const typeField = schema.shape['type'];
+        if (typeField instanceof z.ZodLiteral) {
+            return Array.from(typeField.values).filter(function (value) {
+                return typeof value === 'string';
+            });
+        }
+        return [];
+    }
+    if (schema instanceof z.ZodUnion) {
+        const nested = schema.options.flatMap(function (option) {
+            return wireTypesOf(option);
+        });
+        return [...new Set(nested)];
+    }
+    if (schema instanceof z.ZodPipe) {
+        return wireTypesOf(schema.in);
+    }
+    if (schema instanceof z.ZodIntersection) {
+        const nested = [
+            ...wireTypesOf(schema.def.left),
+            ...wireTypesOf(schema.def.right)
+        ];
+        return [...new Set(nested)];
+    }
+    return [];
+}
+function wireTypeOf(schema, context) {
+    const types = wireTypesOf(schema);
+    if (types.length !== 1) {
+        throw new Error(`Expected exactly one wire "type" literal for ${context}, found: [${types.join(', ')}]`);
+    }
+    return types[0];
+}
+function assertNoRefs(value, defName) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertNoRefs(item, defName);
+        return;
+    }
+    if (value !== null && typeof value === 'object') {
+        for (const [key, child] of Object.entries(value)) {
+            if (key === '$ref') {
+                throw new Error(`Schema for "${defName}" emitted a $ref (${String(child)}); ` +
+                    'nesting it under $defs would break the pointer. Extend build-contract.ts to re-root refs.');
+            }
+            assertNoRefs(child, defName);
+        }
+    }
+}
+function mergeObjectSchemaParts(parts, defName) {
+    const properties = {};
+    const required = [];
+    for (const part of parts) {
+        if (part['type'] !== undefined && part['type'] !== 'object') {
+            throw new Error(`Cannot merge a non-object schema member while flattening "${defName}"`);
+        }
+        for (const [key, value] of Object.entries(part['properties'] ?? {})) {
+            if (key in properties && JSON.stringify(properties[key]) !== JSON.stringify(value)) {
+                throw new Error(`Conflicting definitions for property "${key}" while flattening "${defName}"`);
+            }
+            properties[key] = value;
+        }
+        for (const name of part['required'] ?? []) {
+            if (!required.includes(name))
+                required.push(name);
+        }
+    }
+    return { type: 'object', properties, required };
+}
+/**
+ * Flattens `allOf: [commonFields, { oneOf/anyOf: [...variants] }]` (Zod's
+ * `.and()` of an object with a discriminated union) into a plain
+ * `oneOf`/`anyOf` with `commonFields` merged into every variant.
+ *
+ * Needed because JSON-Schema-consuming codegen (verified against
+ * datamodel-code-generator, the standard JSON-Schema -> pydantic tool) does
+ * not merge `allOf` branches when one of them is itself a union: it silently
+ * keeps only the first branch under the schema's title, dropping every
+ * variant-specific field. `allOf`-of-a-union is valid JSON Schema, but this
+ * is a known rough edge across JSON-Schema tooling generally, so flattening
+ * it here makes the contract more robust for every consumer, not a
+ * Python-specific workaround.
+ *
+ * Scoped to the one shape currently in use (exactly one `allOf` branch is a
+ * union, the rest are plain object schemas): anything else throws instead of
+ * silently emitting a schema some consumer will mis-generate from.
+ */
+function flattenAllOfWithUnion(json, defName) {
+    const allOf = json['allOf'];
+    if (!Array.isArray(allOf))
+        return json;
+    const isUnionMember = function (member) {
+        return (member !== null &&
+            typeof member === 'object' &&
+            (Array.isArray(member['oneOf']) ||
+                Array.isArray(member['anyOf'])));
+    };
+    const unionMembers = allOf.filter(isUnionMember);
+    const plainMembers = allOf.filter(function (member) {
+        return !isUnionMember(member);
+    });
+    if (unionMembers.length !== 1) {
+        throw new Error(`Schema for "${defName}" uses allOf with ${unionMembers.length} union branches; ` +
+            'only the single-union-branch shape is handled. Extend flattenAllOfWithUnion in build-contract.ts.');
+    }
+    const unionMember = unionMembers[0];
+    const unionKey = Array.isArray(unionMember['oneOf']) ? 'oneOf' : 'anyOf';
+    const arms = unionMember[unionKey];
+    const flattened = { ...json };
+    delete flattened['allOf'];
+    flattened[unionKey] = arms.map(function (arm) {
+        return mergeObjectSchemaParts([...plainMembers, arm], defName);
+    });
+    return flattened;
+}
+function isSchemaObject(node) {
+    return node !== null && typeof node === 'object' && !Array.isArray(node);
+}
+function unionArmsOf(node) {
+    if (Array.isArray(node['oneOf']))
+        return node['oneOf'];
+    if (Array.isArray(node['anyOf']))
+        return node['anyOf'];
+    return undefined;
+}
+/**
+ * Collapses `oneOf`/`anyOf` arrays that carry exactly one arm into that arm
+ * directly, recursively from the leaves up. A single-arm union discriminates
+ * nothing, so naming it as a union (wrapper title + arm title) forces the
+ * arm into a name distinct from a wrapper it's identical to — e.g.
+ * `reloadConfigRequestSchema = z.union([reloadConfigWhisperRequestSchema])`
+ * produced both a `ReloadConfigRequest` (the wrapper) and a
+ * `ReloadConfigRequest2` (the lone arm) for what is really one type.
+ * Collapsing first means there's only ever one node here for titling to see.
+ * The wrapper's own explicit `title` (its `.meta()`), if any, wins over the
+ * arm's — it's the intentional public name for the schema export.
+ */
+function collapseSingleMemberUnions(node) {
+    if (!isSchemaObject(node))
+        return node;
+    const properties = node['properties'];
+    if (isSchemaObject(properties)) {
+        for (const key of Object.keys(properties)) {
+            properties[key] = collapseSingleMemberUnions(properties[key]);
+        }
+    }
+    if (node['items'] !== undefined) {
+        node['items'] = collapseSingleMemberUnions(node['items']);
+    }
+    if (isSchemaObject(node['additionalProperties'])) {
+        node['additionalProperties'] = collapseSingleMemberUnions(node['additionalProperties']);
+    }
+    const unionKey = Array.isArray(node['oneOf'])
+        ? 'oneOf'
+        : Array.isArray(node['anyOf'])
+            ? 'anyOf'
+            : undefined;
+    if (!unionKey)
+        return node;
+    const arms = node[unionKey].map(collapseSingleMemberUnions);
+    if (arms.length !== 1) {
+        node[unionKey] = arms;
+        return node;
+    }
+    const arm = arms[0];
+    const wrapperTitle = typeof node['title'] === 'string' ? node['title'] : undefined;
+    const wrapperRest = { ...node };
+    delete wrapperRest[unionKey];
+    if (!isSchemaObject(arm))
+        return wrapperTitle ? wrapperRest : arm;
+    const merged = { ...wrapperRest, ...arm };
+    if (wrapperTitle)
+        merged['title'] = wrapperTitle;
+    return merged;
+}
+function constValueOf(arm, key) {
+    const properties = arm['properties'];
+    const field = isSchemaObject(properties) ? properties[key] : undefined;
+    return isSchemaObject(field) && typeof field['const'] === 'string' ? field['const'] : undefined;
+}
+/**
+ * Property key that best discriminates a set of sibling union arms: the
+ * `const` string field, wherever present, that splits the arms into the most
+ * distinct groups — counting "arms with no const for this key at all" as one
+ * more group (they'll be disambiguated some other way; see `nameUnionArms`).
+ * Picks the *best* key rather than requiring perfection — two shortcomings
+ * otherwise cause bad names:
+ *
+ * - Requiring every arm to carry the key: `loadModel`'s custom-plugin
+ *   catch-all arm has no `modelType` const, so demanding full coverage threw
+ *   away `modelType` for the other 11 arms too.
+ * - Requiring the value to never repeat: `completionStream`'s event union
+ *   has two arms both typed `completionDone` (success vs. error) — demanding
+ *   perfect uniqueness rejected `type` for all 8 events, even though it
+ *   cleanly separates the other 6. `nameUnionArms` recurses into the
+ *   colliding pair to find a secondary key (`stopReason`) instead.
+ *
+ * Also deliberately not a fixed guess-list of names (`type`/`operation`/...):
+ * the wire method discriminator (`type`) is IDENTICAL across every arm of a
+ * single method's own operation union (e.g. every `rag` arm has
+ * `type: 'rag'`), so guessing by name picked the one field that never
+ * discriminates anything and produced `RagRequestRag`, `RagRequestRag2`, ...
+ * A key where every arm lands in one single group is rejected outright —
+ * it's exactly this "same value everywhere" (or "no arm has it") case.
+ */
+function pickDiscriminatorKey(arms) {
+    const candidateKeys = new Set();
+    for (const arm of arms) {
+        const properties = arm['properties'];
+        if (isSchemaObject(properties)) {
+            for (const key of Object.keys(properties))
+                candidateKeys.add(key);
+        }
+    }
+    let bestKey;
+    let bestGroupCount = 1; // a key producing only 1 group discriminates nothing
+    for (const key of candidateKeys) {
+        const values = new Set();
+        let anyMissing = false;
+        for (const arm of arms) {
+            const value = constValueOf(arm, key);
+            if (value === undefined)
+                anyMissing = true;
+            else
+                values.add(value);
+        }
+        const groupCount = values.size + (anyMissing ? 1 : 0);
+        if (groupCount > bestGroupCount) {
+            bestKey = key;
+            bestGroupCount = groupCount;
+        }
+    }
+    return bestKey;
+}
+function ensureUniqueTitle(base, seenTitles) {
+    if (!seenTitles.has(base)) {
+        seenTitles.add(base);
+        return base;
+    }
+    let suffix = 2;
+    while (seenTitles.has(`${base}${suffix}`))
+        suffix++;
+    const unique = `${base}${suffix}`;
+    seenTitles.add(unique);
+    return unique;
+}
+/** Whether a schema node is itself substantial enough to need a title: an
+ * object, an enum, or a nested union (whose own arms will need names) —
+ * as opposed to a bare scalar (`{type: 'string'}`) or `{}` ("any"), which
+ * never get titled regardless of position. */
+function needsOwnTitle(node) {
+    if (!isSchemaObject(node))
+        return false;
+    if (unionArmsOf(node))
+        return true;
+    const isEnum = Array.isArray(node['enum']);
+    const isObject = node['type'] === 'object' || isSchemaObject(node['properties']);
+    const hasConst = node['const'] !== undefined;
+    return (isEnum || isObject) && !hasConst;
+}
+/**
+ * Names each arm of a union: by the shared discriminator's value when the
+ * arms have one in common; else, if at most one arm actually needs a title
+ * (e.g. `string | { repeats: number }` — only the object arm does), that one
+ * arm gets the bare prefix with no suffix, since there's nothing to
+ * disambiguate; only when neither applies does it fall back to positional
+ * naming (1-based: `Foo1`, `Foo2`, ...).
+ */
+function nameUnionArms(arms, namePrefix) {
+    if (arms.length <= 1) {
+        return arms.map(function () {
+            return namePrefix;
+        });
+    }
+    const key = pickDiscriminatorKey(arms);
+    if (!key) {
+        if (arms.filter(needsOwnTitle).length <= 1) {
+            return arms.map(function () {
+                return namePrefix;
+            });
+        }
+        return arms.map(function (_arm, index) {
+            return `${namePrefix}${index + 1}`;
+        });
+    }
+    // Group arms by their value for `key` (arms with no const for `key` share
+    // the `undefined` group). A key is only ever picked when it produces more
+    // than one group (see pickDiscriminatorKey), so every group here is
+    // strictly smaller than `arms` — groups with more than one member recurse
+    // to find a secondary discriminator instead of falling straight to
+    // `ensureUniqueTitle`'s numeric bump. This is what turns two arms sharing
+    // `type: 'completionDone'` into `...CompletionDoneError` (has a `stopReason`
+    // const) and bare `...CompletionDone` (the lone arm left without one)
+    // instead of `...CompletionDone` / `...CompletionDone2`.
+    const groupOrder = [];
+    const groups = new Map();
+    arms.forEach(function (arm, index) {
+        const value = constValueOf(arm, key);
+        if (!groups.has(value)) {
+            groupOrder.push(value);
+            groups.set(value, []);
+        }
+        groups.get(value)?.push(index);
+    });
+    const names = new Array(arms.length);
+    for (const value of groupOrder) {
+        const indexes = groups.get(value);
+        const groupPrefix = value !== undefined ? `${namePrefix}${toPascalCase(value)}` : namePrefix;
+        if (indexes.length === 1) {
+            names[indexes[0]] = groupPrefix;
+            continue;
+        }
+        const subNames = nameUnionArms(indexes.map(function (index) {
+            return arms[index];
+        }), groupPrefix);
+        indexes.forEach(function (armIndex, i) {
+            names[armIndex] = subNames[i];
+        });
+    }
+    return names;
+}
+/**
+ * Assigns a `title` to `node` (unless it already has one) and recurses into
+ * its properties/items/union arms, naming each by its property key or (for
+ * discriminated union arms) the arm's discriminator value — e.g.
+ * `completionStream.response`'s event union gets
+ * `CompletionStreamResponseEventsItemContentDelta` instead of a bare `Events3`.
+ *
+ * Without this, nested/inline Zod schemas reach codegen (verified against
+ * datamodel-code-generator, a JSON-Schema-to-pydantic tool) as
+ * positionally-numbered classes (`Stats13`, `Events7`) with no indication of
+ * what they represent.
+ *
+ * If `node` already carries a `title` (a schema author's explicit Zod
+ * `.meta({ title: ... })`, e.g. `FinetuneRunRequest`), that title wins over
+ * `namePrefix` — both for `node` itself and as the prefix for its own
+ * children — instead of being silently discarded the moment `node` also
+ * happens to be a union wrapper.
+ */
+function titleSchemaNode(node, namePrefix, seenTitles) {
+    if (!isSchemaObject(node))
+        return;
+    const existingTitle = typeof node['title'] === 'string' ? node['title'] : undefined;
+    if (existingTitle)
+        seenTitles.add(existingTitle);
+    const arms = unionArmsOf(node);
+    if (arms) {
+        const effectivePrefix = existingTitle ?? namePrefix;
+        const armNames = nameUnionArms(arms, effectivePrefix);
+        arms.forEach(function (arm, index) {
+            titleSchemaNode(arm, armNames[index], seenTitles);
+        });
+        return;
+    }
+    // If namePrefix collided with an already-assigned title, ensureUniqueTitle
+    // bumps it (e.g. `...CompletionDone` -> `...CompletionDone2`). Children
+    // must be prefixed with that *final* title, not the pre-bump namePrefix —
+    // otherwise a child two levels down silently collides with an unrelated
+    // sibling's identically-(pre-bump-)named child instead of its own.
+    const assignedTitle = needsOwnTitle(node) && !existingTitle ? ensureUniqueTitle(namePrefix, seenTitles) : undefined;
+    if (assignedTitle)
+        node['title'] = assignedTitle;
+    const effectivePrefix = existingTitle ?? assignedTitle ?? namePrefix;
+    const properties = node['properties'];
+    if (isSchemaObject(properties)) {
+        for (const [key, propSchema] of Object.entries(properties)) {
+            titleSchemaNode(propSchema, `${effectivePrefix}${toPascalCase(key)}`, seenTitles);
+        }
+    }
+    if (node['items'] !== undefined) {
+        titleSchemaNode(node['items'], `${effectivePrefix}Item`, seenTitles);
+    }
+    if (isSchemaObject(node['additionalProperties'])) {
+        titleSchemaNode(node['additionalProperties'], `${effectivePrefix}Value`, seenTitles);
+    }
+}
+/** Entry point for a def's root: the root already has `rootTitle` (assigned
+ * by the caller), so only its children need naming — recursing straight into
+ * `titleSchemaNode` would treat the root itself as untitled. */
+function titleNestedSchemas(root, rootTitle, seenTitles) {
+    const arms = unionArmsOf(root);
+    if (arms) {
+        const armNames = nameUnionArms(arms, rootTitle);
+        arms.forEach(function (arm, index) {
+            titleSchemaNode(arm, armNames[index], seenTitles);
+        });
+        return;
+    }
+    const properties = root['properties'];
+    if (isSchemaObject(properties)) {
+        for (const [key, propSchema] of Object.entries(properties)) {
+            titleSchemaNode(propSchema, `${rootTitle}${toPascalCase(key)}`, seenTitles);
+        }
+    }
+    if (root['items'] !== undefined) {
+        titleSchemaNode(root['items'], `${rootTitle}Item`, seenTitles);
+    }
+    if (isSchemaObject(root['additionalProperties'])) {
+        titleSchemaNode(root['additionalProperties'], `${rootTitle}Value`, seenTitles);
+    }
+}
+export function toWireJsonSchema(schema, io, defName) {
+    const json = z.toJSONSchema(schema, {
+        target: 'draft-2020-12',
+        io,
+        unrepresentable: 'any'
+    });
+    delete json['$schema'];
+    const flattened = flattenAllOfWithUnion(json, defName);
+    const collapsed = collapseSingleMemberUnions(flattened);
+    assertNoRefs(collapsed, defName);
+    return collapsed;
+}
+function collectByWireType(options, side) {
+    const byType = new Map();
+    for (const [index, option] of options.entries()) {
+        const schema = option;
+        const wireType = wireTypeOf(schema, `${side} union member #${index}`);
+        if (byType.has(wireType)) {
+            throw new Error(`Duplicate ${side} schema for wire type "${wireType}"`);
+        }
+        byType.set(wireType, schema);
+    }
+    return byType;
+}
+function refTo(defName) {
+    return { $ref: `#/$defs/${defName}` };
+}
+/**
+ * PascalCase class name for a wire type, e.g. `loadModel` -> `LoadModel`,
+ * `finetune:progress` -> `FinetuneProgress`. Without a `title`, JSON Schema
+ * -> codegen (e.g. datamodel-code-generator) falls back to positional names
+ * like `Request1Model11` for nested unions — verified empirically against
+ * the actual generator, not assumed.
+ */
+function toPascalCase(name) {
+    return name
+        .split(/[:\-_]/)
+        .map(function (part) {
+        return part.length > 0 ? part.charAt(0).toUpperCase() + part.slice(1) : part;
+    })
+        .join('');
+}
+function classTitleFor(name, suffix) {
+    return `${toPascalCase(name)}${suffix}`;
+}
+/**
+ * The 4 methods that can switch from a plain unary reply to a stream of
+ * responses when the caller opts in (`request.withProgress === true`):
+ * progress events and the final reply both arrive as stream frames,
+ * distinguished only by each payload's own `type` — see
+ * `server/rpc/handler-selection.ts` (`handlerSupportsProgress`) and
+ * `server/rpc/handler-registry.ts` for the source of truth this mirrors.
+ *
+ * `rag` and `finetune` gate progress further on the request's `operation`
+ * (see `ragSupportsProgress`/`finetuneSupportsProgress` in
+ * `handler-registry.ts`) — `condition` spells out that extra check so a
+ * contract consumer doesn't have to special-case it separately.
+ */
+const progressByMethod = {
+    loadModel: { condition: 'request.withProgress === true', responseType: 'modelProgress' },
+    downloadAsset: { condition: 'request.withProgress === true', responseType: 'modelProgress' },
+    rag: {
+        condition: "request.withProgress === true && ['ingest', 'saveEmbeddings', 'reindex'].includes(request.operation)",
+        responseType: 'rag:progress'
+    },
+    finetune: {
+        condition: "request.withProgress === true && ['start', 'resume', undefined].includes(request.operation)",
+        responseType: 'finetune:progress'
+    }
+};
+export function buildContract() {
+    const methodNames = Object.keys(methodShapes).sort();
+    const requestByType = collectByWireType(requestSchema.options, 'request');
+    const responseByType = collectByWireType(responseSchema.options, 'response');
+    for (const name of methodNames) {
+        if (!requestByType.has(name)) {
+            throw new Error(`Method "${name}" has no request schema in the request union`);
+        }
+        if (!responseByType.has(name)) {
+            throw new Error(`Method "${name}" has no response schema in the response union`);
+        }
+    }
+    for (const wireType of requestByType.keys()) {
+        if (!methodNames.includes(wireType)) {
+            throw new Error(`Request schema "${wireType}" has no entry in methodShapes`);
+        }
+    }
+    const responseTypes = [...responseByType.keys()].sort();
+    for (const [methodName, progress] of Object.entries(progressByMethod)) {
+        if (!responseByType.has(progress.responseType)) {
+            throw new Error(`progressByMethod["${methodName}"] points at response type "${progress.responseType}", ` +
+                'which has no schema in the response union');
+        }
+    }
+    const defs = {
+        request: {
+            title: 'AnyRequest',
+            description: 'Any request accepted by the server, in wire (pre-parse) shape.',
+            anyOf: methodNames.map(function (name) {
+                return refTo(`${name}.request`);
+            })
+        },
+        response: {
+            title: 'AnyResponse',
+            description: 'Any response emitted by the server, including progress updates and error envelopes.',
+            anyOf: responseTypes.map(function (type) {
+                return refTo(`${type}.response`);
+            })
+        }
+    };
+    const defEntries = [];
+    for (const [type, schema] of requestByType) {
+        defEntries.push([`${type}.request`, schema, 'input', classTitleFor(type, 'Request')]);
+    }
+    for (const [type, schema] of responseByType) {
+        defEntries.push([`${type}.response`, schema, 'output', classTitleFor(type, 'Response')]);
+    }
+    // Public constants (@/schemas/constants-registry), merged into the same
+    // $defs as every request/response type via the same z.toJSONSchema call —
+    // not a separate artifact. `x-enum-varnames` preserves each entry's
+    // original key names (`ModelType.llamacppCompletion`, `PluginId.LLM`, ...)
+    // through codegen; plain JSON Schema `enum:` only carries values.
+    const constantVarNames = new Map();
+    for (const [name, schema] of Object.entries(constantsRegistry)) {
+        const defName = `constants.${name}`;
+        defEntries.push([defName, schema, 'output', name]);
+        constantVarNames.set(defName, Object.keys(schema.enum));
+    }
+    defEntries.sort(function (a, b) {
+        return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+    });
+    // Seed with every top-level title up front so nested-schema titles (assigned
+    // below, per def) can never collide with a top-level def title regardless
+    // of iteration order.
+    const seenTitles = new Set([
+        'AnyRequest',
+        'AnyResponse',
+        ...defEntries.map((entry) => entry[3])
+    ]);
+    for (const [defName, schema, io, title] of defEntries) {
+        const wireSchema = toWireJsonSchema(schema, io, defName);
+        titleNestedSchemas(wireSchema, title, seenTitles);
+        const varNames = constantVarNames.get(defName);
+        defs[defName] = {
+            title,
+            ...wireSchema,
+            ...(varNames && { 'x-enum-varnames': varNames })
+        };
+    }
+    const manifest = {
+        methods: methodNames.map(function (name) {
+            const progress = progressByMethod[name];
+            return {
+                name,
+                callShape: callShapeByHandlerType[methodShapes[name]],
+                requestSchema: `schema.json#/$defs/${name}.request`,
+                responseSchema: `schema.json#/$defs/${name}.response`,
+                ...(progress && {
+                    progress: {
+                        condition: progress.condition,
+                        responseSchema: `schema.json#/$defs/${progress.responseType}.response`
+                    }
+                })
+            };
+        })
+    };
+    const schemaDocument = {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        title: '@qvac/sdk wire contract',
+        description: 'Generated from the SDK Zod schemas by `bun run contract:export`. Do not edit by hand. ' +
+            'Requests use the schema input shape, responses the output shape; runtime-only ' +
+            'refinements and transforms stay server-side.',
+        $defs: defs
+    };
+    return { schemaDocument, manifest };
+}
+async function formatJson(value, fileName) {
+    const filePath = fileURLToPath(new URL(fileName, contractDir));
+    const config = await prettier.resolveConfig(filePath);
+    return prettier.format(JSON.stringify(value, null, 2), {
+        ...config,
+        parser: 'json'
+    });
+}
+export async function renderContractFiles() {
+    const { schemaDocument, manifest } = buildContract();
+    const modelsRegistry = buildModelsRegistry();
+    const modelTypeMaps = buildModelTypeMaps();
+    const errorCodes = buildErrorCodes();
+    return {
+        'schema.json': await formatJson(schemaDocument, 'schema.json'),
+        'manifest.json': await formatJson(manifest, 'manifest.json'),
+        'models.json': await formatJson(modelsRegistry, 'models.json'),
+        'model-type-maps.json': await formatJson(modelTypeMaps, 'model-type-maps.json'),
+        'error-codes.json': await formatJson(errorCodes, 'error-codes.json')
+    };
+}

package/dist/scripts/contract/build-error-codes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * JSON export of the SDK error-code registries (name → numeric code) for the
+ * server, client, and registry error families. The Python client's typed
+ * error classes and its RPC-boundary reconstructor read these instead of
+ * hand-copying the numbers, so a code added or renamed on the SDK side surfaces
+ * as a `contract:check` / `generate.py --check` failure rather than a Python
+ * client that silently can't reconstruct a server error.
+ *
+ * A separate artifact from schema.json, like models.json / model-type-maps.json.
+ */
+export interface ErrorCodes {
+    server: Record<string, number>;
+    client: Record<string, number>;
+    registry: Record<string, number>;
+}
+export declare function buildErrorCodes(): ErrorCodes;
+//# sourceMappingURL=build-error-codes.d.ts.map

package/dist/scripts/contract/build-error-codes.js

@@ -0,0 +1,17 @@
+import { SDK_SERVER_ERROR_CODES } from '../../schemas/sdk-errors-server.js';
+import { SDK_CLIENT_ERROR_CODES } from '../../schemas/sdk-errors-client.js';
+import { REGISTRY_ERROR_CODES } from '../../schemas/sdk-errors-registry.js';
+function sortedEntries(record) {
+    const entries = Object.entries(record);
+    entries.sort(function (a, b) {
+        return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+    });
+    return Object.fromEntries(entries);
+}
+export function buildErrorCodes() {
+    return {
+        server: sortedEntries(SDK_SERVER_ERROR_CODES),
+        client: sortedEntries(SDK_CLIENT_ERROR_CODES),
+        registry: sortedEntries(REGISTRY_ERROR_CODES)
+    };
+}

package/dist/scripts/contract/build-model-type-maps.d.ts

@@ -0,0 +1,22 @@
+/**
+ * JSON export of the model-type resolution maps that `loadModel`'s
+ * client-side type-inference reads: alias → canonical model type, canonical
+ * engine → addon, and legacy engine string → canonical engine.
+ *
+ * Inference itself stays in each client (a plain string `modelSrc` carries no
+ * engine to infer from, so it can't move server-side), but the *data* it reads
+ * must not drift between languages — so the maps are exported here, alongside
+ * schema.json/models.json, and generated into each client rather than
+ * hand-copied. `contract:check` (JS) and `generate.py --check` (Python) then
+ * fail the build if a map is edited on one side only.
+ *
+ * A separate artifact from schema.json for the same reason models.json is: a
+ * language-neutral data catalog, not part of the RPC wire contract.
+ */
+export interface ModelTypeMaps {
+    aliasToCanonical: Record<string, string>;
+    engineToAddon: Record<string, string>;
+    legacyEngineToCanonical: Record<string, string>;
+}
+export declare function buildModelTypeMaps(): ModelTypeMaps;
+//# sourceMappingURL=build-model-type-maps.d.ts.map