template - Haia Trace

haia-trace template list [options]
haia-trace template new <name> [options]

A template is the declarative shape of one operation — the milestones that have to be witnessed for it to count as complete. build and sample assemble receipts against one. Four ship with the CLI:

Template	The operation it describes	What captures it
`x402-buyer`	an x402 payment as the paying client saw it — `challenge → payment → settlement`	`@usehaia/trace-x402` on a client
`x402-seller`	the same payment as the resource server saw it — `request → verification → settlement`	`@usehaia/trace-x402` on a resource server
`x402-facilitator`	the same payment as the verify/settle service saw it — `verification → settlement`	`@usehaia/trace-x402` on a facilitator
`escrow-arc`	an escrow on Arc — `agreement → deposit → delivery → criteria → review → disposition`	`@usehaia/trace-circle` for the `circle.` money stages, your own service for the `escrow.` obligation stages

Anything else needs one you write.

Options

Option	Applies to	Meaning
`<name>`	`new`	Name for the new template. Letters, digits, `-` and `_`.
`--dir <path>`	`list`, `new`	Root holding `events/`, `receipts/` and `templates/`. Default: `.trace`.
`--templates-dir <path>`	`list`, `new`	Where your own templates live. Overrides `--dir`. Default: `<dir>/templates/`.
`--force`	`new`	Overwrite the file if it already exists.

`template list`

Everything build --template will accept — the shipped templates and your project’s own — each labelled with the file build would actually load.

haia-trace template list

📋 Operation templates

  ✔ escrow-arc        built-in
  ✔ my-op             .trace/templates/my-op.yaml
  ✔ x402-buyer        built-in
  ✔ x402-facilitator  built-in
  ✔ x402-seller       built-in

5 templates available.

A local template is shown by path rather than by a label, because the path is also the answer to “which one is being used?” when it shadows a shipped template of the same name.

`template new`

Scaffold a template into .trace/templates/ — the directory build searches first, so the two halves of the loop meet with no flags to configure.

haia-trace template new my-op

✔ Created .trace/templates/my-op.yaml

  Edit the stages to match your events, then:
  haia-trace build --template my-op

The file it writes is commented and already valid, but deliberately inert: its placeholder event types match nothing, so building against an unedited scaffold returns PARTIAL rather than a clean verdict on an operation nobody has described yet.

# my-op — the operation this template gives a verdict on.
#
# A template is the declarative shape of one operation: the milestones that have
# to be witnessed for it to count as complete. `build` folds each operation's
# events through this file and returns FULL when every required stage closed,
# PARTIAL otherwise — with an explanation for each one that did not.
#
# Replace the placeholder event types below with the ones your recorder emits.
template: my-op
version: 1
stages:
  # A stage closes the first time any event in its `match` list is observed. The
  # list is an OR, not a sequence: one entry per witness that proves the same
  # milestone, so a single template can cover several ways of doing the work.
  - id: request
    required: true
    match:
      - event: your.namespace.requested
    # Shown on the receipt when a required stage never closed. Say what the gap
    # means for the operation, not that an event was missing.
    missing_explanation: "the operation was never requested"

  # `required: false` marks a progress marker rather than a milestone: it is
  # reported when observed, but its absence never makes a receipt partial.
  - id: authorization
    required: false
    match:
      - event: your.namespace.authorized

  - id: settlement
    required: true
    match:
      - event: your.namespace.settled
    missing_explanation: "the operation was requested, but never settled"

# Faults observed during the operation. An exception is surfaced on the receipt
# even when every stage closed, so an operation that looks complete cannot hide
# one that went wrong along the way.
exceptions:
  - your.namespace.failed
  - your.namespace.canceled

A witness may also name the payload fields the event has to carry:

stages:
  - id: decision
    required: true
    match:
      - event: policy.decision.made
        where: { verdict: approved }   # only this outcome closes the stage
exceptions:
  - event: policy.decision.made        # the same type, faulted on the
    where: { verdict: rejected }       # outcome the stage does not accept

where is a mapping of top-level payload fields to scalars, all of which have to hold. Comparison is strict equality: 1 does not match "1", true does not match 1, and a field the event does not carry never matches. That is the whole grammar — no dotted paths, no comparison operators, no patterns, and an empty where is rejected rather than quietly matching everything. Reach for it where one event type carries the outcome in its payload. Without a condition the stage above closes on a rejected decision as readily as an approved one; listing the type in exceptions instead faults every decision the operation ever took. An exceptions entry is either a bare event type — how the shipped templates write them — or the same { event, where } mapping, for a type that is a fault only under some outcomes. One key is special: role reads the role that observed the event — the one the adapter stamped on it — rather than a payload field of that name.

match:
  - event: x402.verify.ok
    where: { role: server }

Without it, any role closes the stage. Reach for it wherever two roles record the same event type for the same operation, as a resource server and a facilitator do: the shipped x402-seller and x402-facilitator templates constrain every witness for exactly that reason. new refuses to overwrite an existing file unless you pass --force, so an edited template is never lost to a repeated command:

error: template already exists: .trace/templates/my-op.yaml — pass --force to overwrite

Writing over a shipped name is allowed — it is how you adapt a template to a flow that differs from the standard one — but it is said out loud:

✔ Created .trace/templates/x402-buyer.yaml

⚠ This shadows the built-in x402-buyer template.

The build line new prints carries whichever of --dir and --templates-dir you used, so the follow-up command resolves the file that was just written rather than reading a default root.

Templates are data, not code: a new scenario is a new file plus, if the events are new, a capture adapter — never a change to the assembler. See Operation Receipt for how stages and match-sets shape a verdict.

.trace/templates/ is source you author, unlike .trace/events/ and .trace/receipts/, which are recorded and derived. Ignore those two subdirectories in git rather than .trace/ as a whole, or your templates will not be committed.

​Options

​template list

​template new

Options

`template list`

`template new`