> 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/implementation-ledger/ns-420-paper-notional-limits.md).

# NS-420 · Immutable PAPER notional ceilings

## Product outcome

Require every new NIGHTSHIFT schema-v2 PAPER ledger to bind exact user-defined maximum open-entry notional for one venue/symbol market and for the complete cross-venue portfolio. Extend the retained schema-v1 risk checkpoint rather than creating a mutable preference. The control applies to standard entries only and introduces no venue, signing or execution authority.

## Exact policy

* Both limits are required positive exact-decimal USD strings; exponent notation and values above `1,000,000,000` are rejected.
* The retained hierarchy is `max market notional <= max portfolio notional <= starting capital`.
* Existing positions must fit both limits before a legacy ledger can receive the checkpoint.
* Market notional is absolute signed quantity multiplied by average entry price for one exact `venue + symbol` position.
* Portfolio notional is the sum of that same open-entry authority across every retained position.
* The limits are immutable until the user performs the existing full PAPER reset.

## Enforcement

1. A standard immediate simulation is applied to an in-memory candidate ledger, then both resulting actual notionals are checked before any browser write.
2. A standard local GTC placement reserves `remaining quantity * limit price` across its exact market and the full active order book. The existing realized-capital 1x reservation remains independently enforced.
3. Selected and away GTC reconciliation allocates reservations oldest-first. Ledger drift that invalidates a reservation terminally rejects that local row with an exact market- or portfolio-limit reason.
4. A fresh book can fill at a price different from the retained limit. If the candidate ledger would exceed a ceiling, the standard GTC remains open and the observation does not mutate either ledger or order row.
5. A later eligible reduce-only order from the same observation can still execute. Reduce-only and local mark protection remain exempt from the entry-only ceiling.
6. Missing, malformed or incoherent policy evidence fails closed for standard exposure.

## Boundaries

* Browser-local PAPER evidence only; no venue order, queue position, keeper, signer, wallet or background execution.
* Open-entry notional is not mark-to-market exposure, venue equity, margin, leverage, maintenance requirement, liquidation distance, fees, funding or withdrawable collateral.
* Resting reservations are conservative policy capacity, not a claim that a future fill is guaranteed.
* No mock price or fabricated balance is introduced. Every fill still requires the existing fresh exact live-book evidence.

## Acceptance evidence

* Strict checkpoint parsing rejects missing keys, expanded state, noncanonical limits and invalid hierarchy.
* Deterministic tests cover exact parsing, allowed boundaries, market breach, portfolio breach, GTC reservation, ledger drift, retained fills and reduce-only priority.
* Full web tests, repository typecheck, production build, handoff check and supervised localhost health pass.
* Desktop and mobile browser QA prove the six required risk inputs and retained limits remain readable without overflow or console errors.


---

# 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/implementation-ledger/ns-420-paper-notional-limits.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.