# Versioning and migration notes

The current [release candidate](/docs/rc) keeps wire protocol `1.0`. Python uses reviewed GitHub archives while PyPI approval is pending. Keep the installed artifact's source and lockfile.
The host and language packages may receive independent package versions while
retaining an explicitly compatible protocol.

Before changing a host or client, call `protocol()`, require the features your
workflow uses, and check the [compatibility matrix](/docs/compatibility). Unknown
required events or incompatible major wire versions must fail clearly.
[Protocol rules](/docs/protocol) define optional-event negotiation and stable errors.

## Alpha.6: remove mock providers and upgrade management together

Back up a host's private configuration, then remove any provider entries whose
`kind` is `mock` and the corresponding provider IDs from grants. Alpha.6 rejects
that legacy configuration with `MOCK_PROVIDER_REMOVED`; it never silently turns
a fake connection into a real account. Preserve actual providers, native account
directories, Usagestat identities and application grants. Configure the intended
real connection explicitly. New CLI setup requires `--provider`.

The `mockProvider` export, `DeterministicEmbeddingAdapter`,
`@agenticdriver/sdk/provider-conformance` subpath and simulated acceptance scripts
have been removed. Replace fake embedding configuration with an actual supported
embedding account before using vector indexing. Historical usage records remain
readable; new adapters cannot emit `synthetic` usage provenance.

Upgrade the execution host before its management clients, or coordinate both in
one maintenance window after active work drains. Older hosts advertise the removed
`fixture` provider-definition category, which alpha.6 management clients reject.
Wire protocol 1.0 alone does not establish management compatibility. Older clients
can read alpha.6's remaining categories. An SDK dependency update does not replace
a running host or expand saved grants. Never restart another application's host
without coordinating its active work.

## Organization package names before 0.1.0

The SDK repository is now `agenticdriver/agenticdriver`. JavaScript applications
adopt the npm package `@agenticdriver/sdk`, replacing development imports from
`agenticdriver` and its subpaths. The CLI command remains `agenticdriver`.
Go applications adopt `github.com/agenticdriver/agenticdriver/clients/go` in both
their imports and `go.mod`. Python and Rust retain the name `agenticdriver`.

No registry package or semantic-version Go tag was published under the earlier
personal ownership plan. Existing development archives should remain pinned
until each app verifies the new published package, imports, lockfile and workflow.
The wire protocol remains 1.0. See [release ownership and readiness](/docs/releases).

## From sibling source dependencies

Build or obtain reviewed npm/wheel/module/crate artifacts, install them in the
application, and retain its lockfile. The [quickstart](/docs/quickstart) shows all four
languages. Do not use a checkout-relative TypeScript alias, Python import path or
Go `replace` directive as a deployment dependency. A Rust path to the extracted
crate in an application's vendored artifacts is distinct from a sibling checkout.
Move to registry coordinates only after the deliberate package release and
installation checks have completed.

## From static driver credentials

Keep the application's canonical user, organization and service IDs. Programmatic hosts can supply `HostAuthentication` backed by the application's existing policy. Use either that interface or static tokens, never both. Static CLI tokens remain supported; changing a configured static token requires a coordinated host restart. See [Access control](/docs/remote-access).

## Preserve execution and data contracts

- Keep stable Usagestat `hostId`, provider instance and `accountId` bindings.
  Accounting depends on these identities; model names are not account identities.
- Preserve canonical source IDs and revisions when changing parsing, chunking or
  embeddings. Use revision checks and atomic replacement; revalidate ownership
  when evidence is read.
- Require current durable-job authorization through a deliberate resolver.
  Expired request tokens cannot become indefinite worker credentials.
- Keep application approvals and accepted artifacts in the application.
  Validate returned citation IDs against actual selected evidence before saving.
- Cancel/drain a host deliberately before upgrades, back up its compatible state,
  and verify idempotent replay after restart. Never retry an uncertain side effect
  solely because the network connection was lost.