# HUAP: Toward a Trace-First Agentic Operating System
## A public core architecture for reproducible agent workflows

Mirco Mannucci

► To cite this version:

Mirco Mannucci. HUAP: Toward a Trace-First Agentic Operating System A public core architecture for reproducible agent workflows. 2026. hal-05447044

HAL Id: hal-05447044

https://hal.science/hal-05447044v1

Preprint submitted on 7 Jan 2026

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_1.png" /></figure>

Distributed under a Creative Commons CC BY 4.0 - Attribution - International License
# HUAP: Toward a Trace-First Agentic Operating System

## A public core architecture for reproducible agent workflows

Mirco A. Mannucci
HoloMathics LLC

January 2026

## Abstract

The current LLM agents ecosystem is rich in prompting patterns and tool-use wrappers, yet weak in operational guarantees: reproducibility, regression testing, auditable execution, and principled resource accounting. This paper proposes an *agentic operating system* viewpoint and presents **HUAP (HUman Agentic Platform)** as a *trace-first* public core architecture. HUAP treats agent workflows as executable graphs, tool calls as OS-like syscalls, and execution traces as the primary artifact for debugging, evaluation, and certification. We describe the kernel services needed for real-world agentic systems—pod contracts, deterministic replay, trace diffing, and budgeted evaluation—and show how these services turn “agent behavior” into a testable software system. We relate the design to durable execution and event sourcing, and position HUAP relative to contemporary agent frameworks and tool-use training paradigms.

**Keywords:** agentic systems, LLM agents, trace-first execution, deterministic replay, workflow engines, evaluation, observability, event sourcing.

## 1 Introduction

Large language models are increasingly deployed as *agents*: systems that plan, act, call tools, and iterate. Patterns such as ReAct interleave reasoning and actions to reduce hallucination and increase interpretability [1]. Tool-use training methods such as Toolformer attempt to internalize when and how to call external APIs [2]. Multi-agent conversation frameworks aim to scale capability through role decomposition and interaction [3].

Yet in production, the critical bottlenecks are often *operational* rather than purely cognitive:

* **Reproducibility:** Can we re-run an agent workflow and get the same observable outcomes?

* **Debuggability:** When behavior changes, can we pinpoint the divergence precisely?

* **Regression testing:** Can we gate changes (prompts, tools, models) with objective checks?

* **Auditability:** Can an execution be inspected and certified without trusting the runtime?

* **Resource accounting:** Can we enforce budgets (time, tokens, tool costs, risk) at runtime and in CI?

Conventional agent stacks typically treat the agent as a monolithic “program” whose state is implicit in model weights, transient context, and ad-hoc logs. This makes repeatability fragile and evaluation expensive. Software engineering, in contrast, developed reliable techniques for complex
systems by making execution observable: logs, traces, replay, and deterministic tests. Distributed
systems extended this to durable execution, where workflows persist state and resume reliably across
failures [4].

This paper argues that advanced agentic systems need an *operating system layer*: a kernel
responsible for scheduling, IO/tool isolation, state management, tracing, and policy enforcement.
We present HUAP as a concrete step in this direction. HUAP is intentionally split into a *public core*
(open-source, minimal dependencies) and a proprietary tier. The public core focuses on trace-first
execution, deterministic replay, diffing, and budgeted evaluation.

Contributions.

1. We define the *agentic OS* abstraction: what kernel services are required beyond “an agent loop”.

2. We present HUAP's trace-first design, emphasizing replay and diff as first-class operations.

3. We specify pod contracts and workflow graphs as the programming model for agentic applications.

4. We propose budgeted evaluation as the missing “resource accounting” primitive for agent behavior.

5. We relate HUAP to durable execution, event sourcing, and modern telemetry.

2 What is an Agentic Operating System?

An *operating system* is a software layer that mediates between programs and resources. Classically,
it provides process scheduling, memory management, device IO, isolation, and observability. An
*agentic OS* analogously mediates between *agent programs* and the resources they consume: LLM
inference, tools/APIs, files, databases, message queues, sensors, and human approvals.

## 2.1 Agent programs as workflows, not scripts

Most real agentic applications are not a single prompt. They are multi-step workflows with branches,
retries, tool calls, and external interactions. As soon as a system is:

* long-running (minutes to days),

* multi-step (planning → acting → verifying),

* multi-tool (web, database, code execution, messaging),

* safety-gated (approval steps, policy checks),

it becomes closer to a distributed workflow engine than to a script.

This suggests the programming model should be an explicit workflow graph with a kernel
runtime, rather than a hidden agent loop.

## 2.2 Kernel services for agents

We identify a minimal “kernel” surface for an agentic OS:

Scheduling and orchestration

Run workflow graphs; handle retries; coordinate steps and dependencies.
### Tool/syscall mediation

Provide a uniform interface for external tools and enforce policies (timeouts, allowlists).

### State references

Persist and version the minimal state needed to reproduce behavior; avoid opaque mutable blobs.

### Tracing

Emit a structured trace stream capturing decisions, inputs/outputs, and state hashes.

### Replay and diff

Deterministically replay traces and compute semantic differences.

### Budgeted evaluation

Measure token/tool costs and quality proxies; enforce budgets in CI and runtime.

HUAP's public core explicitly targets tracing, replay/diff, and evaluation, because these primitives unlock the rest.

## 3 HUAP Architecture Overview

HUAP organizes functionality into a small *kernel* plus modular *pods*. A pod bundles tools, prompts, models, and workflows that implement a capability (e.g., “SOMA” for posture sensing, “METIS” for research packaging). The public core focuses on the runtime substrate.

### 3.1 High-level component diagram

### 3.2 Pods and contracts

A pod is a package that declares:

* its **tools** (callable functions with metadata),

* its **graphs** (workflow YAMLs),

* its **policies** (allowlists, timeouts, budgets),

* optional **model adapters** (LLM clients or stubs).

Pods are discoverable by the HUAP CLI, validated for contract conformance, and executed by name.

A key design choice is that *tools are typed and categorized*, and are invoked through a standardized runtime interface. This makes it possible to enforce policies like “no network tools in offline mode” or “cap tool cost per run”.

## 4 Execution Model: Trace-First by Construction

Tracing is often treated as a secondary concern: logs are emitted after the fact and are not guaranteed complete. HUAP inverts this: the execution trace is the primary artifact and the runtime is designed to produce it.
<figure><img src="image_2.png" /><figcaption>Figure 1: HUAP modularity: a small kernel plus swappable pods. Each pod bundles tools, prompts/models, and workflows for a capability, while the kernel provides uniform trace-first operability across all pods.</figcaption></figure>

## 4.1 Trace events as the ground truth

A HUAP run emits a JSONL stream of structured events. A minimal event schema includes:

* `run_id`, `timestamp`

* `event_type` (`node_start`, `tool_call`, `tool_result`, `model_call`, `node_end`, `error`, ...)

* `node_id` and graph metadata

* `inputs` and `outputs` (redacted when needed)

* `state_hash` (content-addressed snapshot hash)

* `metrics` (tokens, latency, tool cost)

**Why JSONL?** A line-delimited format supports streaming, incremental processing, and partial recovery. It is easy to diff, compress, and post-process with standard tooling.

## 4.2 Deterministic replay

Reproducibility is hard when LLM inference and network tools are non-deterministic. HUAP provides a pragmatic approach:
<figure><img src="image_3.png" /><figcaption>Figure 2: HUAP public-core viewpoint: workflow execution emits a structured trace; evaluation consumes traces and budgets to gate changes.</figcaption></figure>

* In **live mode**, calls are executed normally and all observables are recorded into the trace.

* In **stub mode**, the runtime replays tool/model results from the trace (or from stubs) to reproduce the same execution path.

Replay is not only for debugging; it is essential for regression tests and certifications. A deterministic replay engine allows you to treat agent workflows like testable programs.

## 4.3 Trace diffing as regression detection

Given two traces, HUAP computes:

* structural divergence (different node order or branching),

* semantic divergence (tool outputs differ, state hashes differ),

* metric divergence (token/tool cost drift).

This is analogous to unit test failures, but with richer, step-local diagnostics. Instead of saying "the agent got worse," we can often say "node 7 changed because tool X returned Y".

# 5 Workflow Graphs as the Programming Model

HUAP workflows are explicit graphs expressed in YAML. Each node can be a prompt/model call, a tool call, or a composite subgraph.

A simplified example:
<caption>Listing 1: Simplified HUAP workflow snippet (illustrative).</caption>

```yaml
graph:
  id: hello
  nodes:
    -id: plan
      type: model_call
      prompt: "Draft a 3-step plan for greeting the user."
    -id: greet
      type: tool_call
      tool: "messages.send"
      args:
        text: "{{ plan.output steps[0] }}"
```

Graphs are preferable to “agent loops” because:

* they are inspectable and versionable,

* they are schedulable (parallel nodes, retries, gates),

* they map naturally to traces and evaluation.

# 6 Budgeted Evaluation: Resource Accounting for Agents

Modern software engineering has strong gating primitives: unit tests, coverage, static checks. Agentic systems need analogous gates, but their failures are often behavioral or cost-based.

HUAP introduces **budgeted evaluation**: a run is evaluated against budgets that specify acceptable ranges for:

* token usage and latency,

* tool call counts and costs,

* safety policy violations (e.g., disallowed tools),

* quality proxies (e.g., rubric scores, deterministic checks).

## 6.1 Budgets and grades

A budget file can define thresholds and grading bands:

* **Hard budgets**: must not exceed (CI fails).

* **Soft budgets**: warnings and grade reductions.

This makes it possible to enforce statements like:

> "This workflow must complete within 3 tool calls, 1200 tokens, and no network access in offline mode."
## 6.2 Why this matters

Without budgets, teams drift into two failure modes:

* **Unbounded cost:** adding “one more tool call” repeatedly until runs are expensive.

* **Unmeasured regressions:** behavior changes subtly with prompt/model updates.

Budgeted evaluation converts qualitative expectations into enforceable artifacts. It is not a substitute for deep evaluation, but it provides a robust baseline.

# 7 State Model and Determinism Boundaries

Trace-first systems must be explicit about *what is deterministic* and what is not. HUAP distinguishes:

* **Recorded observables:** tool/model inputs and outputs captured in the trace (possibly redacted).

* **Derived state:** state snapshots reconstructed from events; summarized by a content hash.

* **Non-deterministic sources:** network tools, stochastic sampling in LLM inference, and external clocks.

## 7.1 State references vs mutable blobs

A common failure mode in agent systems is storing a mutable “memory” blob that changes over time in opaque ways. HUAP pushes toward *state references*: small, typed objects whose provenance can be traced to events. This is compatible with many storage backends (files, databases) but keeps the *logical state* auditable.

## 7.2 Replay modes

HUAP supports multiple replay regimes:

**Exact replay**

Reuse recorded tool/model outputs to reproduce behavior exactly.

**Hybrid replay**

Replay tool outputs while re-running model calls (useful for prompt/model comparisons).

**Offline replay**

Disallow network tools entirely and require full stubbing from the trace.

These regimes enable different tests: exact regression, model upgrade evaluation, and air-gapped certification.

# 8 Policy, Permissions, and Redaction

An agentic OS must mediate capabilities. In HUAP, tool metadata enables *permissioned execution*:

* tools are categorized (e.g., network, filesystem, messaging, memory),

* runtime policies can allow/deny categories per environment,

* per-tool limits (timeouts, retries, rate limits) can be enforced uniformly.
## 8.1 Redaction as a first-class concern

Traces are only useful if they can be retained and shared. Therefore sensitive fields require redaction: API keys, PII, and high-risk payloads should not leak into trace artifacts. HUAP's public-core philosophy is to make redaction hooks explicit at the tracing boundary.

## 8.2 Separation of public core and pro tier

The public core provides the trace substrate and evaluation primitives. In many deployments, the pro tier adds:

* secret management and encrypted trace storage,

* authenticated multi-tenant routing,

* governance workflows (human approvals, audit trails),

* stronger isolation and sandboxing for tools.

This split keeps the public repo lightweight while allowing real deployments to enforce enterprise-grade controls.

# 9 Comparison to Existing Approaches

<table><caption>Table 1 compares HUAP's public-core emphasis with common categories of agent tooling.</caption><thead><tr><th>Capability</th><th>Prompt/Agent<br>libs</th><th>Workflow<br>gines</th><th>en-</th><th>HUAP<br>core</th><th>public</th></tr></thead><tbody><tr><td>Explicit workflows</td><td>Often implicit loops</td><td>Yes</td><td></td><td>Yes</td><td></td></tr><tr><td>Durable state</td><td>Ad hoc memory</td><td>Yes</td><td></td><td>Trace-derived</td><td></td></tr><tr><td>Deterministic replay</td><td>Rare</td><td>Sometimes</td><td></td><td>Yes (first-class)</td><td></td></tr><tr><td>Trace diffing</td><td>Rare</td><td>Limited</td><td></td><td>Yes (first-class)</td><td></td></tr><tr><td>Budget gates in CI</td><td>Rare</td><td>Sometimes</td><td></td><td>Yes (first-class)</td><td></td></tr><tr><td>Tool mediation policies</td><td>Partial</td><td>Partial</td><td></td><td>Yes (category-based)</td><td></td></tr></tbody></table>

<caption>Table 1: High-level positioning. HUAP targets operability primitives (trace/replay/diff/eval) rather than only cognition patterns.</caption>

# 10 Observability and Durable Execution Parallels

HUAP aligns closely with ideas from durable execution and event sourcing: the trace is an append-only event log, and the state is a derived projection. Durable execution platforms emphasize capturing workflow state at each step and resuming reliably after failure [4]. Similarly, telemetry standards emphasize structured traces and spans for observability [5].
## 10.1 Event sourcing lens

From an event sourcing perspective:

* the trace is the event store,

* the current workflow state is a materialized view,

* replay recomputes the view from the event stream,

* diff compares event streams and derived views.

This viewpoint helps clarify why trace quality is non-negotiable: if an event is missing, replay and auditability fail.

# 11 Positioning Relative to Agent Frameworks

Most agent frameworks focus on *how to make agents work* (prompts, memory, tools). HUAP focuses on *how to make agents operable*: reproducible, testable, auditable, and gateable in CI.

## 11.1 Complementary, not competing

HUAP can host or wrap many agent paradigms:

* A ReAct-style node can be expressed as a `model_call` step [1].

* Tool-use can be represented as `tool_call` nodes, whether learned (Toolformer) [2] or prompted.

* Multi-agent systems can be modeled as interacting pods and message queues [3].

The key is that HUAP insists these behaviors emit traces and can be replayed and evaluated.

# 12 A Practical Workflow: CI for Agent Behavior

A minimal CI pipeline for an agentic pod can:

1. run the workflow in stub mode to ensure determinism,

2. replay the resulting trace and verify state hashes,

3. evaluate trace metrics against budgets,

4. compare the trace against a baseline and fail on unacceptable diffs.

This style of CI makes agent development resemble normal software development. Instead of "prompting by vibes," teams can establish behavioral baselines and detect drift.

# 13 Worked Example: Trace, Replay, and Diff in Practice

This section provides a concrete end-to-end example using a small pod and workflow graph. The goal is not to showcase sophisticated reasoning, but to demonstrate the *operational loop*: run → trace → replay → evaluate → diff.
## 13.1 Workflow

Consider a minimal "hello" workflow consisting of: (1) a planning model call producing a short plan, and (2) a messaging tool call that sends the greeting. A typical invocation is:

```
HUAP_LLM_MODE=stub huap trace run hello examples/graphs/hello workflow.yaml --out traces/
hello.jsonl
```

**A slightly richer graph.** To illustrate branching and retries, Listing 2 sketches a graph with an explicit validation step. If validation fails, the workflow retries once with a revised prompt.

<caption>Listing 2: Illustrative workflow with validation and one retry.</caption>

```yaml
graph:
  id: hello workflow_v2
  nodes:
    -id: plan
      type: model_call
      prompt: "Draft a 3-step plan for greeting the user."
    -id: draft_greeting
      type: model_call
      prompt: "Use the plan to draft a 1-sentence greeting."
    -id: validate
      type: tool_call
      tool: "checks Younger"
      args:
        text: "{{ draft_greeting. output. text }}"
        pattern: "^[A-Z].*[.!]$$"
    -id: revise
      type: model_call
      when: "{{ validate. output. ok == false }}"
      retries: 1
      prompt: "Rewrite the greeting as a single sentence starting with a capital letter and ending with punctuation."
    -id: greet
      type: tool_call
      tool: "messages. send"
      args:
        text: "{{ (revise. output. text if revise. ran else draft_greeting. output. text) }}"
```

Even for trivial tasks, this pattern makes two points: (i) explicit guards are easier to trace and test than implicit agent loops, and (ii) retries become visible and measurable (they show up as additional events and token/tool costs).

## 13.2 Trace excerpt

A trace is a JSONL stream. Listing 3 shows an illustrative excerpt (whitespace added for readability). In practice, payloads may be redacted, and large fields (e.g., tool outputs) are stored with summaries and hashes.
**Evaluator output.** A typical evaluator summary (illustrative) is shown below:

<caption>Listing 5: Illustrative evaluator summary.</caption>

```json
PASS grade=B
    tokens_in=120 tokens_out=148 total_tokens=268 (budget<=1200)
    tool_calls=1 (budget<=6)
    latency_ms=601 (soft<=15000)
    policy: no disallowed tool categories
```

## 13.5 Trace diff and behavioral drift

Suppose we modify the greeting text or change a prompt template. Even if the workflow “still works,” we want to detect the drift precisely.

```
huap trace diff traces/hello_baseline.json1 traces/hello_candidates.json1
```

Listing 6 shows an illustrative diff report.

<caption>Listing 6: Illustrative trace diff (semantic + metric drift).</caption>

```json
DIVERGENCE at node=greet event=tool_call
    baseline.args.text: "Hello, Mirco!"
    candidate.args.text: "Hi there!"
    state_hash baseline: 9aa4... candidate: 2c10...

METRICS DRIFT (run-level)
    tokens_out: +120
    tool_calls: +1
```

**Metric comparison table.** Diff reports are more useful when they summarize run-level costs alongside semantic deltas. Table 2 shows an illustrative comparison.

<table><caption>Table 2: Illustrative run-level metric drift derived from traces.</caption><thead><tr><th>Metric</th><th>Baseline</th><th>Candidate</th><th>Δ</th></tr></thead><tbody><tr><td>Total tokens</td><td>268</td><td>388</td><td>+120</td></tr><tr><td>Tool calls</td><td>1</td><td>2</td><td>+1</td></tr><tr><td>Latency (ms)</td><td>601</td><td>1150</td><td>+549</td></tr></tbody></table>

**Golden baselines.** A practical workflow is to keep a small set of *golden* traces under version control (e.g., `examples/traces/`) and to treat them as regression fixtures:

* baseline traces define the expected structure and key observables,

* candidate traces are produced in CI for each change,

* trace diff gates the PR if unacceptable divergence is detected.

To avoid accidental commits of large or sensitive traces, production traces are ignored by default (`traces/`, `runs/`, `.huap/`), while `examples/traces/` can be explicitly whitelisted.
**CI sketch.** The following minimal CI script (illustrative) turns agent behavior into an enforceable contract:

<caption>Listing 7: Illustrative CI gating script for a pod.</caption>

```bash
set -euo pipefail
export HUAP_LLM_MODE=stub

# 1) Run and record candidate trace
huap trace run hello examples/graphs/hello workflow.yaml --out traces/candidate.json1

# 2) Replay deterministically (hash verification)
huap trace replay traces/candidate.json1 --verify

# 3) Evaluate against budgets
huap eval trace traces/candidate.json1 -b examples/budgets/dev.yaml

# 4) Diff against golden baseline
huap trace diff examples/traces/hello baseline.json1 traces/candidate.json1
```

Because each step consumes or produces a trace artifact, failures are localized and explainable. This is the operational advantage of a trace-first agentic OS.

## 14 Roadmap: From Public Core to an Agentic OS

The public core targets trace/replay/eval primitives. A full agentic OS roadmap naturally includes:

* distributed execution (control plane + worker data plane),

* stronger isolation for tools and secrets,

* proof-carrying traces and certification artifacts,

* policy languages for guardrails and resource types,

* multi-tenant scheduling and billing.

These extensions become practical *because* trace-first execution provides a stable substrate.

## 15 Threat Model and Trust Boundaries

Operational guarantees require clarity about what is assumed trustworthy. This section sketches the main threat surfaces for a trace-first agentic OS and the mitigations that naturally follow.

### 15.1 Assets

We treat the following as assets to protect:

* **Confidentiality of secrets and PII** that may appear in tool inputs/outputs or prompts.

* **Integrity of traces** used for replay, evaluation, and certification.

* **Policy compliance** (e.g., disallowed tools, offline execution constraints).

* **Cost guarantees** (budgets and limits that prevent runaway tool calls or token burn).
## 15.2 Adversary model

We consider realistic adversaries in agent deployments:

* **Accidental leakage:** developers unintentionally log secrets into traces.

* **Malicious tool outputs:** external tools return poisoned payloads that influence downstream steps.

* **Trace tampering:** traces are edited post-hoc to conceal actions or fabricate compliance.

* **Policy bypass:** a workflow attempts to call disallowed tools, or routes through an "equivalent" tool.

## 15.3 Trust boundaries

A trace-first system draws explicit boundaries:

**Runtime boundary**

The kernel is trusted to enforce policy and emit traces. In the pro tier, kernel binaries should be signed and attested.

**Tool boundary**

Tools are untrusted: their outputs must be treated as tainted data unless verified.

**Storage boundary**

Trace storage may be untrusted unless integrity protections are applied (hash-chaining, signatures, WORM storage).

## 15.4 Mitigations enabled by trace-first design

**Redaction and minimization.** Redaction hooks should operate *at the trace boundary*, not as an afterthought. The default should be to store hashes/summaries and only retain full payloads when necessary.

**Integrity: hash chaining and signatures.** For certifications, traces should be tamper-evident. A simple approach is *hash chaining*: each event includes a hash of the previous event, forming an append-only chain. Stronger guarantees add digital signatures over chain heads (or periodic checkpoints), enabling offline verification.

**Replay as anomaly detection.** Deterministic replay can detect unexpected nondeterminism and hidden dependencies. If replay diverges, it signals that either (a) external non-deterministic sources were not fully captured, or (b) the runtime/pod changed in ways that affect derived state.

## 15.5 What replay guarantees (and does not guarantee)

Replay is an *observational* guarantee: it reproduces captured observables. It does not prove that the original run was safe or correct; it proves that the runtime can reproduce the same observable behavior under the same recorded tool/model results.
# 16 Conclusion

Agentic systems are moving from demos to products. The limiting factor is increasingly operational: reproducibility, auditability, and cost control. We presented HUAP as a trace-first public-core architecture that treats agent workflows as executable graphs and traces as the ground truth artifact, and illustrated the operational loop with a worked trace/replay/eval/diff example. Deterministic replay, diffing, and budgeted evaluation are not peripheral features; they are kernel primitives that convert “agent behavior” into a testable engineering object.

## References

[1] S. Yao, J. Zhao, D. Yu, N. Du, I. Shafran, K. Narasimhan, and Y. Cao. *ReAct: Synergizing Reasoning and Acting in Language Models*. arXiv:2210.03629, 2022. https://arxiv.org/abs/2210.03629.

[2] T. Schick, J. Dwivedi-Yu, R. Dessì, R. Raileanu, M. Lomeli, L. Zettlemoyer, N. Cancedda, and T. Scialom. *Toolformer: Language Models Can Teach Themselves to Use Tools*. arXiv:2302.04761, 2023. https://arxiv.org/abs/2302.04761.

[3] Q. Wu et al. *AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation*. arXiv:2308.08155, 2023. https://arxiv.org/abs/2308.08155.

[4] Temporal Technologies. *Temporal: Durable Execution Solutions*. https://temporal.io/. Accessed 2026-01-03.

[5] OpenTelemetry. *OpenTelemetry: Observability Framework*. https://opentelemetry.io/. Accessed 2026-01-03.

# A Appendix

The codebase for HUAP CORE public version can be found here: https://github.com/Mircus/HUAP/tree/main. The repository is released under the MIT Licence.

## A.1 Appendix: Minimal trace event schema

<table><thead><tr><td>Field</td><td>Meaning</td></tr></thead><tbody><tr><td>run_id</td><td>Unique identifier for a workflow run.</td></tr><tr><td>event_type</td><td>Event kind: node_start, tool_call, tool_result, model_call, node_end, error.</td></tr><tr><td>graph_id, node_id</td><td>Workflow identity and current node.</td></tr><tr><td>inputs, outputs</td><td>Structured payloads; may be redacted.</td></tr><tr><td>state_hash</td><td>Content hash of the derived state snapshot after applying the event.</td></tr><tr><td>metrics</td><td>Tokens, latency, tool costs, retry counts, etc.</td></tr></tbody></table>
## A.2 Appendix: Budget file sketch (illustrative)

```yaml
budgets:
  hard:
    max_tokens: 1200
    max_tool_calls: 6
    disallowed_toolCategories: ["network"]
  soft:
    max_latency_ms: 15000
grades:
  A: {max_tokens: 900, max_tool_calls: 4}
  B: {max_tokens: 1100, max_tool_calls: 5}
  C: {max_tokens: 1200, max_tool_calls: 6}
```

## A.3 Appendix: Trace diff sketch

```ini
DIVERGENCE at node=greet
baseline.tool_result.text: "Hello, Mirco!"
candidate.tool_result.text: "Hi there!"
state_hash baseline: 7b9c... candidate: a12f...
metrics delta: +120 tokens, +1 tool_call
```

## A.4 Appendix: Canonical CLI surface (public core)

The public core CLI is organized around trace artifacts:

```bash
# Execute a workflow graph and produce a trace
huap trace run <pod> <graph.yaml> --out trace.json1

# Deterministically replay a trace
huap trace replay trace.json1 --verify

# Compare traces (baseline vs candidate)
huap trace diff baseline.json1 candidate.json1

# Evaluate a trace against a budget
huap eval trace trace.json1 -b budgets/dev.yaml
```