🔄Protocol Upgrades and Compatibility
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.<network>.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:
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
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 or the TAP package upgrade guide for package-level verification and cutover.
Next
Use the Protocol Upgrades guide to choose the package upgrade workflow and preserve compatibility evidence.
Last updated

