Scope: a concrete, file-by-file walkthrough of migrating a
RemoteAdapteracross an SDK contract MAJOR bump (vN → vN+1), using the reference text-file adapter as the worked example. Read Adapter SDK §6–8 first for the versioning/deprecation policy this guide applies.Mechanisms referenced are real:
ADAPTER_SDK_CONTRACT_VERSIONandverifyAdapterPackage(libs/bellona/remote-adapters/src/contract.ts,packaging.ts), and the announce→sunsetRemoteDeprecationRegistry(libs/bellona/remote-protocol/src/protocol-evolution.ts,180.C.29.15).
The compatibility contract you are migrating against#
ADAPTER_SDK_CONTRACT_VERSION is currently '1.0.0'. A package records the
contract version it was built against in its manifest
(AdapterPackageManifest.contractVersion), and verifyAdapterPackage refuses a
package whose contract MAJOR differs from the host's supportedContractMajor
(default = the SDK's MAJOR). So:
- A package built against
1.xinstalls on any host whose SDK is MAJOR1. - The day the SDK ships
2.0.0, that same package yields thecontract-version-incompatibleverdict on a MAJOR-2 host, andverifyAdapterForInstallreturnsrefused-contract-incompatible. You must ship a2.xbuild.
Because every breaking change in 2.0.0 was announced as a
RemoteDeprecation during the 1.x line (announce in a MINOR, sunset in the next
MAJOR — see Adapter SDK §7), the migration is never a
surprise: the work is enumerated by the deprecation list and surfaced by the type
checker.
Worked example — a hypothetical 1.x → 2.0.0#
Suppose 2.0.0 makes one breaking change: dispatch requires handlers to return
through a new typed ctx.complete(output) instead of a bare return output
(illustrative — it exercises every migration step). Here is the migration of the
reference createTextFileAdapter (text-file-adapter.ts).
Step 1 — read the deprecation list#
import { RemoteDeprecationRegistry } from '@bellona/remote-protocol';
// The SDK ships its deprecations; list the ones sunsetting in 2.0.0.
for (const d of registry.list()) {
console.log(d.commandName, d.announcedInVersion, '→ sunset', d.sunsetInVersion, d.migrationGuideUri);
}
Each entry names its replacement* and a migrationGuideUri. During 1.x,
registry.check(target, '1.4.0') returned deprecated (allowed + warning); on a
2.0.0 runtime it returns sunset and assertCommandNotSunset throws — that is
your fail-loud signal the old surface is gone.
Step 2 — bump the dependency and let the compiler find the breaks#
Update @bellona/remote-adapters to ^2.0.0 and rebuild. Every signature that
changed is now a type error. For the example change, each handler's return {...}
no longer type-checks against RemoteAdapterCommandHandler.
Step 3 — adopt the replacement at each call site#
Before (1.x):
handler: async (ctx) => {
const bytes = await writeFileBytes(path, content);
ctx.captureEvidence({ evidence, artifact });
return { path, bytesWritten: bytes };
};
After (2.0.0):
handler: async (ctx) => {
const bytes = await writeFileBytes(path, content);
ctx.captureEvidence({ evidence, artifact });
return ctx.complete({ path, bytesWritten: bytes }); // the replacement surface
};
Apply the same change to read / write / append. Where a default changed,
set it explicitly rather than relying on the new default.
Step 4 — re-run conformance against the new suite#
cd libs/bellona/remote-adapters && npx vitest run
runAdapterConformance(adapter, fixtures) is the source of truth. Green against
the 2.x suite ⇒ the adapter conforms to the new contract. Do not hand-reason
"it should still work" — the suite encodes the contract guarantees (timeout,
cancellation, idempotency, evidence attribution, typed errors).
Step 5 — re-stamp the package#
const pkg = buildAdapterPackage(
{ /* ...same inputs... */ /* contractVersion defaults to ADAPTER_SDK_CONTRACT_VERSION = '2.0.0' */ },
signingKey
);
// pkg.manifest.contractVersion === '2.0.0'
A MAJOR-2 host now accepts it; a MAJOR-1 host keeps installing your last 1.x
package. Publish both through the overlap window so hosts on either MAJOR have
an installable build.
Step 6 — bump your adapter's own version#
adapterVersion and contractVersion are independent axes
(AdapterPackageManifest records both). Adopting a contract MAJOR is at least a
MINOR of your adapter (new behaviour); make it a MAJOR if your own command surface
changed. Update adapterVersion in buildAdapterPackage input.
A field-level (MINOR) deprecation — the lighter path#
Most changes are MINOR, not MAJOR. When the SDK deprecates a single argument field
in 1.1 (sunset in 2.0.0):
- Your adapter keeps working on
1.1–1.x—checkreturnsdeprecated(allowed); surface/log the warning it returns. - Switch your handler to read the
replacementFieldPaththe deprecation names. - No package re-stamp is forced until the MAJOR sunset, but re-stamping early is harmless (the manifest just records a newer MINOR).
Because a field deprecation escalates with its command (a sunset command sunsets
its fields too), you never have to track command- and field-level sunsets
separately — registry.check(command, runtimeVersion, fieldPath) returns the
more-severe outcome.
Checklist#
- Listed the deprecations sunsetting in the target MAJOR (
registry.list()). - Bumped the SDK dependency; resolved every compiler error.
- Adopted each replacement surface; set changed defaults explicitly.
-
runAdapterConformancegreen against the new suite. - Re-stamped with
buildAdapterPackage(manifestcontractVersion= new MAJOR). - Published both the new and the last prior-MAJOR package for the overlap.
- Bumped the adapter's own
adapterVersion.