> 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/engineering-guide/07-execution-and-reconciliation.md).

# Execution and reconciliation

[← Bring Your Own Agent](/nytshift-docs/engineering-guide/06-bring-your-own-agent.md) · [Documentation home](/nytshift-docs/start-here/readme.md) · Next: [Identity, portfolio and funding →](/nytshift-docs/engineering-guide/08-identity-portfolio-and-funding.md)

Execution is a separately deployed, disabled-by-default boundary. Public data, account inspection, paper trading, proposals and AEGIS policy can all exist without a signer. That asymmetry is intentional.

## The rule

> A model may propose. AEGIS may allow. Only a separately authorized controller and isolated signer may attempt a venue action.

No component treats “AEGIS allowed” as a signature. An allow verdict is one input to a short-lived reviewed action.

![Locked NYTSHIFT Approval mode showing a reviewed Hyperliquid order with optional take profit, required risk stop and a separate human gate](https://365345826-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FD02RJbcs8ypn0hikgNUk%2Fuploads%2Fgit-blob-e4ad6fceee664b0a26aec522963d9d6ccbf9fb5b%2F03-approval-mode.png?alt=media)

## Review-to-finality pipeline

1. Authenticate the operator or sender-constrained testnet policy.
2. Parse strict bounded JSON and exact decimal strings.
3. Reconcile the exact configured venue account.
4. Read fresh market metadata, executable book, fee state and capacity.
5. Evaluate AEGIS against server-owned evidence.
6. Persist the normalized review verdict before returning an approval token.
7. Display exact symbol, side, amount, TIF, price bounds, fees, network and risk limits.
8. Receive explicit confirmation or one durable DPoP policy request.
9. Atomically consume the one-use scope before signer I/O.
10. Re-run time-sensitive checks.
11. Send one authenticated loopback request to the isolated signer.
12. Persist the signer claim before network I/O.
13. Make at most one venue attempt.
14. Reconcile by exact venue identity until terminal state or explicit bounded uncertainty.

## Hyperliquid boundary

Hyperliquid signing uses a dedicated API wallet file outside the repository. The offline doctor derives the address without network access and rejects a key that resolves to the master or selected subaccount.

Review requires, among other gates:

* exact master/subaccount and owner scope;
* full primary + deployer-DEX metadata without schema drift;
* fresh converged portfolio generation;
* exact active leverage, max size and available-to-trade capacity;
* explicit operator slippage and total-fee ceilings;
* disclosed native builder fee scope/approval;
* signed execution eligibility;
* kill switch and venue dead-man state;
* testnet/mainnet mode agreement in BFF and signer.

Opening orders may use a `normalTpsl` parent with distinct-CLOID reduce-only take-profit and stop-loss legs. Each leg is retained before submission. Group reconciliation never infers child finality from the parent ACK.

### Venue dead-man switch

Mainnet-capable Hyperliquid entry requires a 30-second `scheduleCancel` lease. The terminal refreshes it only while authenticated operator presence remains live. Every refresh records the complete bounded all-DEX open-order CLOID set before the one venue call. Ambiguity stops heartbeats and becomes post-deadline reconcile-only. Disarm requires a fresh proof of zero open orders.

## Arcus boundary

Arcus uses a separate Ed25519 key, account scope, confirmation secret and supervisor. The connected no-send preflight verifies live rules, a fresh two-sided book, compliance, margin, positions and exact engine integers. It remains non-promotable.

The protected path:

* is disabled by default;
* repeats the live preflight;
* persists review and one cancel-on-reconciliation-failure scope;
* signs through loopback-only Python;
* treats HTTP 202 as pending, never final;
* latches ordinary entry after an unknown lifecycle;
* preserves emergency cancel-all independently from ordinary execution;
* derives mainnet rehearsal evidence from durable testnet outcomes rather than booleans.

## Exact arithmetic

Capital-moving price, size and notional values cross TypeScript/Python boundaries as bounded non-exponent decimal strings. AEGIS and the signer use exact integer/decimal arithmetic. Conversion to a venue SDK number occurs only at the final adapter where required.

## Idempotency domains

| Action           | Identity                                            | Replay behavior                                                       |
| ---------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
| Order intent     | `intent_id` + venue CLOID/client ID                 | Duplicate rejected or returns retained result; never a second attempt |
| Bracket group    | Parent/TP/SL distinct CLOIDs + group scope          | Reconcile each leg; no inferred sibling state                         |
| Leverage update  | Separate exact-once action claim                    | Never shares order-submission identity                                |
| Dead-man action  | Account/network-bound schedule claim                | Ambiguity becomes reconcile-only                                      |
| Agent automation | DPoP key + request ID + policy                      | Exact replay not double-charged or reattempted                        |
| Arcus withdrawal | One-use wallet-bound request + provider transfer ID | HTTP 202 remains pending until exact-ID evidence                      |

## Unknown outcomes

```mermaid
flowchart TD
    A[Signed attempt begins] --> R{Result class}
    R -->|proved pre-sign failure| N[Not attempted]
    R -->|venue rejection| J[Final rejected]
    R -->|authoritative fill/cancel| F[Final]
    R -->|timeout/ambiguous response| U[Unknown]
    U --> Q[Query exact CLOID/client ID]
    Q -->|matching order/fill| F
    Q -->|proved absent within authoritative scope| J
    Q -->|coverage exhausted/conflict| B[Attention required; new entry blocked]
```

There is no `Unknown → retry` edge. Recovery uses retained identity, venue reads, fill windows and signer audit.

## Durable signer store

SQLite WAL owns intent, idempotency, order/bracket scope, reconciliation, all-fill evidence, fee ledger, leverage claims, dead-man state, Arcus alerts and rehearsal evidence. Migrations are ordered and exclusive; health requires exact schema plus integrity checks. Cold backups are separate from public application backups and require stopped supervisors.

Runbooks: [Hyperliquid lifecycle](/nytshift-docs/hyperliquid/hyperliquid-order-lifecycle.md), [brackets](/nytshift-docs/hyperliquid/hyperliquid-bracket-orders.md), [dead-man switch](/nytshift-docs/hyperliquid/hyperliquid-dead-man-switch.md), [Arcus reconciliation](/nytshift-docs/arcus/arcus-reconciliation-incident.md), [unknown order](/nytshift-docs/policy-control-and-incident-response/unknown-order.md) and [kill switch](/nytshift-docs/policy-control-and-incident-response/kill-switch.md).


---

# 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/engineering-guide/07-execution-and-reconciliation.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.