> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/policy-control-and-incident-response/execution-flow-tracing.md).

# Execution-flow tracing

Use this runbook to follow one protected order from review through submit, cancellation and reconciliation. Trace evidence is diagnostic only. Never retry an ambiguous action because two rows share a flow ID.

## Normal correlation

1. Keep execution disabled unless the separate activation checklist is deliberately in progress.
2. Unlock the local operator session and open the terminal account audit or Settings.
3. Record both identifiers: `FLOW` is the stable execution root and `SPAN` is one protected HTTP action.
4. A review normally shows the same value for flow and span. Submit, cancel and reconciliation must have fresh spans while retaining the original flow.
5. Match the flow against the strict Arcus or Hyperliquid signer-audit row for the exact client ID/CLOID.
6. Establish finality only from the venue lifecycle and reconciliation result. An HTTP ACK or trace match is never final.

Protected responses return `x-nightshift-trace-id` and `x-nightshift-root-trace-id`. Do not copy either header into a new request as authority: the BFF ignores caller lineage. Signed confirmation tickets and the authenticated loopback signer audit are the only accepted roots.

## Missing or split lineage

1. Treat `LEGACY` as historical evidence without a validated UUID; do not invent a replacement.
2. If flow equals span on a later reconciliation, the signer had no retained valid root for that exact identifier. Continue reconciliation using the CLOID/client ID.
3. If the BFF and signer show different spans but the same flow, that is expected across service boundaries.
4. If the signer root lookup is unavailable, keep reconciliation available and inspect signer health, execution-store integrity and the exact account scope.
5. For an ambiguous submit/cancel, do not retry. Follow the venue-specific reconciliation or emergency-stop runbook.

## Store migration and recovery

The stable `control-plane-observability-v1.json` filename contains schema v3. Reads migrate strict schema-v1/v2 events in memory by assigning `rootTraceId = traceId`; the next atomic write persists v3. Existing SLO alerts, incidents and delivery rows are preserved.

1. Stop the supervisor before inspecting or restoring a checkpoint.
2. Preserve malformed, future-schema, symlinked or oversized files for investigation.
3. Verify a checkpoint with `pnpm backup:verify -- <backup-id>` before restore.
4. Restart and run `pnpm local:health`, then issue a harmless locked protected request.
5. Confirm the authenticated control-plane panel shows a valid flow/span pair and no sensitive fields.

The signer database remains a separate sensitive backup domain. Use the signer-store recovery runbook; never copy its detail JSON into the public telemetry store.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/policy-control-and-incident-response/execution-flow-tracing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.