Cleanup a5 host_build_graph header guards and stale docs

.claude/rules/codestyle.md

@@ -197,3 +197,24 @@
     comments for no functional gain. If the tree is ever to be unified in one
     go, it needs its own decision plus a lint rule to hold the line — not a
     hand-edited PR.
+
+12. **Use `#pragma once` for header guards, not `#ifndef`/`#define`/`#endif`.**
+
+    ```cpp
+    // Good
+    #pragma once
+
+    // Bad
+    #ifndef SRC_A5_RUNTIME_FOO_H_
+    #define SRC_A5_RUNTIME_FOO_H_
+    ...
+    #endif  // SRC_A5_RUNTIME_FOO_H_
+    ```
+
+    There is no compiler this project targets (gcc, clang, ccec, all C++17)
+    that does not support it.  `#pragma once` is one line rather than three,
+    cannot have the guard name disagree with the file's actual path, and does
+    not leave a trailing `#endif` that can detach from its `#if` when the
+    convertor ojects the `#ifndef` but misses the `#endif`.  Existing files
+    are converted on sight during routine edits; a dedicated sweep is not
+    required.

docs/dfx/args-dump.md

@@ -67,7 +67,8 @@ python tests/st/<case>/test_<name>.py -p a2a3 -d 0 --dump-args   # partial (leve
 
 # pytest
 pytest tests/st/<case> --platform a5sim --dump-args 2
-pytest examples/a5/host_build_graph/vector_example --platform a5sim --dump-args 2
+# a5 host_build_graph has no examples — use the scene test
+pytest tests/st/a5/host_build_graph/dump_args --platform a5sim --dump-args 2
 ```
 
 The level sets `CallConfig::enable_dump_args` (0/1/2/3). The host then
@@ -305,24 +306,14 @@ independent (added via `add_scalar`) and are typically omitted. If a
 `SCALAR` direction *is* listed it must come after every tensor entry; the
 dump skips `SCALAR` entries (they do not consume a positional tensor slot).
 
-`host_build_graph` has no incore signatures, so it needs explicit
-`TensorInfo` wiring instead (geometry is still automatic):
-
-```cpp
-// In orchestration C++ (host_build_graph only)
-TensorInfo info_a = make_tensor_info_from_tensor_arg(orch_args.tensor(0));
-TensorInfo info_b = make_tensor_info_from_tensor_arg(orch_args.tensor(1));
-TensorInfo info_f = make_tensor_info_from_tensor_arg(orch_args.tensor(2));
-
-int t0 = add_task(runtime, args_t0, 4, /*func_id=*/0, CoreType::AIV);
-TensorInfo t0_info[] = {info_a, info_b, info_f};
-set_tensor_info_to_task(runtime, t0, t0_info, 3);
-
-// Or in one call
-int t1 = add_task_with_tensor_info(
-    runtime, args_t1, /*num_args=*/3, /*func_id=*/1, CoreType::AIV,
-    t1_info, /*tensor_count=*/1);
-```
+Both `host_build_graph` and `tensormap_and_ringbuffer` share the
+same code path: the AICPU dump-collector reads geometry directly from
+`PTO2TaskPayload::tensors[]`, which carries shape and offset info
+alongside the device-packed arguments. For allocated output tensors,
+`alloc_tensors` supplies a `TensorCreateInfo` at orchestration time
+that is embedded in the payload by submit. For tensors that already
+exist (inputs passed by the caller), the geometry travels directly on
+the Tensor object and needs no explicit per-task registration.
 
 Full template:
 [`tests/st/a5/host_build_graph/dump_args`](../../tests/st/a5/host_build_graph/dump_args/)
@@ -460,22 +451,15 @@ non-dump runs keep the original cheaper completion path.
 ### 5.3 Tensor metadata registration
 
 AICPU has device addresses and sizes — the logical shape, dtype,
-and view geometry come from the runtime. Each runtime exposes
-metadata through a slightly different path, but they all converge
-on `TensorInfo` (see
-[`tensor_info.h`](../../src/a5/runtime/host_build_graph/runtime/tensor_info.h)):
-
-- **`host_build_graph`** — two orchestration-side APIs:
-  - `add_task()` → `set_tensor_info_to_task(task_id, info[], count)`
-  - `add_task_with_tensor_info()` (single-call convenience wrapper)
-
-  See
-  [`dump_args_orch.cpp`](../../tests/st/a5/host_build_graph/dump_args/kernels/orchestration/dump_args_orch.cpp)
-  for both styles in one file.
-- **`tensormap_and_ringbuffer`** — runtime layer fills `TensorInfo`
-  from `PTO2TaskPayload::tensors[]` directly. The ring buffer
-  carries `PTO2TaskPayload` which already contains shape/offset
-  arrays, so no orchestration API is needed.
+and view geometry come from the runtime. Both `host_build_graph`
+and `tensormap_and_ringbuffer` share the same code path: the
+AICPU dump-collector reads geometry directly from
+`PTO2TaskPayload::tensors[]`, which carries shape and offset info
+alongside the device-packed arguments. For allocated output tensors,
+`alloc_tensors` supplies a `TensorCreateInfo` at orchestration time
+that is embedded in the payload by submit. For tensors that already
+exist (inputs passed by the caller), the geometry travels directly
+on the Tensor object and needs no explicit per-task registration.
 
 When metadata is missing or inconsistent, the task is skipped for
 dump and a single `LOG_WARN` is emitted (guarded by
@@ -887,13 +871,15 @@ most likely at the default partial level (`--dump-args` = level 1)
 with no `L0TaskArgs::dump(...)` markers in the orchestration, so every task is
 skipped. Add markers (§3.2), or pass `--dump-args 2` for a full dump.
 
-**Manifest has tasks but `tensors[]` is empty.** AICPU received a
-task whose `TensorInfo` was missing or inconsistent. Look for a
+**Manifest has tasks but expected tensor records are missing.** A
+AICPU received a payload whose tensor count or metadata did not
+match what the orchestrator registered. A scalar-only task will
+have zero tensors and is intentionally empty. Look for a
 `LOG_WARN` from `try_log_dump_args_layout_mismatch` — it
 identifies the first mismatched task, then is suppressed to avoid
-log flooding. For `host_build_graph`, ensure
-`set_tensor_info_to_task` (or
-`add_task_with_tensor_info`) was called for every task.
+log flooding. Ensure every task that expects a tensor output calls
+`alloc_tensors` with a `TensorCreateInfo`, and every input tensor
+is added via `add_input` / `add_output` / `add_inout`.
 
 **`AFTER_COMPLETION` data looks stale or partially written.** This
 should not happen with the runtime barrier in place — AICore

src/a5/runtime/host_build_graph/common/pto_runtime_status.h

@@ -15,8 +15,7 @@
  * Shared error-code contract used inside the tensormap_and_ringbuffer runtime.
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_COMMON_PTO_RUNTIME_STATUS_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_COMMON_PTO_RUNTIME_STATUS_H_
+#pragma once
 
 #include <stdint.h>
 
@@ -49,5 +48,3 @@ static inline int32_t runtime_status_from_error_codes(int32_t orch_error_code, i
     }
     return 0;
 }
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_COMMON_PTO_RUNTIME_STATUS_H_

src/a5/runtime/host_build_graph/runtime/aicore_completion_mailbox.h

@@ -9,8 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_AICORE_COMPLETION_MAILBOX_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_AICORE_COMPLETION_MAILBOX_H_
+#pragma once
 
 #include <atomic>
 #include <cstdint>
@@ -185,5 +184,3 @@ struct AICoreCompletionMailbox {
 static_assert(
     sizeof(AICoreCompletionMailbox) % PTO2_ALIGN_SIZE == 0, "AICoreCompletionMailbox size must be cache-line aligned"
 );
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_AICORE_COMPLETION_MAILBOX_H_

src/a5/runtime/host_build_graph/runtime/aicore_completion_mailbox_types.h

@@ -9,8 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_AICORE_COMPLETION_MAILBOX_TYPES_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_AICORE_COMPLETION_MAILBOX_TYPES_H_
+#pragma once
 
 #include <stdint.h>
 
@@ -63,5 +62,3 @@ static_assert(
     sizeof(DeferredCompletionSlab) % PTO2_ALIGN_SIZE == 0,
     "DeferredCompletionSlab size must preserve array element cache-line boundaries"
 );
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_AICORE_COMPLETION_MAILBOX_TYPES_H_

src/a5/runtime/host_build_graph/runtime/backend/sdma/sdma_completion_kernel.h

@@ -9,8 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 
-#ifndef SRC_A5_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_BACKEND_SDMA_SDMA_COMPLETION_KERNEL_H_
-#define SRC_A5_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_BACKEND_SDMA_SDMA_COMPLETION_KERNEL_H_
+#pragma once
 
 #include <stdint.h>
 
@@ -142,5 +141,3 @@ send_request_entry(AsyncCtx &ctx, SdmaRequestDescriptor<DstTensor, SrcTensor, Sc
     pto2::detail::defer_flush(ctx);
     return true;
 }
-
-#endif  // SRC_A5_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_BACKEND_SDMA_SDMA_COMPLETION_KERNEL_H_

src/a5/runtime/host_build_graph/runtime/backend/sdma/sdma_completion_scheduler.h

@@ -9,8 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 
-#ifndef SRC_A5_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_BACKEND_SDMA_SDMA_COMPLETION_SCHEDULER_H_
-#define SRC_A5_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_BACKEND_SDMA_SDMA_COMPLETION_SCHEDULER_H_
+#pragma once
 
 #include <cstddef>
 #include <cstdint>
@@ -57,5 +56,3 @@ inline void retire_sdma_event_record(uint64_t record_addr) {
     volatile uint64_t *channel_info = reinterpret_cast<volatile uint64_t *>(static_cast<uintptr_t>(channel_info_addr));
     __atomic_store_n(channel_info, packed, __ATOMIC_RELEASE);
 }
-
-#endif  // SRC_A5_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_BACKEND_SDMA_SDMA_COMPLETION_SCHEDULER_H_

src/a5/runtime/host_build_graph/runtime/dep_gen_host_graph.h

@@ -54,8 +54,7 @@
  * consumer (deps viewer, swimlane join) reads both runtimes' output the same way.
  */
 
-#ifndef SRC_A2A3_RUNTIME_HOST_BUILD_GRAPH_RUNTIME_DEP_GEN_HOST_GRAPH_H_
-#define SRC_A2A3_RUNTIME_HOST_BUILD_GRAPH_RUNTIME_DEP_GEN_HOST_GRAPH_H_
+#pragma once
 
 #include <cstdint>
 
@@ -139,5 +138,3 @@ void dep_gen_host_graph_destroy_capture(void *capture) noexcept;
  */
 int dep_gen_host_graph_emit(const char *deps_json_path);
 }
-
-#endif  // SRC_A2A3_RUNTIME_HOST_BUILD_GRAPH_RUNTIME_DEP_GEN_HOST_GRAPH_H_

src/a5/runtime/host_build_graph/runtime/host_tensor_access.h

@@ -47,8 +47,7 @@
  * strong definitions from `host/host_tensor_access.cpp`.
  */
 
-#ifndef SRC_A2A3_RUNTIME_HOST_BUILD_GRAPH_RUNTIME_HOST_TENSOR_ACCESS_H_
-#define SRC_A2A3_RUNTIME_HOST_BUILD_GRAPH_RUNTIME_HOST_TENSOR_ACCESS_H_
+#pragma once
 
 #include <stddef.h>
 #include <stdint.h>
@@ -87,5 +86,3 @@ void host_tensor_access_reset(int (*copy_to_device)(void *dev_ptr, const void *h
  * @return false for an empty region or a null `host_view`.
  */
 bool host_tensor_access_add(uint64_t dev_base, uint64_t size, void *host_view);
-
-#endif  // SRC_A2A3_RUNTIME_HOST_BUILD_GRAPH_RUNTIME_HOST_TENSOR_ACCESS_H_

src/a5/runtime/host_build_graph/runtime/pto_completion_token.h

@@ -9,8 +9,7 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_COMPLETION_TOKEN_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_COMPLETION_TOKEN_H_
+#pragma once
 
 #include <stdint.h>
 
@@ -41,5 +40,3 @@ struct CompletionPollResult {
     CompletionPollState state{CompletionPollState::PENDING};
     int32_t error_code{PTO2_ERROR_NONE};
 };
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_COMPLETION_TOKEN_H_

src/a5/runtime/host_build_graph/runtime/pto_constants.h

@@ -9,11 +9,8 @@
  * -----------------------------------------------------------------------------------------------------------
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_CONSTANTS_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_CONSTANTS_H_
+#pragma once
 
 #define PTO2_ALIGN_SIZE 64             // Cache line alignment
 #define PTO2_PACKED_OUTPUT_ALIGN 1024  // Each output in packed buffer aligned to 1024B; gap is padding
 #define PTO2_ALIGN_UP(x, align) (((x) + (align) - 1) & ~((align) - 1))
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_CONSTANTS_H_

src/a5/runtime/host_build_graph/runtime/pto_dep_compute.h

@@ -49,8 +49,7 @@
  * inlining and add ~5 ns/call to the orch hot path.
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_DEP_COMPUTE_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_DEP_COMPUTE_H_
+#pragma once
 
 #include <cstdint>
 
@@ -196,5 +195,3 @@ inline int32_t count_registrable_outputs(const DepInputs &inputs, bool in_manual
     }
     return needed;
 }
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_DEP_COMPUTE_H_

src/a5/runtime/host_build_graph/runtime/pto_runtime2_types.h

@@ -22,8 +22,7 @@
  * Based on: docs/RUNTIME_LOGIC.md
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_RUNTIME2_TYPES_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_RUNTIME2_TYPES_H_
+#pragma once
 
 #include <stdbool.h>
 #include <stddef.h>
@@ -548,5 +547,3 @@ static_assert(sizeof(PTO2TaskSlotState) == 64);
 // Sentinel marking a wake list as "owner already completed; no more
 // registrations accepted". Distinct from any real slot_state pointer.
 inline PTO2TaskSlotState *const WAKE_LIST_SENTINEL = reinterpret_cast<PTO2TaskSlotState *>(static_cast<uintptr_t>(0x1));
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_RUNTIME2_TYPES_H_

src/a5/runtime/host_build_graph/runtime/pto_types.h

@@ -22,8 +22,7 @@
  * without type conflicts (Handshake, TensorPair, HostApi).
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_TYPES_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_TYPES_H_
+#pragma once
 
 #include <stdint.h>
 #include <string.h>
@@ -663,5 +662,3 @@ struct L2TaskArgs : Arg<CHIP_MAX_TENSOR_ARGS, CHIP_MAX_SCALAR_ARGS> {
         }
     }
 };
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_PTO_TYPES_H_

src/a5/runtime/host_build_graph/runtime/runtime.h

@@ -26,8 +26,7 @@
  * signals AICore via DATA_MAIN_BASE.
  */
 
-#ifndef SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_RUNTIME_H_
-#define SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_RUNTIME_H_
+#pragma once
 
 #include <stdbool.h>
 #include <stdint.h>
@@ -315,5 +314,3 @@ class Runtime {
 // object); trb returns sizeof(DeviceRuntimeLaunchDesc). Defined per-runtime so
 // the shared device_runner_helpers.cpp copy path stays runtime-agnostic.
 size_t runtime_device_copy_size(const Runtime &rt);
-
-#endif  // SRC_A2A3_RUNTIME_TENSORMAP_AND_RINGBUFFER_RUNTIME_RUNTIME_H_