> 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/agents-identity-and-data/contract-evolution.md).

# Contract evolution

Use this runbook whenever a canonical event, AEGIS request, advisory proposal, paper-only request, development API request or isolated signer payload changes. Contract artifacts do not enable an API or execution mode; they make existing boundaries inspectable and drift-detectable.

## Verify the current contract

1. Run `pnpm contracts:check`. It builds `@terminal/contracts`, regenerates all eight documents in memory and requires exact committed output.
2. Run the contract package tests and Python parity test when diagnosing drift:

   ```powershell
   pnpm --filter @terminal/contracts test
   node scripts/python-tool.mjs pytest services/execution-py/tests/test_contract_artifacts.py
   ```
3. Inspect only the committed files under `packages/contracts/generated`. Do not hand-edit them.
4. Confirm the signer OpenAPI server remains `127.0.0.1`, bearer security contains no value, exchange decimals remain JSON strings, and all four public OpenAPI families remain anonymous, loopback-oriented and response-versioned. Agent entitlement and aggregate-usage definitions belong only in the master contract registry; the agent OpenAPI must remain unchanged with only proposal GET/POST, an opaque bearer scheme, operator-required approval and no execution operation. Account and RHC-data contract-violation telemetry must never include the requested address; RHC readiness telemetry must never include endpoint, path, wallet or rejected-payload detail.

## Add a compatible contract

1. Preserve every existing `*V1` Zod schema and operation request, parameter, security and response boundary.
2. Add a new, uniquely named definition to `CONTRACT_SCHEMA_REGISTRY`. If the payload semantics changed, use a new versioned name such as `ExampleV2`; do not silently mutate `ExampleV1`.
3. Add the new endpoint or change consumers through an explicit migration adapter while the old contract remains accepted for its documented window.
4. Run `pnpm contracts:generate`. The generator compares candidates with the Git `HEAD` committed v1 definitions and operations, then writes all artifacts atomically. This keeps a released contract immutable without treating an uncommitted draft generated during the same milestone as published.
5. Add positive, malformed, extra-field, precision and downgrade/compatibility tests. Capital-moving TypeScript/Python models also require cross-language parity coverage.
6. Run `pnpm contracts:check`, the full handoff gate and localhost smoke before committing the source and generated files together.

## Breaking-change refusal

`CONTRACT_V1_CHANGED` means a published definition or operation request/parameter/security/response boundary changed. `CONTRACT_V1_REMOVED` means it disappeared. Do not bypass these errors by deleting the committed artifact or weakening the checker after release.

For a necessary breaking change:

1. Keep the v1 schema and parser intact.
2. Introduce a v2 schema/operation with explicit routing or version discrimination.
3. Prove old and new payload isolation, replay/idempotency behavior and rollback.
4. Document the compatibility window and removal gate in a dedicated reviewed ticket.
5. Remove v1 only in an explicitly authorized major artifact release after all consumers have migrated.

## Decimal-boundary incident

If a signer request is rejected for decimal shape or exact notional mismatch, do not coerce, round or retry it. Preserve the reviewed ticket and trace IDs, compare the source quantity/price with the generated DTO, and perform a fresh venue/account/risk review. Exponent notation and JSON numbers are invalid by design. The SDK float conversion is a final library adapter requirement, never the inter-service contract or notional authority.


---

# 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/agents-identity-and-data/contract-evolution.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.