# Adapter SDK Migration Guide

> 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](./adapter-sdk.md)** §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](./adapter-sdk.md) §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`.
