Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

fix(composer): type exact render provenance (#31)

Matthew Kissingerc0497f1dc26c
diff --git a/src/__tests__/composer-run-port.test.ts b/src/__tests__/composer-run-port.test.ts
index db0ea7fa..399ae6b0 100644
--- a/src/__tests__/composer-run-port.test.ts
+++ b/src/__tests__/composer-run-port.test.ts
@@ -64,8 +64,17 @@ describe('composer pbrRender seam (B3a)', () => {
const port: PbrRenderPort = async (req: PbrRenderRequest): Promise<PbrRenderResult> => ({
ok: true,
rendererId: 'dawn-vulkan:nvidia-rtx-a4500:NVIDIA: 550.100',
- viewsPng: (req.viewDirs ?? []).map(() => new Uint8Array([1])),
+ viewsPng: (req.cameras ?? req.viewDirs ?? []).map(() => new Uint8Array([1])),
timings: { renderMs: 12 },
+ ...(req.cameras
+ ? {
+ backend: 'vulkan',
+ cameras: req.cameras,
+ width: req.width,
+ height: req.height,
+ lightingPresetId: req.lightingPresetId,
+ }
+ : {}),
});
const res = await port({
glb: new Uint8Array([0x67, 0x6c, 0x54, 0x46]),
@@ -79,6 +88,30 @@ describe('composer pbrRender seam (B3a)', () => {
expect(res.ok).toBe(true);
expect(res.rendererId).toMatch(/^[a-z0-9-]+:/);
expect(res.viewsPng).toHaveLength(2);
+
+ const exactCamera = {
+ position: [12, 8, 15] as [number, number, number],
+ target: [0, 1, 0] as [number, number, number],
+ up: [0, 1, 0] as [number, number, number],
+ fovDeg: 50,
+ aspect: 16 / 9,
+ near: 0.1,
+ far: 500,
+ };
+ const exact = await port({
+ glb: new Uint8Array([1]),
+ cameras: [exactCamera],
+ width: 1280,
+ height: 720,
+ lightingPresetId: 'neutral-studio-v1',
+ });
+ expect(exact).toMatchObject({
+ backend: 'vulkan',
+ cameras: [exactCamera],
+ width: 1280,
+ height: 720,
+ lightingPresetId: 'neutral-studio-v1',
+ });
});
test('validates and clones exact perspective camera transport without changing legacy view dirs', () => {
diff --git a/src/__tests__/composer-world-run.test.ts b/src/__tests__/composer-world-run.test.ts
index 09f4b09a..85388003 100644
--- a/src/__tests__/composer-world-run.test.ts
+++ b/src/__tests__/composer-world-run.test.ts
@@ -159,9 +159,16 @@ describe('runKilnWorldIntegration', () => {
expect(modelContext).toContain('dawn-vulkan:test');
expect(modelContext).toContain('outputSha256');
expect(modelContext).toContain('"degraded":false');
+ expect(modelContext).not.toContain('fallbackReceipt');
});
test('surfaces an ok CPU fallback as degraded evidence without inventing a receipt', async () => {
+ const fallbackReceipt = {
+ cameraAttested: false as const,
+ backend: 'cpu',
+ rendererId: 'cpu-raster:test',
+ outputSha256: `sha256:${'d'.repeat(64)}` as const,
+ };
const model = new ToolCapturingModel([
{ toolCalls: [{ name: 'scene_world_render' }] },
{ text: 'done' },
@@ -175,6 +182,7 @@ describe('runKilnWorldIntegration', () => {
pngBase64: Buffer.from('png').toString('base64'),
degraded: true,
degradeReason: 'GPU deadline; deterministic CPU fallback',
+ fallbackReceipt,
}),
maxSteps: 4,
});
@@ -185,12 +193,16 @@ describe('runKilnWorldIntegration', () => {
views: 1,
degraded: true,
degradeReason: 'GPU deadline; deterministic CPU fallback',
+ fallbackReceipt,
},
]);
const modelContext = JSON.stringify(model.messages);
expect(modelContext).toContain('"degraded":true');
expect(modelContext).toContain('GPU deadline; deterministic CPU fallback');
- expect(modelContext).not.toContain('outputSha256');
+ expect(modelContext).toContain('cpu-raster:test');
+ expect(modelContext).toContain('outputSha256');
+ expect(modelContext).toContain('"cameraAttested":false');
+ expect(modelContext).not.toContain('"receipt":');
});
test('shares one aggregate model-call allowance across compose and integration', async () => {
diff --git a/src/composer/agent/world-run.ts b/src/composer/agent/world-run.ts
index a2ee4e39..8c0e063d 100644
--- a/src/composer/agent/world-run.ts
+++ b/src/composer/agent/world-run.ts
@@ -17,6 +17,7 @@ import {
parseWorldDocumentV2,
PlacementModel,
type Placement,
+ type SceneRenderFallbackReceipt,
type SceneRenderReceipt,
type SceneRenderPort,
type SceneRenderResult,
@@ -69,6 +70,7 @@ export interface WorldIntegrationRenderEvidence {
degraded?: boolean;
degradeReason?: string;
receipt?: SceneRenderReceipt;
+ fallbackReceipt?: SceneRenderFallbackReceipt;
}
const empty = z.object({}).strict();
@@ -181,12 +183,16 @@ function renderEvidenceOf(
views: number,
result: SceneRenderResult,
): WorldIntegrationRenderEvidence {
+ if (result.receipt && result.fallbackReceipt) {
+ throw new TypeError('render result cannot carry both exact and fallback receipts');
+ }
return {
worldHash,
views,
...(result.degraded !== undefined ? { degraded: result.degraded } : {}),
...(result.degradeReason ? { degradeReason: result.degradeReason } : {}),
...(result.receipt ? { receipt: cloneReceipt(result.receipt) } : {}),
+ ...(result.fallbackReceipt ? { fallbackReceipt: { ...result.fallbackReceipt } } : {}),
};
}
diff --git a/src/composer/render-port.ts b/src/composer/render-port.ts
index 8b72f982..8c8a3fd0 100644
--- a/src/composer/render-port.ts
+++ b/src/composer/render-port.ts
@@ -58,6 +58,15 @@ export interface SceneRenderReceipt {
outputSha256: `sha256:${string}`;
}
+/** Provenance for successful fallback pixels that do not attest the requested cameras. */
+export interface SceneRenderFallbackReceipt {
+ /** Literal false prevents this record from being mistaken for a SceneRenderReceipt. */
+ cameraAttested: false;
+ backend: string;
+ rendererId: string;
+ outputSha256: `sha256:${string}`;
+}
+
export interface SceneRenderResult {
ok: boolean;
/** The composited grid, or the single custom-camera frame (base64 PNG). */
@@ -67,6 +76,8 @@ export interface SceneRenderResult {
tris?: number;
/** Present when the host renders an immutable canonical-world milestone. */
receipt?: SceneRenderReceipt;
+ /** Actual fallback producer/output identity; never an exact-camera attestation. */
+ fallbackReceipt?: SceneRenderFallbackReceipt;
/** True when `ok:true` pixels came from a declared fallback rather than the
* requested renderer. Absent preserves compatibility with legacy hosts whose
* successful result did not report fallback provenance. */
@@ -291,6 +302,13 @@ export interface PbrRenderResult {
/** Honest producer identity, e.g. "dawn-vulkan:nvidia-rtx-a4500:NVIDIA: 550.100"
* or the CPU fallback's deterministic "cpu-raster:<engine-version>". */
rendererId: string;
+ /** Actual renderer backend. Required by hosts for camera mode; optional for legacy ports. */
+ backend?: string;
+ /** Exact camera transport echoed by a camera-mode host after validation. */
+ cameras?: ResolvedSceneCamera[];
+ width?: number;
+ height?: number;
+ lightingPresetId?: string;
/** One PNG per requested view direction, in request order. */
viewsPng?: Uint8Array[];
/** The optional beauty shot. */