DONE Trace one real frame with nested CPU zones #OHNIWM

Intent: make a coarse frame explanation one ordinary benchmark away, with an opt-in macro whose disabled path neither constructs events nor changes backend control flow.

Evidence:

• The trace buffer records a zone name, parent, depth, monotonic start/end ticks, allocated bytes, garbage-collection time, and collections crossing the extent. with-cpu-trace-zone is a thin unwind-protect wrapper; buffers reuse event and stack storage after their first capture. The same module provides with-runtime-observation for a retained aggregate when a benchmark needs time, allocation, and GC evidence without a zone tree.
• The SDL request boundary explicitly carries the selected trace onto the native frame thread. Dynamic Lisp bindings alone do not cross that thread handoff.
• Both presentation backends name the same semantic acquisition, encoding, finish, submit, and present regions. Backend-only work remains visibly named :metal/... or :vulkan/... inside its implementation.
• The existing benchmark phases now compose with those zones, so luvcraft contributes simulation, streaming, shader refresh, mesh publication, uniform update, shadow, scene, and surface-copy regions without asking which backend owns the encoder.
• benchmark-luvcraft-frame-performance still measures its ordinary batch without tracing. It then warms the reusable trace buffer and prints one separate representative frame.

One standalone Apple M2 Pro run measured 60 steady frames at an 8.367 ms CPU median and then printed this representative structure:

luvcraft/frame                         7.376 ms
  luvcraft/presentation                7.365 ms
    canvas/frame                       7.363 ms
      canvas/acquire-drawable          5.747 ms
      metal/allocate-frame-resources   0.099 ms
      gpu/encode                       1.146 ms
        luvcraft/mesh-publication      0.403 ms
        luvcraft/shadow-pass           0.383 ms
        luvcraft/scene-pass            0.223 ms
      gpu/submit                       0.242 ms

That single frame is localization evidence, not a distribution. The adjacent fixed metrics retain median, p95, mean, and maximum across the measured batch. More zones should be added only when a coarse region earns a focused question.

Done when (met): a real frame produces a bounded nested report across the native thread handoff, the untraced benchmark remains the comparison baseline, tests prove nesting and storage reuse, and Vulkan and Metal smoke paths remain valid.

Mentioned in: Ambient telemetry is a bounded semantic skeleton

DONE Convert the outer runtime boundaries #G3CFYX

Intent: make one ordinary live capture explain the outer event, frame, production, streaming, simulation, and overlay structure before adding the denser subsystem waves in #1G3ORG.

Evidence: the communicator instrumentation already localized a roughly 5.4 MB keypress repaint to about 4.4 MB of McCLIM command preparation. The new zdefun, zdefmethod, and zone forms have a zero-allocation disabled path, while #7SOIWP supplies a bounded admission rule for wider coverage.

Done when: SDL requests/events and frame ownership, luvcraft frame and simulation ownership, production scheduling/draining/publication, top-level streaming phases, and overlay refresh/encode each have stable ambient zones; loop owners attach semantic counts; a representative live capture stays legible rather than emitting per-element spans; and the relevant tests and both source-structure checks pass.

Outcome: forty-two outer functions and methods now use the concise zoned definition forms. SDL request draining, event dispatch, and native frame service; Vulkan and Metal frame ownership; production request, worker, and publication transactions; the streaming reconciliation phases; fixed-step simulation; frame encoding; terminal and McCLIM overlay refresh, preparation, and encoding all have stable semantic names. Scheduling, publication, fixed-step, and retained-command owners carry their natural work counts.

A live focused-phone frame produced 54 CPU zones and remained a readable frame -> simulation/streaming/presentation -> overlay tree. It attributed about 4.36 MiB in total, including the terminal -> Telegram -> McCLIM overlay path, without per-glyph, per-cell, or per-command spans. Caller-side request-canvas-frame and call-on-sdl-canvas-thread deliberately remain ordinary definitions: the former transports the same opt-in CPU trace onto the native thread, so opening that trace on both sides would manufacture cross-thread nesting. Native request draining and frame service provide the honest ownership zones instead.

The full test matrix, strict Parinfer source check, cold luvcraft system load, and wiki build pass with this coverage.

DONE Stream one chunk window under measurement #887PO7

Intent: measure the frames where traversal creates real asynchronous chunk load, lighting, mesh, GPU upload, and publication work, rather than infer that cost from the fully resident steady benchmark.

Evidence:

LUVCRAFT_BENCHMARK_FRAMES=240 make metal-streaming-benchmark

This begins from the same settled 9 by 9 resident world as the steady case, then moves the player one chunk in +X at the measured boundary. One edge of nine chunks leaves and one edge of nine genuinely new chunks enters. Every CSV frame now records resident chunks, pending production, staged products, and rendered products; the printed transition summary stops at the first frame where residency, meshes, and the worker are settled again.

The first Apple M2 Pro run settled at frame 57. Across those 58 transition frames, CPU frame time had an 8.453 ms median, 43.225 ms p95, and 46.078 ms maximum; 10 frames exceeded the 16.667 ms 60 Hz deadline. The worst repeated cost was not worker generation: owner-side mesh/lighting publication reached 42.209 ms. This is now a reproducible hitch and a next optimization target, not a claim that streaming performance is solved.

Done when (met): one command produces a bounded steady/streaming comparison, names how many chunks entered and when the transition settled, reports 60 Hz deadline misses, and leaves per-frame lifecycle counts in a comparison-ready CSV.

TODO Reuse Metal frame submission resources #YKITZ8

Intent: stop constructing and releasing one MTL4CommandAllocator and one MTL4CommandBuffer for every frame when a bounded frame-slot owner can reuse them safely.

Evidence: the current trace exposes :metal/allocate-frame-resources as a separate region, and source inspection confirms that both native objects are created after every drawable acquisition. The representative frame above spent 0.099 ms there. That one number is not a stable estimate, but it makes the ownership experiment measurable. #JAM5XR is the related lifetime work: reuse must follow the shared-event frontier rather than reintroduce a queue stall.

Done when: a bounded Metal frame-slot structure owns reusable submission resources, the completion frontier prevents early reuse, traces show the creation region absent from steady frames, allocation and frame distributions improve in a repeated A/B run, and API validation remains clean.

TODO Separate drawable pacing from encoding distributions #JBZ4SC

Intent: report how much host frame time is runnable encoding work and how much is waiting for presentation availability, instead of treating both as one “encoding” number.

Evidence: native sampling after #WEE1DX found the frame thread mostly sleeping inside CAMetalLayer nextDrawable, while the instrumented representative frame above localized 5.747 ms to drawable acquisition and 1.146 ms to the inclusive encoding region. These are compatible observations from different windows, not a fixed ratio.

Done when: repeated captures summarize drawable-acquisition and encoding distributions separately for Metal and Vulkan, the benchmark explains which intervals include pacing, and eventual GPU timestamps remain a distinct measurement rather than being inferred from host waits.