Eve library

Adapter SDK Migration Guide

Guide

Revision 1

On this page

Scope: a concrete, file-by-file walkthrough of migrating a RemoteAdapter across 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_VERSION and verifyAdapterPackage (libs/bellona/remote-adapters/src/contract.ts, packaging.ts), and the announce→sunset RemoteDeprecationRegistry (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.x installs on any host whose SDK is MAJOR 1.
  • The day the SDK ships 2.0.0, that same package yields the contract-version-incompatible verdict on a MAJOR-2 host, and verifyAdapterForInstall returns refused-contract-incompatible. You must ship a 2.x build.

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#

ts
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):

ts
handler: async (ctx) => {
  const bytes = await writeFileBytes(path, content);
  ctx.captureEvidence({ evidence, artifact });
  return { path, bytesWritten: bytes };
};

After (2.0.0):

ts
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#

bash
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#

ts
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):

  1. Your adapter keeps working on 1.1–1.x — check returns deprecated (allowed); surface/log the warning it returns.
  2. Switch your handler to read the replacementFieldPath the deprecation names.
  3. 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.
  • runAdapterConformance green against the new suite.
  • Re-stamped with buildAdapterPackage (manifest contractVersion = new MAJOR).
  • Published both the new and the last prior-MAJOR package for the overlap.
  • Bumped the adapter's own adapterVersion.