Ppu Acu Joint Profile

Start coarse

Read references/recorder.md, then choose the smallest topology that can separate the current alternatives. Examples are choices, not defaults:

• one representative writer around major mainloop and epilogue phases;
• a few owners for blocks or worker roles expected to behave differently;
• one comparable range from every block only for a dispatch, imbalance, or tail question;
• a writer other than thread 0 when that thread or warp owns the operation being studied.

Set capture_mode: "coarse", record the selection in sampling_rationale, and enumerate the exact (owner, block, thread) writers. Compile the temporary snapshot with PPU_TIMELINE_ENABLED:

#include "ppu_timeline.cuh"
namespace ptl = ppu_acu_profile::timeline;

const bool selected_writer = /* exact block/thread/role predicate */;
const unsigned owner = /* dense id for that selected writer */;
ptl::Recorder trace(params.timeline_buffer, owner, selected_writer);

trace.range_begin(10);  // one semantic coarse phase
// Existing kernel work; control flow and synchronization stay unchanged.
trace.range_end(10);

When an immediate record write would perturb the region being measured, capture only the timer at the real boundaries and flush the pair later, in chronological order, after the sensitive work:

const auto phase_begin = trace.timestamp();
// Existing sensitive work.
const auto phase_end = trace.timestamp();
// Flush outside the sensitive region; do not insert synchronization to move this flush.
trace.range_at(10, phase_begin, phase_end);

Use immediate writes when their cost does not change the conclusion. Use deferred writes when a density check shows local interval distortion or when the hypothesis concerns a short critical region. A deferred timestamp reduces the boundary operation to the timer read; it does not make the capture probe-free, and records must still be flushed in owner-local timestamp order.

Do not add barriers, waits, atomics, predicates, or control-flow changes to simplify the trace. Map each timestamp to a real semantic boundary. An asynchronous issue marker is not completion; observe the original wait, barrier, or first dependent consume when completion matters.

Use the target project's real PPU compiler, runtime, architecture flags, and launch path; do not replace them with a standalone CUDA-SDK executable or a synthetic launch route.

For a remote attempt, read references/remote-capture.md. Upload this skill as an explicit sandbox input, keep clean/instrumented snapshots under one attempt directory, decode before the remote job exits, and synchronize only that attempt's evidence.

Read references/recorder.md for the timer contract, optional sanity experiment with a declared error bound, and correctness artifact requirements. The decoder rejects timer_tick_ns, timer_calibration, invalid source/unit declarations, and correctness evidence that does not pass for the exact kernel, workload, and device.

Initialize the ABI buffer on the host, copy it to the device, launch once, synchronize, and copy the entire allocation back. Emit manifest v5 and the event dictionary from actual launch and source facts, then decode:

python "$PPU_PROFILE_SKILL/scripts/timeline.py" decode \
  --raw coarse.timeline.bin \
  --manifest coarse.timeline.manifest.json \
  --event-dictionary coarse.timeline.events.json \
  --output-prefix coarse.timeline

Use only an accepted receipt. A diagnostic receipt is intentionally incomplete and may answer a local exploratory question; a joint merge or terminal-reusable conclusion requires a decision-grade receipt with source, compiled-binary, and workload-input bindings. If the coarse trace answers the question, stop without fine probes, ACU, or merge. Read references/timeline_contract.md when interpreting decoder outputs or preparing a fine capture for optional joint analysis.

Refine only the unresolved region

Create a new reversible fine snapshot only when coarse evidence leaves a narrower question. Retain the minimum context and add only the issue/wait/consume or subphase boundaries needed inside that region. Set capture_mode: "fine". A fine timeline remains valid standalone evidence and does not require ACU or merge.py.

Declare analysis.owner, analysis.window_site_id, and analysis.site_ids only when preparing a fine capture for optional joint analysis or when those labels help the standalone interpretation. The decoder rejects declared analysis ranges outside the window. Analyze another owner in another attempt instead of pretending unsynchronized owner clocks share an axis.

Bound probe effects when the claim needs it

Preserve A (clean), B (minimal useful probes), and, only when density sensitivity matters, C (denser nearby probes). Each timing command must warm up, iterate, synchronize, validate the representative output, and emit one __PPU_TIMELINE_SAMPLE__=... JSON line:

python "$PPU_PROFILE_SKILL/scripts/timeline.py" measure \
  --baseline-command '["python","run_a.py"]' \
  --instrumented-command '["python","run_b.py"]' \
  --workload-identity case-id --warmup 10 --iterations 100 \
  --max-relative-change 0.03 \
  --output fine.perturbation-a-b.json

python "$PPU_PROFILE_SKILL/scripts/timeline.py" measure \
  --baseline-command '["python","run_b.py"]' \
  --instrumented-command '["python","run_c.py"]' \
  --workload-identity case-id --warmup 10 --iterations 100 \
  --max-relative-change 0.03 \
  --output fine.perturbation-b-c.json

Every emitted sample includes positive finite latency_ms, correctness: "passed", synchronized: true, the exact workload/warmup/iteration, physical-device and runtime identity, kernel_sha256, cache policy, clock configuration, and a stable allocation_identity such as the authorized Pod UID plus allocation/job id. Measurement v2 also records each command argv hash. The helper rejects any kernel, runtime, cache, clock, device, allocation, or command drift across the interleaved schedule.

A/B measures end-to-end probe overhead; B/C measures the end-to-end effect of probe density. Declare --max-relative-change before the experiment (0.03 above is an example, not a hardware constant). The helper records the bound and rejects an absolute median latency change above it; joint validation recomputes that gate. Compare common owner-local intervals separately when the claim depends on their stability, using a critical-path plan with stability.material_relative_spread. Reduce or move sites when either declared gate fails.

Close an agent-declared critical path when needed

If the question is whether selected subranges explain an enclosing range, or whether the slowest owner is stable across captures, declare the semantic parent and components in a plan and analyze the accepted canonical captures:

python "$PPU_PROFILE_SKILL/scripts/critical_path.py" \
  --plan critical-path.plan.json \
  --capture attempt-1/fine.timeline.canonical.json attempt-1/fine.timeline.receipt.json \
  --capture attempt-2/fine.timeline.canonical.json attempt-2/fine.timeline.receipt.json \
  --output critical-path.report.json

The plan, not the tool, chooses phases, owner-topology comparison, and any material-spread threshold. The analyzer verifies each canonical hash against its receipt and rejects grid, block, capture-mode, identity, or selected-site semantic drift. It computes component interval union rather than double-counting overlap and leaves uncovered time unattributed. Escalate representative owner to more warps or blocks only when the observed spread or remaining topology ambiguity can change the optimization decision. See references/timeline_contract.md for the plan contract.

Route C: Optional joint analysis

Choose this only after ACU and fine timeline were each collected and interpreted independently, and the unresolved question requires their relationship. The fine capture must declare one analysis owner, one enclosing window, and a non-empty site list. Verify kernel, grid, block, workload, device, and duration agreement before interpreting the output (warning above 3%, rejection above 5%; warning evidence cannot enter reusable memory).

python "$PPU_PROFILE_SKILL/scripts/merge.py" \
  --timeline fine.timeline.perfetto.json \
  --timeline-receipt fine.timeline.receipt.json \
  --pm-csv profile.samples.csv \
  --acu-raw-csv profile.raw.csv \
  --acu-metadata profile.extract.json \
  --perturbation fine.perturbation-a-b.json \
  --density-sensitivity fine.perturbation-b-c.json \
  --output-prefix fine.joint

The perturbation and density-sensitivity inputs are optional; pass those flags only when the corresponding validated artifacts exist. Joint merge is fail-closed: it requires decision-grade timeline and ACU bindings, compares kernel specialization, workload, physical device, runtime, cache policy, clock configuration, grid, block, and duration, and has no duration-mismatch override.

Interpret the result as four separate claims:

1. owner-local ordering and dependency intervals from the fine timeline;
2. device-global compute, memory, cache, occupancy, and tail phases from ACU;
3. guaranteed overlap first, then possible overlap under the bounded analysis-owner origin offset;
4. probe overhead, density sensitivity, sampling coverage, and remaining ambiguity.

The merger never aligns raw clocks or rescales either run. The exact optional full-block survival gates are in references/timeline_contract.md.

Finish

Name the selected route in the result and keep its evidence scope explicit. A valid ACU-only or timeline-only conclusion is complete without a joint artifact. Restore the probe-free kernel and use the normal evaluator for final correctness and performance; profile evidence does not replace the probe-free result.