cavern-asset-bake — designer flow and process contract

This directory owns the Phase 14 workload definition. Godot owns the editable mask/settings Resource, the output asset, the scene integration, and the editor UI; the pure Odin cavern kernel does the substantial computation; the existing six-stage build authority remains the only compiler and publication owner. This admits one native tool, not a general cooking or EditorPlugin framework.

Resources

• Request — res://bake/bake_request.tres, a CaveBakeRequest Resource: one occupancy mask (Image, 8-bit L8, 0/255) plus the settings fields the kernel already validates (smoothing_steps, minimum_region_size). The designer edits it in the Inspector with the editor's own undo.
• Output — res://bake/cave_bake_data.tres, a CaveBakeData Resource: the baked floor grid (PackedByteArray), its width/height, the kernel diagnostics hash, the request digest it was baked from, and the native source revision that produced it.
• Destination policy — the output path is fixed by the request Resource's output_path; one request owns exactly one destination asset.

Designer flow

1. Edit — the designer changes the mask or settings on the request Resource. Inspector edits use the editor's standard undo/redo; nothing here touches the output asset.
2. Bake — the Bake Shell (a GDScript panel in the authoring editor, or its scripted equivalent in evidence runs) saves the request, then launches one bounded headless child process: the same editor binary, this project, --headless --script res://bake/bake_process.gd, with the request path, output path, and the request digest as user arguments. The child loads the current accepted native image through the standard runtime staging contract (the same environment gododin run uses) and runs the pure kernel's process_mask on the mask bytes.
3. Inspect — when the child prints GODODIN_BAKE_PUBLISH, the destination asset has been atomically replaced; the scene reimport/reload picks it up on the next open or explicit reload, and the shell's preview refreshes from the file. The shell streams the child's sentinels into its log.
4. Cancel — the shell may cancel an outstanding bake: it terminates the child process. A cancelled bake never touches the destination.
5. Repair — if the child cannot load an accepted image (GODODIN_BAKE_NOIMAGE), the shell surfaces the diagnostic and the normal rebuild path (the editor addon / gododin build) repairs it; the bake shell never compiles, links, or stages an artifact itself.
6. Reopen/reimport — the output is an ordinary Resource. On reopen, the freshness state below decides the inspector badge; the asset stays loadable in every state.

Identity and freshness

• Request digest — SHA-256 over the canonicalized mask bytes plus the settings fields, computed by the shell before launch and recomputed inside the child before processing. A mismatch fails the bake; the shell never bakes a request it cannot digest identically to the child. (The engine exposes plain SHA-256 over files, so the shared digest helper hashes the canonical bytes through a per-process temporary file.)
• Output identity — the destination ResourcePath plus the recorded request digest and native source revision. Deterministic repeat: the same digest and the same pure kernel produce an identical payload and provenance — grid bytes, dimensions, diagnostics, digest, and revision — asserted by the campaign. The serialized .tres itself is not byte-compared: the engine writes a fresh resource UID into every save, and the kernel's wall-clock generation_usec is a measurement, not identity.
• Freshness — FRESH when the asset's recorded digest equals the current request digest; STALE when it differs; MISSING before the first successful bake. Staleness is a badge, never a blocker: the last valid asset remains loaded, exported, and inspectable.
• Undo/redo — request edits are undoable through the Inspector's own history. Output publication is a file replacement, not an editor action, so it is recorded in the shell log instead of the undo history; this is stated behavior, not a gap.

Ownership, failure, and publication bounds

• One outstanding bake per request resource. Launching a new bake supersedes the outstanding one: the child is terminated and its partial output ignored.
• The child validates the kernel result (bounds, border safety, single-region validation, expected byte count) before publication. Publication is atomic: write to a temporary file in the same directory, then rename over the destination. A failed, cancelled, or superseded bake preserves the last valid asset byte for byte.
• Process failure — non-zero exit, missing sentinel, or timeout — is bounded: the shell reports BAKE_FAILED with the child's log tail and keeps the last valid asset. The child owns native execution; project native code never runs inside the recovery shell or the panel.
• The child keeps no engine state beyond the run: no scene is saved, no editor state is read, and the process exits after publishing or failing.

The committed designer asset

The configured project carries one committed product of this flow: live/project/bake/cave_bake_request.tres (a 256x192 L8 mask with smoothing 5 and minimum region 48) and its published destination live/project/bake/cave_bake_data.tres. They were produced by the real shell and supervised child through bake_authoring.gd, which also verifies the published asset the way a consumer does — freshness against the recomputed request digest and oracle parity with the accepted kernel. Exported applications consume this asset in a bake-consume self-check: the app loads the asset, recomputes the digest, verifies FRESH and kernel parity through the normal installed-image path, and tears down with zero owners. The harness gates both export profiles on that sentinel and on a bundle closure with no compiler, OLS, or CLI helper (verify_bake_export.py).

Evidence obligations (Phase 14 bullets)

The real-editor exercises run through the bake_probe plugin (live/project/editor/bake_probe/, a no-op outside the exercise mode): the no-image editor drives the real shell into the unavailable-image refusal with the destination preserved, and the accepted-image editor proves deterministic repeat, mid-bake cancellation, native-process failure, the stale reimport through the editor's own import pipeline, and two consumers sharing the cached request Resource (bake_editor=true in the installed sentinel). Editor reload while a bake is outstanding is exercised in the same real-editor run as the background workload's reload exercise (the harness signals the probe when the addon's rebuild child exits, so the supervised bake child is in flight when reload_extension lands; reload=true in the installed sentinel). The shared C3 checkpoint is complete: the SDK/user docs and the affected release-matrix rows updated with it.