Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
import {
authoringDiagnosticAdvice,
EXECUTION_REJECTED_ADVICE,
type AuthoringDiagnostic,
} from './authoring-diagnostic';
import { createHash } from 'node:crypto';
import {
assertNoLegacyRuntimePolicy,
validateRequirementsBinding,
validateRequirementsContext,
resolveRequirementsContext,
requirementsContextsEqual,
type RequirementsContext,
} from '../requirements-context';
import type { AssetQaReport } from '../qa/types';
import { validateRequirementsQaReport } from '../qa/requirements-report';
import type { RenderGlbOptions, RenderResult } from '../render';
import type { KhronosGltfValidationReport } from '../qa/gltf';
import {
validateMaterialLibraryPayloadAny,
validateMaterialManifestIdentityAny,
} from '../material-library-node';
import { canonicalMaterialJson, type MaterialLibraryPayload } from '../material-library';
import { rebuildOptionsSchema } from '../rebuild-options';
import {
solidFailureAdvice,
validSolidFailureDetails,
type SolidFailureDetails,
} from './solid-diagnostic';
export const EVALUATOR_REQUEST_VERSION = 'kiln.evaluator.request.v2' as const;
export const EVALUATOR_RESULT_VERSION = 'kiln.evaluator.result.v2' as const;
export const MAX_EVALUATOR_CODE_BYTES = 512 * 1024;
/** Includes bounded, host-approved PNG payloads; non-resource request data stays at 1 MiB. */
export const MAX_EVALUATOR_REQUEST_BYTES = 24 * 1024 * 1024;
export const DEFAULT_EVALUATOR_DEADLINE_MS = 60_000;
export const MAX_EVALUATOR_DEADLINE_MS = 120_000;
export const DEFAULT_EVALUATOR_MAX_GLB_BYTES = 16 * 1024 * 1024;
export const DEFAULT_EVALUATOR_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
export const MAX_EVALUATOR_GLB_BYTES = 64 * 1024 * 1024;
export const MAX_EVALUATOR_RESPONSE_BYTES = 96 * 1024 * 1024;
export type EvaluatorOutcomeCode =
| 'INPUT_INVALID'
| 'EXECUTION_REJECTED'
| 'QA_BLOCKED'
| 'DEADLINE_EXCEEDED'
| 'CANCELLED'
| 'OUTPUT_LIMIT_EXCEEDED'
| 'ISOLATION_UNAVAILABLE'
| 'WORKER_FAILED'
| 'PROTOCOL_ERROR';
const EVALUATOR_OUTCOME_MESSAGES: Record<EvaluatorOutcomeCode, string> = {
INPUT_INVALID:
'Evaluator request was invalid. Use kiln.evaluator.request.v2 and update the host and worker together. Retired category/intent options require explicit requirements migration; see docs/migration.md.',
EXECUTION_REJECTED: 'Generated asset execution was rejected.',
QA_BLOCKED: 'Generated asset did not pass quality checks.',
DEADLINE_EXCEEDED: 'Evaluator deadline exceeded.',
CANCELLED: 'Evaluator request was cancelled.',
OUTPUT_LIMIT_EXCEEDED: 'Evaluator output limit exceeded.',
ISOLATION_UNAVAILABLE: 'Isolated evaluator is unavailable.',
WORKER_FAILED: 'Evaluator worker failed.',
PROTOCOL_ERROR: 'Evaluator returned invalid data.',
};
export function evaluatorOutcomeMessage(code: EvaluatorOutcomeCode): string {
return EVALUATOR_OUTCOME_MESSAGES[code];
}
/** Which budget an OUTPUT_LIMIT_EXCEEDED outcome reached, in closed fields only (#317). */
export interface EvaluatorOutputLimitDetails {
stage: 'glb' | 'response';
limitBytes: number;
observedBytes: number;
/** A transport that stops reading at the budget knows a lower bound, not the size. */
atLeast?: true;
triangles?: number;
}
export function validEvaluatorOutputLimit(value: unknown): value is EvaluatorOutputLimitDetails {
return (
isRecord(value) &&
hasExactKeys(value, ['stage', 'limitBytes', 'observedBytes', 'atLeast', 'triangles']) &&
(value.stage === 'glb' || value.stage === 'response') &&
validInteger(value.limitBytes, 1, Number.MAX_SAFE_INTEGER) &&
validInteger(value.observedBytes, value.limitBytes + 1, Number.MAX_SAFE_INTEGER) &&
(value.atLeast === undefined || value.atLeast === true) &&
(value.triangles === undefined || validInteger(value.triangles, 0, Number.MAX_SAFE_INTEGER))
);
}
/** The wire message stays fixed; this is the host's account of it, as a cause's advice is. */
export function evaluatorOutputLimitAdvice(limit: EvaluatorOutputLimitDetails | undefined): string {
if (!limit) return '';
const size = `${limit.atLeast ? 'at least ' : ''}${limit.observedBytes} bytes`;
const reached =
limit.stage === 'glb'
? `The built GLB is ${size}${limit.triangles === undefined ? '' : ` (${limit.triangles} triangles)`}`
: `The evaluator response, which carries the GLB as base64 with its review data, is ${size}`;
return (
` ${reached}; this host allows at most ${limit.limitBytes} bytes, and nothing was exported.` +
' Lower the vertex count or attribute data, reuse one geometry across parts so its copies' +
' share the bytes, or split the asset into parts exported separately. A local host can raise' +
` the GLB limit to ${MAX_EVALUATOR_GLB_BYTES} with KILN_EVALUATOR_MAX_GLB_BYTES.` +
' kiln_discover with capabilities:true reports the limits in force.'
);
}
/**
* The one request budget an author reaches by authoring, rather than by sending a malformed
* request: source larger than a single evaluator request carries. The program store's limit
* is deliberately higher, because a stored revision is read, imported and exported without
* ever being evaluated, so this is a gap and not a mistake to close. Named here as a closed
* cause (#299): the generic `fail('request')` path reports it as a version mismatch, and a
* request carrying source over this budget never has to leave the host to find out.
*
* Returns the message, or undefined when the source fits. A non-string `code` belongs to the
* strict decoder, which rejects it as the malformed request it is.
*/
export function evaluatorSourceBudgetFailure(code: unknown): string | undefined {
if (typeof code !== 'string') return undefined;
const bytes = Buffer.byteLength(code, 'utf8');
if (bytes <= MAX_EVALUATOR_CODE_BYTES) return undefined;
return (
`Source is ${bytes} bytes; one evaluator request carries at most ${MAX_EVALUATOR_CODE_BYTES} bytes of source. ` +
'The program store accepts more on purpose, so this revision saves, reads, imports and exports; only evaluation refuses it. ' +
'Build the geometry inside build() from the primitive, profile and procedural helpers instead of embedding a literal vertex buffer, ' +
'round the literals you must keep to the precision the asset needs, or bind texture bytes as approved material resources instead of inlining them. ' +
'kiln_discover reports both limits as source.maxBytes and source.transportEvaluatorMaxBytes.'
);
}
export interface EvaluatorRequestV2 {
version: typeof EVALUATOR_REQUEST_VERSION;
requestId: string;
operation: 'execute-export-glb';
code: string;
options: Omit<RenderGlbOptions, 'textureResolver' | 'diagnosticConsole'>;
limits: { maxGlbBytes: number };
}
export interface CreateEvaluatorRequestV2Input {
requestId: string;
code: string;
options?: RenderGlbOptions;
maxGlbBytes?: number;
}
export interface EvaluatorTransportControlsV2 {
deadlineMs: number;
maxResponseBytes: number;
signal?: AbortSignal;
}
export type EvaluatorTransportV2 = (
requestJson: string,
controls: Readonly<EvaluatorTransportControlsV2>,
) => Promise<string>;
export interface EvaluatorPortCallControlsV2 {
deadlineMs?: number;
maxGlbBytes?: number;
maxResponseBytes?: number;
signal?: AbortSignal;
}
export interface EvaluatorPortV2 {
render(
code: string,
options?: RenderGlbOptions,
controls?: EvaluatorPortCallControlsV2,
): Promise<RenderResult>;
}
export type EvaluatorExecutionProfileV2 = 'trusted-local' | 'evaluator-required';
export function resolveEvaluatorPortV2(
port: EvaluatorPortV2 | undefined,
profile: EvaluatorExecutionProfileV2,
): EvaluatorPortV2 {
if (port) return port;
if (profile === 'evaluator-required') {
throw new EvaluatorPortError('ISOLATION_UNAVAILABLE', 'Evaluator port is required.');
}
return trustedInProcessEvaluatorPortV2;
}
export class EvaluatorPortError extends Error {
constructor(
readonly code: EvaluatorOutcomeCode,
message = evaluatorOutcomeMessage(code),
readonly diagnostic?: AuthoringDiagnostic,
readonly solid?: SolidFailureDetails,
readonly limit?: EvaluatorOutputLimitDetails,
) {
// A rejection with a closed cause carries that cause's advice; one without carries
// the engine's generic advice (decision 24). The wire message itself never changes.
super(
diagnostic
? `${message} ${authoringDiagnosticAdvice(diagnostic)}${solidFailureAdvice(solid)}`
: code === 'EXECUTION_REJECTED'
? `${message} ${EXECUTION_REJECTED_ADVICE}`
: `${message}${evaluatorOutputLimitAdvice(limit)}`,
);
this.name = 'EvaluatorPortError';
}
}
interface WireDiagnosticView {
[key: string]: unknown;
pngBase64: string;
}
interface WireRenderResult extends Omit<RenderResult, 'glb' | 'diagnosticViews'> {
glbBase64: string;
diagnosticViews?: WireDiagnosticView[];
}
export type EvaluatorResultV2 =
| {
version: typeof EVALUATOR_RESULT_VERSION;
requestId: string;
ok: true;
render: RenderResult;
}
| {
version: typeof EVALUATOR_RESULT_VERSION;
requestId: string;
ok: false;
error: {
code: EvaluatorOutcomeCode;
message: string;
diagnostic?: AuthoringDiagnostic;
solid?: SolidFailureDetails;
limit?: EvaluatorOutputLimitDetails;
qa?: {
report: AssetQaReport;
stage: 'scene' | 'final-glb';
gltfValidation?: KhronosGltfValidationReport;
};
};
};
export type WireEvaluatorResultV2 =
| (Omit<Extract<EvaluatorResultV2, { ok: true }>, 'render'> & { render: WireRenderResult })
| Extract<EvaluatorResultV2, { ok: false }>;
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
function hasExactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
return Object.keys(value).every((key) => allowed.includes(key));
}
function fail(kind: 'request' | 'result'): never {
throw new Error(`invalid evaluator ${kind}`);
}
function validRequestId(value: unknown): value is string {
return typeof value === 'string' && /^[A-Za-z0-9._-]{1,64}$/.test(value);
}
function validInteger(value: unknown, min: number, max: number): value is number {
return Number.isInteger(value) && Number(value) >= min && Number(value) <= max;
}
function validRequirementsQaReport(value: unknown): boolean {
try {
validateRequirementsQaReport(value);
return true;
} catch {
return false;
}
}
function validGltfValidation(value: unknown): value is KhronosGltfValidationReport {
const issues = isRecord(value) && isRecord(value.issues) ? value.issues : undefined;
if (!issues || !Array.isArray(issues.messages)) {
return false;
}
return (
['numErrors', 'numWarnings', 'numInfos', 'numHints'].every((key) =>
validInteger(issues[key], 0, Number.MAX_SAFE_INTEGER),
) &&
issues.messages.length <= 1_000 &&
issues.messages.every(
(issue) =>
isRecord(issue) &&
typeof issue.code === 'string' &&
typeof issue.message === 'string' &&
typeof issue.severity === 'number' &&
Number.isFinite(issue.severity),
)
);
}
function boundedControl(value: number | undefined, fallback: number, max: number): number {
const resolved = value ?? fallback;
if (!validInteger(resolved, 1, max)) {
throw new EvaluatorPortError('INPUT_INVALID');
}
return resolved;
}
export function createEvaluatorRequestV2(input: CreateEvaluatorRequestV2Input): {
request: EvaluatorRequestV2;
json: string;
} {
if (input.options?.textureResolver) {
throw new EvaluatorPortError(
'INPUT_INVALID',
'Evaluator requests do not accept a host resolver capability.',
);
}
if (input.options?.diagnosticConsole) {
throw new EvaluatorPortError(
'INPUT_INVALID',
'Evaluator requests do not accept a host console capability.',
);
}
const oversizeSource = evaluatorSourceBudgetFailure(input.code);
if (oversizeSource) throw new EvaluatorPortError('INPUT_INVALID', oversizeSource);
const maxGlbBytes = boundedControl(
input.maxGlbBytes,
DEFAULT_EVALUATOR_MAX_GLB_BYTES,
64 * 1024 * 1024,
);
const { textureResolver: _, diagnosticConsole: _console, ...options } = input.options ?? {};
const request: EvaluatorRequestV2 = {
version: EVALUATOR_REQUEST_VERSION,
requestId: input.requestId,
operation: 'execute-export-glb',
code: input.code,
options,
limits: { maxGlbBytes },
};
const json = JSON.stringify(request);
// Reuse the strict decoder as the single authority for ids, source, options,
// prototype-key rejection, and request budgets.
const decoded = decodeEvaluatorRequestV2(json);
return { request: decoded, json };
}
function parseOptions(
value: unknown,
): Omit<RenderGlbOptions, 'textureResolver' | 'diagnosticConsole'> {
if (
!isRecord(value) ||
!hasExactKeys(value, [
'optimize',
'instance',
'intent',
'category',
'requirements',
'geometryPolicy',
'indexPolicy',
'gltfExporter',
'materialResources',
])
) {
return fail('request');
}
const options: Omit<RenderGlbOptions, 'textureResolver' | 'diagnosticConsole'> = {};
if (value.materialResources !== undefined)
options.materialResources = validateMaterialLibraryPayloadAny(value.materialResources);
if (value.gltfExporter !== undefined) {
if (value.gltfExporter !== 'legacy' && value.gltfExporter !== 'three') fail('request');
options.gltfExporter = value.gltfExporter;
}
if (value.geometryPolicy !== undefined) {
if (!['warn', 'strict'].includes(String(value.geometryPolicy))) fail('request');
options.geometryPolicy = value.geometryPolicy as 'warn' | 'strict';
}
if (value.indexPolicy !== undefined) {
if (value.indexPolicy !== 'indexed' && value.indexPolicy !== 'asBuilt') fail('request');
options.indexPolicy = value.indexPolicy;
}
if (value.optimize !== undefined) {
if (!['off', 'auto', 'palette', 'full'].includes(String(value.optimize))) fail('request');
options.optimize = value.optimize as NonNullable<RenderGlbOptions['optimize']>;
}
if (value.instance !== undefined) {
if (!['off', 'auto', 'on'].includes(String(value.instance))) fail('request');
options.instance = value.instance as NonNullable<RenderGlbOptions['instance']>;
}
assertNoLegacyRuntimePolicy(value);
if (value.requirements !== undefined)
options.requirements = validateRequirementsBinding(value.requirements);
return options;
}
export function decodeEvaluatorRequestV2(json: string): EvaluatorRequestV2 {
if (Buffer.byteLength(json, 'utf8') > MAX_EVALUATOR_REQUEST_BYTES) fail('request');
let value: unknown;
try {
value = JSON.parse(json);
} catch {
return fail('request');
}
if (isRecord(value) && isRecord(value.options)) {
const { materialResources: _, ...metadataOptions } = value.options;
if (
Buffer.byteLength(JSON.stringify({ ...value, options: metadataOptions }), 'utf8') >
1024 * 1024
)
return fail('request');
}
if (
!isRecord(value) ||
!hasExactKeys(value, ['version', 'requestId', 'operation', 'code', 'options', 'limits']) ||
value.version !== EVALUATOR_REQUEST_VERSION ||
!validRequestId(value.requestId) ||
value.operation !== 'execute-export-glb' ||
typeof value.code !== 'string' ||
Buffer.byteLength(value.code, 'utf8') > MAX_EVALUATOR_CODE_BYTES ||
!isRecord(value.limits) ||
!hasExactKeys(value.limits, ['maxGlbBytes']) ||
!validInteger(value.limits.maxGlbBytes, 1, MAX_EVALUATOR_GLB_BYTES)
) {
return fail('request');
}
return {
version: EVALUATOR_REQUEST_VERSION,
requestId: value.requestId,
operation: 'execute-export-glb',
code: value.code,
options: parseOptions(value.options),
limits: { maxGlbBytes: value.limits.maxGlbBytes },
};
}
export function encodeRenderResultV2(
requestId: string,
render: RenderResult,
): WireEvaluatorResultV2 {
const { glb, diagnosticViews, buildCache: _hostCacheReceipt, ...rest } = render;
return {
version: EVALUATOR_RESULT_VERSION,
requestId,
ok: true,
render: {
...rest,
glbBase64: glb.toString('base64'),
...(diagnosticViews
? {
diagnosticViews: diagnosticViews.map(({ png, ...view }) => ({
...view,
pngBase64: Buffer.from(png).toString('base64'),
})),
}
: {}),
},
};
}
function isSha256(value: unknown): value is `sha256:${string}` {
return typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
}
export function decodeEvaluatorResultV2(
json: string,
maxGlbBytes: number,
expectedRequestId?: string,
): EvaluatorResultV2 {
let value: unknown;
try {
value = JSON.parse(json);
} catch {
return fail('result');
}
if (
!isRecord(value) ||
!hasExactKeys(value, ['version', 'requestId', 'ok', 'render', 'error']) ||
value.version !== EVALUATOR_RESULT_VERSION ||
!validRequestId(value.requestId) ||
typeof value.ok !== 'boolean'
) {
return fail('result');
}
if (expectedRequestId !== undefined && value.requestId !== expectedRequestId) fail('result');
if (!value.ok) {
if (value.render !== undefined) return fail('result');
if (
!isRecord(value.error) ||
!hasExactKeys(value.error, ['code', 'message', 'qa', 'diagnostic', 'solid', 'limit'])
) {
return fail('result');
}
const codes: EvaluatorOutcomeCode[] = [
'INPUT_INVALID',
'EXECUTION_REJECTED',
'QA_BLOCKED',
'DEADLINE_EXCEEDED',
'CANCELLED',
'OUTPUT_LIMIT_EXCEEDED',
'ISOLATION_UNAVAILABLE',
'WORKER_FAILED',
'PROTOCOL_ERROR',
];
if (
!codes.includes(value.error.code as EvaluatorOutcomeCode) ||
typeof value.error.message !== 'string' ||
value.error.message !== evaluatorOutcomeMessage(value.error.code as EvaluatorOutcomeCode)
) {
return fail('result');
}
if (
value.error.diagnostic !== undefined &&
(value.error.code !== 'EXECUTION_REJECTED' ||
(value.error.diagnostic !== 'UNBOUND_VARIABLE' &&
value.error.diagnostic !== 'GEAR_RADII_ORDER' &&
value.error.diagnostic !== 'ROUNDED_BOX_RADIUS' &&
value.error.diagnostic !== 'PROCEDURAL_TEXTURE_UNKNOWN_KEY' &&
value.error.diagnostic !== 'PROCEDURAL_TEXTURE_BLEND' &&
value.error.diagnostic !== 'PROCEDURAL_TEXTURE_USAGE' &&
value.error.diagnostic !== 'PROCEDURAL_TEXTURE_V3_CONTRACT' &&
value.error.diagnostic !== 'PORTABLE_MATERIAL_V3_CONTRACT' &&
value.error.diagnostic !== 'TEXTURE_ATLAS_CONTRACT' &&
value.error.diagnostic !== 'MATERIAL_FRACTION_RANGE' &&
value.error.diagnostic !== 'MATERIAL_RECIPE_TEXTURE_BINDING' &&
value.error.diagnostic !== 'PORTABLE_TEXTURE_REFERENCE' &&
value.error.diagnostic !== 'PORTABLE_COLOR_ARGUMENT' &&
value.error.diagnostic !== 'PARAMETRIC_PERIODIC_ENDPOINT' &&
value.error.diagnostic !== 'PROFILE_HOLES_UNSUPPORTED' &&
value.error.diagnostic !== 'PROFILE_BEVEL_COLLAPSE' &&
value.error.diagnostic !== 'PROFILE_SOLID_FAILED' &&
value.error.diagnostic !== 'PROFILE_CORRESPONDENCE_COLLAPSE' &&
value.error.diagnostic !== 'REMOVED_HELPER' &&
value.error.diagnostic !== 'TUBE_RADIUS' &&
value.error.diagnostic !== 'TAPER_CONE_AXIS' &&
value.error.diagnostic !== 'SOLID_FLOAT32_COLLAPSE' &&
value.error.diagnostic !== 'MESH_DATA_NONFINITE' &&
value.error.diagnostic !== 'MATERIAL_ALPHA_MODE' &&
value.error.diagnostic !== 'MATERIAL_COLOR_ARGUMENT' &&
value.error.diagnostic !== 'PART_NAME_ARGUMENT' &&
value.error.diagnostic !== 'PART_GEOMETRY_ARGUMENT' &&
value.error.diagnostic !== 'PART_MATERIAL_ARGUMENT' &&
value.error.diagnostic !== 'MATERIAL_PACKED_CHANNELS' &&
value.error.diagnostic !== 'UNINITIALIZED_BINDING' &&
value.error.diagnostic !== 'BUILD_RESULT' &&
value.error.diagnostic !== 'MATERIAL_RECIPE_OVERRIDE' &&
value.error.diagnostic !== 'PROGRAM_TYPE_ERROR' &&
value.error.diagnostic !== 'PROGRAM_RANGE_ERROR' &&
value.error.diagnostic !== 'LOD_SET' &&
value.error.diagnostic !== 'OPEN_SHELL' &&
value.error.diagnostic !== 'DELIVERY_CONTRACT' &&
value.error.diagnostic !== 'REQUIRE_SOLID' &&
value.error.diagnostic !== 'EXPORT_MATERIAL_SIDE_UNSUPPORTED' &&
value.error.diagnostic !== 'BONE_CHAIN_ARGUMENT' &&
value.error.diagnostic !== 'SKIN_BINDING_ARGUMENT'))
)
return fail('result');
if (
value.error.solid !== undefined &&
(value.error.diagnostic !== 'REQUIRE_SOLID' || !validSolidFailureDetails(value.error.solid))
)
return fail('result');
if (
value.error.limit !== undefined &&
(value.error.code !== 'OUTPUT_LIMIT_EXCEEDED' ||
!validEvaluatorOutputLimit(value.error.limit))
)
return fail('result');
if (value.error.qa !== undefined) {
if (
value.error.code !== 'QA_BLOCKED' ||
!isRecord(value.error.qa) ||
!hasExactKeys(value.error.qa, ['report', 'stage', 'gltfValidation']) ||
!validRequirementsQaReport(value.error.qa.report) ||
!['scene', 'final-glb'].includes(String(value.error.qa.stage)) ||
(value.error.qa.gltfValidation !== undefined &&
!validGltfValidation(value.error.qa.gltfValidation))
) {
return fail('result');
}
} else if (value.error.code === 'QA_BLOCKED') {
return fail('result');
}
return value as unknown as Extract<EvaluatorResultV2, { ok: false }>;
}
if (value.error !== undefined || !isRecord(value.render)) fail('result');
const renderKeys = [
'glbBase64',
'artifactGlbSha256',
'tris',
'meta',
'warnings',
'diagnosticViews',
'materialMetrics',
'materialRecipeApplications',
'materialResourceProvenance',
'materialLibraryDependencies',
'bakedTextures',
'integrationManifest',
'requirements',
'rebuildOptions',
] as const;
if (
!hasExactKeys(value.render, renderKeys) ||
typeof value.render.glbBase64 !== 'string' ||
!validInteger(value.render.tris, 0, Number.MAX_SAFE_INTEGER) ||
!isRecord(value.render.meta) ||
!Array.isArray(value.render.warnings) ||
!value.render.warnings.every((warning) => typeof warning === 'string') ||
!isRecord(value.render.integrationManifest)
) {
fail('result');
}
let requirements: RequirementsContext;
if (
value.render.rebuildOptions !== undefined &&
!rebuildOptionsSchema.strict().safeParse(value.render.rebuildOptions).success
)
fail('result');
if (value.render.materialLibraryDependencies !== undefined) {
if (
!Array.isArray(value.render.materialLibraryDependencies) ||
value.render.materialLibraryDependencies.length > 16
)
fail('result');
try {
for (const manifest of value.render.materialLibraryDependencies)
validateMaterialManifestIdentityAny(manifest);
} catch {
return fail('result');
}
}
try {
requirements = validateRequirementsContext(value.render.requirements);
validateRequirementsQaReport(value.render.meta.qaReport, requirements);
} catch {
return fail('result');
}
const glb = Buffer.from(value.render.glbBase64, 'base64');
if (glb.byteLength > maxGlbBytes || glb.toString('base64') !== value.render.glbBase64)
fail('result');
if (!isSha256(value.render.artifactGlbSha256)) fail('result');
const actualHash = `sha256:${createHash('sha256').update(glb).digest('hex')}`;
if (actualHash !== value.render.artifactGlbSha256) fail('result');
const diagnosticViews = value.render.diagnosticViews;
if (diagnosticViews !== undefined && !Array.isArray(diagnosticViews)) fail('result');
const decodedViews = diagnosticViews?.map((candidate) => {
if (!isRecord(candidate) || typeof candidate.pngBase64 !== 'string') return fail('result');
const png = Buffer.from(candidate.pngBase64, 'base64');
if (png.toString('base64') !== candidate.pngBase64) return fail('result');
const { pngBase64: _, ...view } = candidate;
return { ...view, png };
});
const { glbBase64: _, diagnosticViews: __, ...rest } = value.render;
return {
version: EVALUATOR_RESULT_VERSION,
requestId: value.requestId,
ok: true,
render: {
...rest,
glb,
...(decodedViews ? { diagnosticViews: decodedViews } : {}),
} as unknown as RenderResult,
};
}
export function createEvaluatorPortV2(
transport: EvaluatorTransportV2,
defaults: EvaluatorPortCallControlsV2 = {},
): EvaluatorPortV2 {
let sequence = 0;
return {
async render(code, options = {}, controls = {}) {
const signal = controls.signal ?? defaults.signal;
if (signal?.aborted) throw new EvaluatorPortError('CANCELLED');
const deadlineMs = boundedControl(
controls.deadlineMs ?? defaults.deadlineMs,
DEFAULT_EVALUATOR_DEADLINE_MS,
MAX_EVALUATOR_DEADLINE_MS,
);
const maxGlbBytes = boundedControl(
controls.maxGlbBytes ?? defaults.maxGlbBytes,
DEFAULT_EVALUATOR_MAX_GLB_BYTES,
MAX_EVALUATOR_GLB_BYTES,
);
const maxResponseBytes = boundedControl(
controls.maxResponseBytes ?? defaults.maxResponseBytes,
DEFAULT_EVALUATOR_MAX_RESPONSE_BYTES,
MAX_EVALUATOR_RESPONSE_BYTES,
);
const requestId = `eval-${++sequence}`;
const built = createEvaluatorRequestV2({ requestId, code, options, maxGlbBytes });
let timer: ReturnType<typeof setTimeout> | undefined;
let response: string;
const transportController = new AbortController();
let abort: (() => void) | undefined;
try {
const cancelled = new Promise<never>((_, reject) => {
abort = () => {
reject(new EvaluatorPortError('CANCELLED'));
transportController.abort();
};
signal?.addEventListener('abort', abort, { once: true });
});
response = await Promise.race([
transport(built.json, {
deadlineMs,
maxResponseBytes,
signal: transportController.signal,
}),
cancelled,
new Promise<never>((_, reject) => {
timer = setTimeout(() => {
reject(new EvaluatorPortError('DEADLINE_EXCEEDED'));
transportController.abort();
}, deadlineMs);
}),
]);
} catch (error) {
if (error instanceof EvaluatorPortError) throw error;
throw new EvaluatorPortError('WORKER_FAILED');
} finally {
clearTimeout(timer);
if (abort) signal?.removeEventListener('abort', abort);
}
if (signal?.aborted) throw new EvaluatorPortError('CANCELLED');
if (typeof response !== 'string') throw new EvaluatorPortError('PROTOCOL_ERROR');
const responseBytes = Buffer.byteLength(response, 'utf8');
if (responseBytes > maxResponseBytes) {
throw new EvaluatorPortError('OUTPUT_LIMIT_EXCEEDED', undefined, undefined, undefined, {
stage: 'response',
limitBytes: maxResponseBytes,
observedBytes: responseBytes,
});
}
let result: EvaluatorResultV2;
try {
result = decodeEvaluatorResultV2(response, maxGlbBytes, requestId);
} catch {
throw new EvaluatorPortError('PROTOCOL_ERROR');
}
assertEvaluatorResultRequirements(
result,
resolveRequirementsContext(built.request.options.requirements),
);
assertEvaluatorResultMaterialResources(result, built.request.options.materialResources);
if (!result.ok) {
if (result.error.code === 'QA_BLOCKED' && result.error.qa) {
const { AssetQaBlockedError } = await import('../qa/run');
throw new AssetQaBlockedError(
result.error.qa.report,
result.error.qa.stage,
result.error.qa.gltfValidation,
);
}
throw new EvaluatorPortError(
result.error.code,
undefined,
result.error.diagnostic,
result.error.solid,
result.error.limit,
);
}
return result.render;
},
};
}
/** All transports bind decoded acceptance evidence to the same current-host snapshot. */
export function assertEvaluatorResultMaterialResources(
result: EvaluatorResultV2,
expected?: MaterialLibraryPayload,
): void {
if (!result.ok) return;
const actual = result.render.materialLibraryDependencies ?? [];
const wanted = expected?.records.map((record) => record.manifest) ?? [];
const identity = (manifest: (typeof actual)[number]) =>
`${manifest.materialId}/${manifest.revisionId}`;
if (
new Set(actual.map(identity)).size !== actual.length ||
JSON.stringify(actual.map(canonicalMaterialJson).sort()) !==
JSON.stringify(wanted.map(canonicalMaterialJson).sort())
)
throw new EvaluatorPortError('PROTOCOL_ERROR');
}
/** All transports bind decoded acceptance evidence to the same current-host snapshot. */
export function assertEvaluatorResultRequirements(
result: EvaluatorResultV2,
expected: RequirementsContext,
): void {
try {
if (result.ok) {
if (!requirementsContextsEqual(result.render.requirements, expected))
throw new Error('Requirements mismatch.');
} else if (result.error.code === 'QA_BLOCKED' && result.error.qa) {
validateRequirementsQaReport(result.error.qa.report, expected);
}
} catch {
throw new EvaluatorPortError(
'PROTOCOL_ERROR',
'Evaluator requirements context differs from the host request.',
);
}
}
/** Explicit trusted/test compatibility port. Production hosts must inject a
* transport-backed port and select `evaluator-required`; there is no fallback. */
export const trustedInProcessEvaluatorPortV2: EvaluatorPortV2 = {
async render(code, options = {}, controls = {}) {
if (controls.signal?.aborted) throw new EvaluatorPortError('CANCELLED');
const { renderGLBInProcess } = await import('../render');
const result = await renderGLBInProcess(code, options);
if (controls.signal?.aborted) throw new EvaluatorPortError('CANCELLED');
return result;
},
};