> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/talus-docs-v2.1.0/concepts/14-protocol-upgrades-and-compatibility.md).
# Protocol Upgrades and Compatibility
{% hint style="info" %}
**Audience:** Nexus and TAP package developers.
**Goal:** Decide whether a release needs only local updates, a dependency migration, or new application identities.
{% endhint %}
Compatibility is the relationship between a published Nexus package, an application package, its registered Tool and DAG identities, and the objects and live work that use them. A release can change a local component without requiring an on-chain package change, or it can change a dependency or signature that requires a deliberate migration.
### Package lineage and authority
An application package must retain the package authority needed for its own upgrade and must verify dependency IDs, package lineage, type origins, and changed public signatures before cutover. A compatible pointer can retain a Tool or DAG identity only when its contract and application invariants remain compatible. A breaking FQN, module, schema, witness, output variant, port, or invocation contract requires a new identity or revision.
#### Runtime authority and object witnesses
The runtime composition is public at the authority boundary. A stable `RuntimeAuthority` root binds the Scheduler package lineage through its `UpgradeCap`; an owned `RuntimeAuthorityCap` controls permanent pause and work-admission marker changes. The runtime proves its identity with the package witness and produces an ephemeral `RuntimePermit` for execution and settlement effects. A selected network must still expose the matching objects, package lineage, and effects.
Stable Nexus objects can retain one identity and readable typed inner state across a package upgrade, while mutation and destruction require the accepted witness from the package. A cached package ID, event emitter, historical Protocol field, or deployment document is not a substitute for that witness. `deployment..json` records describe package lineage, linkage, shared roots, capabilities, and transaction evidence and explicitly omit `protocol`, `protocol_version`, and `config_hash`; historical release manifests may retain those fields for compatibility validation, but they are not live effect authority. Treat `RuntimeAuthority`, `RuntimeAuthorityCap`, `RuntimePermit`, witness, pause state, and admission markers as unavailable only when the selected network and client cannot prove their exact objects, bindings, tests, and transaction effects; do not invent a command absent from the selected CLI.
The custody matrix is explicit for the authority surface:
| Surface | Authority and action | Recovery or evidence boundary |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bound Scheduler `UpgradeCap` | `bind_runtime` stores this lineage under `RuntimeAuthority`; the same bound cap can rotate to a witness introduced by a later Scheduler package. | It does not pause or change admission markers. Record the cap lineage, target package IDs, regenerated artifacts, tests, and transaction effects before rotation. |
| `RuntimeAuthorityCap` | Required to bind the first runtime, permanently pause the authority, and add or remove work-admission markers. | Pause has no resume entry point; recovery is a later `rotate_runtime` through the bound Scheduler `UpgradeCap`, not a resume toggle. |
| `RuntimePermit` | `authorize` returns transaction-scoped effect authority after the authority is bound, unpaused, and matched to the exact runtime type. | It is ephemeral execution evidence, not a stored custody capability. |
| Runtime witness and package target | The witness type selects the target package/type accepted by the bound cap. | A witness does not prove exact bytecode provenance; require package IDs, UpgradeCap lineage, source/generated artifacts, tests, and transaction effects. |
#### Runtime and execution compatibility
Tasks and executions pin the contracts they use. A dependency or package upgrade does not rewrite old work: drain or settle nonportable work, preserve the old deployment as evidence, and direct new Tasks to the compatible or replacement revision. Verify business state, reserves, committed results, and payment settlement across the boundary.
Tool and Agent application compatibility is separate from protocol package lineage. The LTS SDK classifies an observed Tool as `Current`, `LegacyUnderstood`, `MigrationRequired`, `Unsupported`, or `Unavailable`; only `Current` is a positive compatibility result. The on-chain Tool package-pointer action accepts a compatible LTS Tool under owner authority and clears its verified flag. It does not convert an RC.4/V1 Tool record, off-chain endpoint, DAG, Agent, skill, Task, payment, or business object.
A skill update affects future admission only. Existing Tasks retain their pinned DAG, skill revision, fixed Tools, policy, payment, and schedule contract. Already-admitted Executions can drain only while that pinned contract remains supported; pending and unadmitted occurrences are rechecked and can become inactive, stale, missing, or rejected.
#### Release-family application boundary
| Starting point | Mandatory interface work | Default object strategy |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| V2 RC.4 | Signed HTTP v1 → v3, ToolGas → ToolCashier, old on-chain `execute` prefix → LTS `UIDRequirements`/interface result, TAP scheduling → Task/Schedule/Occurrence | Preserve application-owned state only through a compatible package upgrade or explicit bridge; inspect each Tool, publish replacement DAG/skill identities when contracts changed, and recreate future Tasks. |
| V1 | Generated bindings and typed state resolution, all RC.4 interface work, `DefaultTAP`/`DefaultTAPV1Witness` plus Leader `AgentInterface`/`DagExecutionConfig` → Agent/Skill, V1 scheduling → the LTS Task model, typed payment, and split result/settlement paths | Treat the cutover as cross-family reconstruction unless a specific target function/test proves an object-level migration. |
#### Decision guide
* **No breaking Nexus contract/API change:** no on-chain application package change is required solely for the release. Update the target SDK, CLI, Toolkit, or other local component only when the application uses it or needs the release.
* **Move dependency-only change:** update package dependencies and deployment bindings, rebuild, test, dry-run, and upgrade the application package while retaining source signatures that remain compatible.
* **Breaking signature/type/schema change:** update imports and Move signatures, check Tool ABI, input/output schema, witness, DAG ports, skill revisions, payment/task interactions, and state invariants, then choose a compatible pointer migration or a new Tool identity and DAG/skill revision.
Use the [on-chain Tool upgrade guide](/talus-docs-v2.1.0/guides/tool-development/build-onchain-tool-vertex-and-upgrade.md) or the [TAP package upgrade guide](/talus-docs-v2.1.0/guides/tap-development/upgrade-tap-package.md) for package-level verification and cutover.
**Next**
Use the [Protocol Upgrades guide](/talus-docs-v2.1.0/guides/protocol-upgrades.md) to choose the package upgrade workflow and preserve compatibility evidence.
---
# 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 following URL with the `ask` and `goal` query parameters:
```
GET https://docs.talus.network/talus-docs-v2.1.0/concepts/14-protocol-upgrades-and-compatibility.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.
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.
