@instruktlabs/kiln 0.0.0-stage → 1.0.0

package/lib/composer/agent/world-run.d.ts

@@ -0,0 +1,50 @@
+import { type AgentUsage, type KilnAgentEvent } from "../../agent/hooks.js";
+import type { GenerationCallBudget, GenerationCallBudgetReceipt } from "../../agent/call-budget.js";
+import { type Placement, type SceneRenderFallbackReceipt, type SceneRenderReceipt, type SceneRenderPort, type WorldDocumentV2 } from "../index.js";
+import { type MakeWorldIntegrationToolsV2Options } from "./world-tools.js";
+export interface RunKilnWorldIntegrationOptions extends Omit<MakeWorldIntegrationToolsV2Options, 'state'> {
+    model: unknown;
+    prompt: string;
+    world: unknown;
+    render: SceneRenderPort;
+    agentName?: string;
+    onEvent?: (event: KilnAgentEvent) => void;
+    extraTools?: unknown[];
+    /** Explicit integration-only model-call ceiling. Required without a shared budget. */
+    maxSteps?: number;
+    /** Preferred: the same aggregate allowance used by compose/observer/repair roles. */
+    generationCallBudget?: GenerationCallBudget;
+}
+export interface RunKilnWorldIntegrationResult {
+    world: WorldDocumentV2;
+    worldHash: `sha256:${string}`;
+    placements: Placement[];
+    finalized: boolean;
+    toolCalls: string[];
+    steps: number;
+    usage?: AgentUsage;
+    callBudget?: GenerationCallBudgetReceipt;
+    /** Every successful canonical-world render attempt, in tool-call order. */
+    renderEvidence: WorldIntegrationRenderEvidence[];
+    /** The model may request commit, but the host remains the final authority. */
+    finalizedBy?: 'model' | 'host';
+    capped?: boolean;
+    lastText?: string;
+    error?: string;
+}
+export interface WorldIntegrationRenderEvidence {
+    worldHash: `sha256:${string}`;
+    views: number;
+    /** Absent only for a legacy host that did not report fallback provenance. */
+    degraded?: boolean;
+    degradeReason?: string;
+    receipt?: SceneRenderReceipt;
+    fallbackReceipt?: SceneRenderFallbackReceipt;
+}
+/**
+ * Run the bounded post-compose integration phase over one canonical authority.
+ * Fresh flow: compose -> migrate v1 candidate -> run this. Refine flow: compose
+ * candidate -> reconcileWorldDocumentV2Candidate(parent,candidate) -> run this.
+ * Every placement-affecting world tool mutates the same state rendered/finalized.
+ */
+export declare function runKilnWorldIntegration(options: RunKilnWorldIntegrationOptions): Promise<RunKilnWorldIntegrationResult>;

package/lib/composer/agent/world-run.js

@@ -0,0 +1,295 @@
+/** Engine-owned bounded second-stage compiler for canonical world integration. */
+import { Agent, ImageBlock, JsonBlock, tool, } from '@strands-agents/sdk';
+import { z } from 'zod';
+import { MetricsCollector } from "../../agent/hooks.js";
+import { toCachedSystemPrompt } from "../../agent/providers.js";
+import { hashWorldDocumentV2, PRESENTATION_MAX_TOTAL_PIXELS_V1, parseWorldDocumentV2, PlacementModel, validatePresentationReceiptV1, validateWorldIntegrationV2, worldDocumentV2ToSceneModelJSON, } from "../index.js";
+import { WORLD_INTEGRATION_PROMPT_V2 } from "./prompt.js";
+import { makeWorldIntegrationToolsV2, } from "./world-tools.js";
+const empty = z.object({}).strict();
+const png = (base64) => new Uint8Array(Buffer.from(base64, 'base64'));
+function placements(world) {
+    return PlacementModel.fromJSON(worldDocumentV2ToSceneModelJSON(world)).placements().placements;
+}
+function lastMessageText(message) {
+    if (!message)
+        return undefined;
+    const text = message.content
+        .filter((block) => block.type === 'textBlock')
+        .map((block) => block.text ?? '')
+        .join('\n')
+        .trim();
+    return text || undefined;
+}
+function lifecycleTools(state, render, finalized, renderEvidence) {
+    return [
+        tool({
+            name: 'scene_world_view',
+            description: 'Inspect the complete canonical world and authored integration counts.',
+            inputSchema: empty,
+            callback: async () => {
+                const worldHash = await hashWorldDocumentV2(state.world);
+                return {
+                    ok: true,
+                    worldHash,
+                    objects: state.world.objects.length,
+                    zones: state.world.authored.zones.length,
+                    paths: state.world.authored.paths.length,
+                    sockets: state.world.authored.sockets.length,
+                    spawns: state.world.spawns.length,
+                    terrain: state.world.terrain.kind,
+                    presentation: state.world.presentation ?? null,
+                    presentationLimits: {
+                        maxCameras: 12,
+                        maxGridColumns: 4,
+                        maxGridRows: 3,
+                        maxCellWidth: 4096,
+                        maxCellHeight: 4096,
+                        maxTotalPixels: PRESENTATION_MAX_TOTAL_PIXELS_V1,
+                    },
+                    presentationBinding: state.world.presentation
+                        ? { kind: 'world', sha256: worldHash, authoredByModel: false }
+                        : null,
+                };
+            },
+        }),
+        tool({
+            name: 'scene_world_validate',
+            description: 'Check socket compatibility/occupancy and every reserved, portal, and spawn clearance.',
+            inputSchema: empty,
+            callback: () => {
+                const issues = validateWorldIntegrationV2(state.world);
+                return { ok: issues.length === 0, issues };
+            },
+        }),
+        tool({
+            name: 'scene_world_render',
+            description: 'Render the current canonical world with the host inspection profile; inspect before finalizing.',
+            inputSchema: empty,
+            callback: async () => {
+                const attempt = await renderCanonicalWorld(state.world, render);
+                if (!attempt.ok)
+                    return { ok: false, error: attempt.error };
+                const { evidence, frames } = attempt;
+                renderEvidence.push(evidence);
+                return [
+                    ...frames.map((frame) => new ImageBlock({ format: 'png', source: { bytes: png(frame) } })),
+                    new JsonBlock({ json: { ok: true, ...evidence } }),
+                ];
+            },
+        }),
+        tool({
+            name: 'scene_world_finalize',
+            description: 'Finalize the validated canonical world after rendering it. Call exactly once.',
+            inputSchema: empty,
+            callback: async () => {
+                const issues = validateWorldIntegrationV2(state.world);
+                if (issues.length)
+                    return { ok: false, issues };
+                finalized.value = true;
+                return { ok: true, worldHash: await hashWorldDocumentV2(state.world) };
+            },
+        }),
+    ];
+}
+async function renderCanonicalWorld(world, render) {
+    const worldHash = await hashWorldDocumentV2(world);
+    const presentation = world.presentation;
+    const result = await render({
+        placements: placements(world),
+        worldDocument: world,
+        worldHash,
+        ...(presentation
+            ? {
+                cameras: presentation.cameras.map(({ id: _id, cell: _cell, ...camera }) => camera),
+                width: presentation.grid.cellWidth,
+                height: presentation.grid.cellHeight,
+                lightingPresetId: presentation.lightingPresetId,
+            }
+            : {}),
+    });
+    if (!result.ok)
+        return { ok: false, error: result.error ?? 'render failed' };
+    if (presentation && result.receipt) {
+        const receiptValidation = validatePresentationReceiptV1({
+            ...presentation,
+            artifactBinding: { kind: 'world', sha256: worldHash },
+        }, result.receipt);
+        if (!receiptValidation.ok) {
+            return {
+                ok: false,
+                error: `presentation receipt rejected: ${receiptValidation.reason}`,
+            };
+        }
+    }
+    const frames = result.perCameraBase64?.length
+        ? result.perCameraBase64
+        : result.pngBase64
+            ? [result.pngBase64]
+            : [];
+    return { ok: true, frames, evidence: renderEvidenceOf(worldHash, frames.length, result) };
+}
+function cloneReceipt(receipt) {
+    if (receipt.perCameraOutputSha256 !== undefined &&
+        receipt.perCameraOutputSha256.length !== receipt.cameras.length) {
+        throw new TypeError('render receipt per-camera output hashes must match cameras');
+    }
+    return {
+        ...receipt,
+        ...(receipt.perCameraOutputSha256
+            ? { perCameraOutputSha256: [...receipt.perCameraOutputSha256] }
+            : {}),
+        cameras: receipt.cameras.map((camera) => ({
+            ...camera,
+            position: [...camera.position],
+            target: [...camera.target],
+            up: [...camera.up],
+        })),
+    };
+}
+function renderEvidenceOf(worldHash, views, result) {
+    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 } } : {}),
+    };
+}
+function hostFinalizationError(world, worldHash, renderEvidence) {
+    const issues = validateWorldIntegrationV2(world);
+    if (issues.length) {
+        return `world integration validation failed: ${issues[0].code}`;
+    }
+    const exactFinalRender = renderEvidence.some((evidence) => evidence.worldHash === worldHash &&
+        evidence.views > 0 &&
+        evidence.degraded !== true &&
+        evidence.receipt?.worldHash === worldHash);
+    if (!exactFinalRender) {
+        return 'world integration ended before a hash-bound non-degraded render of the final world';
+    }
+    return undefined;
+}
+async function establishHostFinalization(world, render, renderEvidence) {
+    const worldHash = await hashWorldDocumentV2(world);
+    const validationError = hostFinalizationError(world, worldHash, renderEvidence);
+    if (!validationError)
+        return { worldHash, renderedByHost: false };
+    if (!validationError.startsWith('world integration ended before')) {
+        return { worldHash, error: validationError, renderedByHost: false };
+    }
+    // A render of this exact world already produced non-committable evidence.
+    // Preserve that terminal truth instead of hiding a degraded or malformed
+    // receipt behind an unchanged automatic retry.
+    if (renderEvidence.some((evidence) => evidence.worldHash === worldHash)) {
+        return { worldHash, error: validationError, renderedByHost: false };
+    }
+    const attempt = await renderCanonicalWorld(world, render);
+    if (!attempt.ok) {
+        return {
+            worldHash,
+            error: `final world render failed: ${attempt.error}`,
+            renderedByHost: true,
+        };
+    }
+    renderEvidence.push(attempt.evidence);
+    return {
+        worldHash,
+        error: hostFinalizationError(world, worldHash, renderEvidence),
+        renderedByHost: true,
+    };
+}
+/**
+ * Run the bounded post-compose integration phase over one canonical authority.
+ * Fresh flow: compose -> migrate v1 candidate -> run this. Refine flow: compose
+ * candidate -> reconcileWorldDocumentV2Candidate(parent,candidate) -> run this.
+ * Every placement-affecting world tool mutates the same state rendered/finalized.
+ */
+export async function runKilnWorldIntegration(options) {
+    const state = { world: parseWorldDocumentV2(options.world) };
+    const finalized = { value: false };
+    const renderEvidence = [];
+    const maxSteps = options.maxSteps ?? 0;
+    const metrics = new MetricsCollector(options.onEvent, maxSteps, options.generationCallBudget, 'author');
+    try {
+        if (!options.generationCallBudget && (!Number.isInteger(maxSteps) || maxSteps < 1)) {
+            throw new Error('runKilnWorldIntegration requires generationCallBudget or an explicit positive maxSteps');
+        }
+        const mutationTools = makeWorldIntegrationToolsV2({
+            state,
+            ...(options.publishHeightfieldArtifact
+                ? { publishHeightfieldArtifact: options.publishHeightfieldArtifact }
+                : {}),
+            ...(options.publishColliderArtifact
+                ? { publishColliderArtifact: options.publishColliderArtifact }
+                : {}),
+            ...(options.resolveAuthoredColliderGeometry
+                ? { resolveAuthoredColliderGeometry: options.resolveAuthoredColliderGeometry }
+                : {}),
+            ...(options.onWorldChanged ? { onWorldChanged: options.onWorldChanged } : {}),
+        });
+        const tools = [
+            ...mutationTools,
+            ...lifecycleTools(state, options.render, finalized, renderEvidence),
+            ...(options.extraTools ?? []),
+        ];
+        const agent = new Agent({
+            model: options.model,
+            systemPrompt: await toCachedSystemPrompt(WORLD_INTEGRATION_PROMPT_V2, options.model),
+            tools: tools,
+            name: options.agentName ?? 'kiln-world-integrator',
+        });
+        metrics.attach(agent);
+        const result = await agent.invoke(`## World integration task\n${options.prompt.trim()}\n\nInspect the current world, make only bounded integration edits that serve the request, render, validate, then finalize.`);
+        metrics.recordResultUsage(result.metrics?.latestAgentInvocation?.usage);
+        const collected = metrics.readMetrics();
+        const finalization = await establishHostFinalization(state.world, options.render, renderEvidence);
+        const { worldHash } = finalization;
+        const lastText = lastMessageText(result.lastMessage);
+        const finalizationError = finalization.error;
+        const hostFinalized = finalizationError === undefined && (!finalized.value || finalization.renderedByHost);
+        return {
+            world: state.world,
+            worldHash,
+            placements: placements(state.world),
+            finalized: finalizationError === undefined,
+            ...(finalizationError === undefined
+                ? { finalizedBy: hostFinalized ? 'host' : 'model' }
+                : {}),
+            toolCalls: collected.toolCalls,
+            steps: collected.steps,
+            renderEvidence,
+            ...(collected.usage ? { usage: collected.usage } : {}),
+            ...(options.generationCallBudget
+                ? { callBudget: options.generationCallBudget.receipt() }
+                : {}),
+            ...(metrics.wasCapped() ? { capped: true } : {}),
+            ...(lastText ? { lastText } : {}),
+            ...(finalizationError ? { error: finalizationError } : {}),
+        };
+    }
+    catch (error) {
+        const collected = metrics.readMetrics();
+        return {
+            world: state.world,
+            worldHash: await hashWorldDocumentV2(state.world),
+            placements: placements(state.world),
+            finalized: finalized.value,
+            toolCalls: collected.toolCalls,
+            steps: collected.steps,
+            renderEvidence,
+            ...(collected.usage ? { usage: collected.usage } : {}),
+            ...(options.generationCallBudget
+                ? { callBudget: options.generationCallBudget.receipt() }
+                : {}),
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        metrics.detach();
+    }
+}

package/lib/composer/agent/world-tools.d.ts

@@ -0,0 +1,20 @@
+/** Bounded Strands tool surface for canonical Composer V2 integration primitives. */
+import { type Tool } from '@strands-agents/sdk';
+import { type ColliderArtifactV1, type ResolveAuthoredColliderGeometryV1Port, type HeightfieldArtifactV1, type WorldDocumentV2 } from "../index.js";
+export interface WorldIntegrationToolState {
+    world: WorldDocumentV2;
+}
+export interface MakeWorldIntegrationToolsV2Options {
+    state: WorldIntegrationToolState;
+    publishHeightfieldArtifact?: (artifact: HeightfieldArtifactV1, bytes: Uint8Array, sha256: string) => Promise<{
+        uri: string;
+        mediaType?: string;
+    }>;
+    publishColliderArtifact?: (artifact: ColliderArtifactV1, bytes: Uint8Array, sha256: `sha256:${string}`) => Promise<{
+        uri: string;
+        mediaType?: string;
+    }>;
+    resolveAuthoredColliderGeometry?: ResolveAuthoredColliderGeometryV1Port;
+    onWorldChanged?: (world: WorldDocumentV2) => void;
+}
+export declare function makeWorldIntegrationToolsV2(options: MakeWorldIntegrationToolsV2Options): Tool[];

package/lib/composer/agent/world-tools.js

@@ -0,0 +1,311 @@
+/** Bounded Strands tool surface for canonical Composer V2 integration primitives. */
+import { tool } from '@strands-agents/sdk';
+import { z } from 'zod';
+import { AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1, AUTHORED_COLLIDER_GEOMETRY_V1_SCHEMA_VERSION, ColliderCompileError, ColliderPolicyV1Schema, compileColliderArtifactV1, encodeColliderArtifactV1, hashColliderArtifactV1, parseAuthoredColliderGeometryV1, createHeightfieldArtifactV1, encodeHeightfieldArtifactV1, hashHeightfieldArtifactV1, fillWorldPathV2, setWorldPathsV2, setWorldPresentationV1, setWorldSocketsV2, setWorldSpawnsV2, setWorldTerrainV2, setWorldZonesV2, snapWorldObjectToSocketV2, PresentationParametersV1Schema, parseWorldDocumentV2, } from "../index.js";
+const finite = z.number().finite();
+const vec2 = z.tuple([finite, finite]);
+const vec3 = z.tuple([finite, finite, finite]);
+const id = z.string().min(1).max(256);
+const positiveVec2 = z.tuple([finite.positive(), finite.positive()]);
+export function makeWorldIntegrationToolsV2(options) {
+    const commit = (world) => {
+        options.state.world = world;
+        options.onWorldChanged?.(world);
+        return { ok: true, worldId: world.worldId };
+    };
+    const guarded = (operation) => {
+        try {
+            return commit(operation());
+        }
+        catch (error) {
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    };
+    const setZones = tool({
+        name: 'scene_world_set_zones',
+        description: 'Replace bounded reserved/portal/spawn-clearance zones. Rect halfExtents must be positive.',
+        inputSchema: z
+            .object({
+            zones: z
+                .array(z
+                .object({
+                id,
+                kind: z.enum(['reserved', 'portal-clearance', 'spawn-clearance']),
+                shape: z.discriminatedUnion('type', [
+                    z
+                        .object({ type: z.literal('rect'), center: vec2, halfExtents: positiveVec2 })
+                        .strict(),
+                    z
+                        .object({ type: z.literal('circle'), center: vec2, radius: finite.positive() })
+                        .strict(),
+                ]),
+            })
+                .strict())
+                .max(32),
+        })
+            .strict(),
+        callback: (input) => guarded(() => setWorldZonesV2(options.state.world, input.zones)),
+    });
+    const setPaths = tool({
+        name: 'scene_world_set_paths',
+        description: 'Replace authored navigational paths using world-space X/Y/Z points.',
+        inputSchema: z
+            .object({
+            paths: z
+                .array(z
+                .object({
+                id,
+                points: z.array(vec3).min(2).max(64),
+                halfWidth: finite.positive(),
+            })
+                .strict())
+                .max(16),
+        })
+            .strict(),
+        callback: (input) => guarded(() => setWorldPathsV2(options.state.world, input.paths)),
+    });
+    const setSockets = tool({
+        name: 'scene_world_set_sockets',
+        description: 'Replace named anchors/portals with compatibility, capacity, and portal clearance.',
+        inputSchema: z
+            .object({
+            sockets: z
+                .array(z
+                .object({
+                id,
+                kind: z.enum(['anchor', 'portal']),
+                position: vec3,
+                rotationYDeg: finite,
+                compatibilityTags: z.array(z.string().min(1).max(128)).min(1).max(16),
+                capacity: z.number().int().min(1).max(8),
+                clearanceRadius: finite.positive().optional(),
+            })
+                .strict())
+                .max(32),
+        })
+            .strict(),
+        callback: (input) => guarded(() => setWorldSocketsV2(options.state.world, input.sockets)),
+    });
+    const setSpawns = tool({
+        name: 'scene_world_set_spawns',
+        description: 'Replace player/actor spawns, each with a positive clearance radius.',
+        inputSchema: z
+            .object({
+            spawns: z
+                .array(z
+                .object({
+                id,
+                position: vec3,
+                rotationYDeg: finite,
+                clearanceRadius: finite.positive(),
+            })
+                .strict())
+                .max(16),
+        })
+            .strict(),
+        callback: (input) => guarded(() => setWorldSpawnsV2(options.state.world, input.spawns)),
+    });
+    const setPresentation = tool({
+        name: 'scene_world_set_presentation',
+        description: 'Replace persisted ordered camera/grid/lighting/receipt parameters. Do not send artifactBinding; Engine binds the post-edit world hash. Total requested pixels are capped at 16,777,216.',
+        inputSchema: z.object({ presentation: PresentationParametersV1Schema }).strict(),
+        callback: (input) => guarded(() => setWorldPresentationV1(options.state.world, input.presentation)),
+    });
+    const setCollision = tool({
+        name: 'scene_world_set_collision',
+        description: 'Set one object collision policy to none, asset bounds, selected authored GLB mesh nodes, or a deterministic generated bounds-box artifact. Artifact policies require bounded host ports.',
+        inputSchema: z.object({ objectId: id, policy: ColliderPolicyV1Schema }).strict(),
+        callback: async (input) => {
+            try {
+                const object = options.state.world.objects.find((candidate) => candidate.id === input.objectId);
+                if (!object)
+                    return { ok: false, error: `unknown object "${input.objectId}"` };
+                const asset = options.state.world.assets.find((candidate) => candidate.refId === object.assetRefId);
+                if (!asset)
+                    return { ok: false, error: `missing asset for "${input.objectId}"` };
+                if (input.policy.kind === 'none' || input.policy.kind === 'bounds') {
+                    const objects = options.state.world.objects.map((candidate) => candidate.id === object.id
+                        ? { ...candidate, collision: { policy: input.policy.kind } }
+                        : candidate);
+                    const referenced = new Set(objects.flatMap((candidate) => candidate.collision?.policy === 'artifact' ? [candidate.collision.artifactRefId] : []));
+                    return commit(parseWorldDocumentV2({
+                        ...options.state.world,
+                        objects,
+                        collisionArtifacts: options.state.world.collisionArtifacts.filter((artifact) => referenced.has(artifact.refId)),
+                    }));
+                }
+                if (input.policy.kind === 'authored-submesh' && !options.resolveAuthoredColliderGeometry) {
+                    return {
+                        ok: false,
+                        error: 'authored collider geometry resolver is not configured',
+                    };
+                }
+                if (!options.publishColliderArtifact) {
+                    return { ok: false, error: 'collider artifact publisher is not configured' };
+                }
+                const sourceArtifactSha256 = `sha256:${asset.artifactSha256}`;
+                let artifact;
+                if (input.policy.kind === 'authored-submesh') {
+                    const resolved = parseAuthoredColliderGeometryV1(await options.resolveAuthoredColliderGeometry(Object.freeze({
+                        schemaVersion: AUTHORED_COLLIDER_GEOMETRY_V1_SCHEMA_VERSION,
+                        sourceArtifactSha256,
+                        transformFrame: 'asset-local',
+                        nodeNames: Object.freeze([...input.policy.nodeNames]),
+                        limits: AUTHORED_COLLIDER_GEOMETRY_LIMITS_V1,
+                    })));
+                    if (resolved.sourceArtifactSha256 !== sourceArtifactSha256) {
+                        throw new ColliderCompileError('COLLIDER_SOURCE_HASH_MISMATCH', 'resolved collider geometry does not match the selected asset hash');
+                    }
+                    const requested = new Set(input.policy.nodeNames);
+                    const returned = new Set(resolved.submeshes.map((entry) => entry.nodeName));
+                    const missing = input.policy.nodeNames.filter((nodeName) => !returned.has(nodeName));
+                    if (missing.length) {
+                        throw new ColliderCompileError('COLLIDER_AUTHORED_SUBMESH_MISSING', `missing authored collider node(s): ${missing.join(', ')}`);
+                    }
+                    const unexpected = resolved.submeshes
+                        .map((entry) => entry.nodeName)
+                        .filter((nodeName) => !requested.has(nodeName));
+                    if (unexpected.length) {
+                        throw new ColliderCompileError('COLLIDER_AUTHORED_SUBMESH_INVALID', `resolver returned unrequested collider node(s): ${unexpected.join(', ')}`);
+                    }
+                    artifact = compileColliderArtifactV1(input.policy, {
+                        sourceArtifactSha256,
+                        bounds: asset.bounds,
+                        authoredSubmeshes: resolved.submeshes,
+                    });
+                }
+                else {
+                    artifact = compileColliderArtifactV1(input.policy, {
+                        sourceArtifactSha256,
+                        bounds: asset.bounds,
+                    });
+                }
+                const bytes = encodeColliderArtifactV1(artifact);
+                const sha256 = await hashColliderArtifactV1(artifact);
+                const published = await options.publishColliderArtifact(artifact, bytes, sha256);
+                const refId = `collision:${sha256.slice('sha256:'.length)}`;
+                const objects = options.state.world.objects.map((candidate) => candidate.id === object.id
+                    ? { ...candidate, collision: { policy: 'artifact', artifactRefId: refId } }
+                    : candidate);
+                const referenced = new Set(objects.flatMap((candidate) => candidate.collision?.policy === 'artifact' ? [candidate.collision.artifactRefId] : []));
+                const collisionArtifacts = [
+                    ...options.state.world.collisionArtifacts.filter((candidate) => candidate.refId !== refId && referenced.has(candidate.refId)),
+                    {
+                        refId,
+                        artifact: {
+                            uri: published.uri,
+                            sha256: sha256.slice('sha256:'.length),
+                            mediaType: published.mediaType ?? 'application/vnd.kiln.collider+json',
+                        },
+                    },
+                ];
+                const result = commit(parseWorldDocumentV2({
+                    ...options.state.world,
+                    objects,
+                    collisionArtifacts,
+                }));
+                return { ...result, sha256, bytes: bytes.byteLength };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    });
+    const snap = tool({
+        name: 'scene_world_snap',
+        description: 'Snap one compatible object exactly to a named socket; fails when incompatible or full.',
+        inputSchema: z.object({ objectId: id, socketId: id }).strict(),
+        callback: (input) => guarded(() => snapWorldObjectToSocketV2(options.state.world, input)),
+    });
+    const fillPath = tool({
+        name: 'scene_world_fill_path',
+        description: 'Repeat one existing object along a path with deterministic arc-length spacing and tangent facing.',
+        inputSchema: z
+            .object({
+            pathId: id,
+            templateObjectId: id,
+            idPrefix: z.string().min(1).max(240),
+            count: z.number().int().min(1).max(32),
+            spacing: finite.positive(),
+            startDistance: finite.nonnegative().optional(),
+        })
+            .strict(),
+        callback: (input) => guarded(() => fillWorldPathV2(options.state.world, input)),
+    });
+    const stampSchema = z.discriminatedUnion('kind', [
+        z
+            .object({
+            kind: z.enum(['road', 'path']),
+            points: z.array(vec2).min(2).max(64),
+            halfWidth: finite.positive(),
+            targetHeight: finite,
+        })
+            .strict(),
+        z
+            .object({
+            kind: z.literal('pad'),
+            center: vec2,
+            halfExtents: positiveVec2,
+            targetHeight: finite,
+        })
+            .strict(),
+    ]);
+    const setHeightfield = tool({
+        name: 'scene_world_set_heightfield',
+        description: 'Generate and bind one bounded seeded heightfield with optional road/path/pad stamps.',
+        inputSchema: z
+            .object({
+            origin: vec2,
+            cellSize: finite.positive(),
+            width: z.number().int().min(2).max(129),
+            height: z.number().int().min(2).max(129),
+            baseHeight: finite,
+            amplitude: finite.nonnegative(),
+            frequency: finite.positive(),
+            stamps: z.array(stampSchema).max(16),
+        })
+            .strict(),
+        callback: async (input) => {
+            if (!options.publishHeightfieldArtifact)
+                return {
+                    ok: false,
+                    error: 'heightfield artifact publisher is not configured',
+                };
+            try {
+                const artifact = createHeightfieldArtifactV1({ ...input, seed: options.state.world.seed });
+                const bytes = encodeHeightfieldArtifactV1(artifact);
+                const sha256 = await hashHeightfieldArtifactV1(artifact);
+                const published = await options.publishHeightfieldArtifact(artifact, bytes, sha256);
+                const result = commit(setWorldTerrainV2(options.state.world, {
+                    kind: 'heightfield',
+                    artifact: {
+                        uri: published.uri,
+                        sha256,
+                        mediaType: published.mediaType ?? 'application/vnd.kiln.heightfield+json',
+                    },
+                }));
+                return { ...result, sha256, bytes: bytes.byteLength };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    });
+    return [
+        setZones,
+        setPaths,
+        setSockets,
+        setSpawns,
+        setPresentation,
+        setCollision,
+        snap,
+        fillPath,
+        setHeightfield,
+    ];
+}