@forgezero/providers 0.1.18 → 0.1.20

package/README.md

@@ -59,7 +59,7 @@ bun test
 <a id="forgezero-providers"></a>
 ## @forgezero/providers
 
-The registry: priority, health, and a terminal-versus-retryable verdict per failure. This entry exposes 16 named value exports and 29 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+The registry: priority, health, and a terminal-versus-retryable verdict per failure. This entry exposes 17 named value exports and 31 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
 
 ```text
 import {
@@ -72,6 +72,7 @@ import {
   createService,
   defineProvider,
   defineProviderMethod,
+  defineProviderMethodBranches,
   defineService,
   defineSingleMethodProvider,
   envCredentials,
@@ -102,6 +103,8 @@ import type {
   ProviderDefinition,
   ProviderHealth,
   ProviderInstanceConfig,
+  ProviderMethodBranches,
+  ProviderMethodEntry,
   ProviderMethodSpec,
   ProviderMethods,
   RegistryOptions,
@@ -204,7 +207,7 @@ import type {
 
 ## @forgezero/providers/email — Email with ordered provider fallback
 
-The service owns send/sendBatch. Attach provider methods directly in priority arrays; SMTP is never presented as batch-capable.
+The service owns send/sendBatch. Ordered entries select exact provider method versions; SMTP is never presented as batch-capable.
 
 ```text
 import {
@@ -518,100 +521,154 @@ export const selectedCapability = RealtimeProviderError;
 
 ## Built-in provider capabilities
 
-A provider owns capabilities; it does not own a service. A service method attaches a provider instance and one of its methods. This keeps custom providers and custom services independent.
+A provider owns versioned capabilities; it does not own a service. A service method attaches an exact provider, method and version in an ordered array. Current, legacy and deprecated branches can coexist; retired branches never run.
 
 ```text
-evm-rpc              request
-jetemail             send, sendBatch
-smtp                 send
-arangodb             query
-http                 request
-s3                   request
-google-ai-studio     translate
+evm-rpc
+  - request
+jetemail
+  - send
+  - sendBatch
+smtp
+  - send
+arangodb
+  - query
+http
+  - request
+s3
+  - request
+google-ai-studio
+  - translate
 ```
 
 ## EVM JSON-RPC node (evm-rpc)
 
-Import: @forgezero/providers/chain. Methods: request. Credential fields: url, bearer. Nonsecret config: chainId, maxLogRange, timeoutMs. Several endpoints per chain is the normal case, not a luxury: public RPC is rate-limited and paid gateways have outages, and a scanner that stops when one is down stops crediting deposits while the money sits on the chain. "Already known" and "nonce too low" are TERMINAL — the transaction is already in flight, so rebroadcasting through another node is how a sweep gets sent twice.
+Import: @forgezero/providers/chain. Each method below is a provider capability that a service attaches by exact version. Several endpoints per chain is the normal case, not a luxury: public RPC is rate-limited and paid gateways have outages, and a scanner that stops when one is down stops crediting deposits while the money sits on the chain. "Already known" and "nonce too low" are TERMINAL — the transaction is already in flight, so rebroadcasting through another node is how a sweep gets sent twice.
 
 ```text
 importPath: '@forgezero/providers/chain'
 providerId: 'evm-rpc'
-methods: request
-credentials: url, bearer
-config: chainId, maxLogRange, timeoutMs
+methods:
+  - request
+credentials:
+  - url
+  - bearer
+config:
+  - chainId
+  - maxLogRange
+  - timeoutMs
 ```
 
 ## JetEmail (jetemail)
 
-Import: @forgezero/providers/email. Methods: send, sendBatch. Credential fields: apiKey. Nonsecret config: eu, from. A 401 is RETRYABLE at the loop level — that key is bad, the next provider's may not be. Treating any 4xx as fatal is what loses the fallback.
+Import: @forgezero/providers/email. Each method below is a provider capability that a service attaches by exact version. A 401 is RETRYABLE at the loop level — that key is bad, the next provider's may not be. Treating any 4xx as fatal is what loses the fallback.
 
 ```text
 importPath: '@forgezero/providers/email'
 providerId: 'jetemail'
-methods: send, sendBatch
-credentials: apiKey
-config: eu, from
+methods:
+  - send
+  - sendBatch
+credentials:
+  - apiKey
+config:
+  - eu
+  - from
 ```
 
 ## SMTP (smtp)
 
-Import: @forgezero/providers/email. Methods: send. Credential fields: user, password. Nonsecret config: host, port, secure, from, transport. Any number of named relays, each with its own priority slot. Also the bootstrap path: the vault opens after a ceremony, and the ceremony needs mail.
+Import: @forgezero/providers/email. Each method below is a provider capability that a service attaches by exact version. Any number of named relays, each with its own priority slot. Also the bootstrap path: the vault opens after a ceremony, and the ceremony needs mail.
 
 ```text
 importPath: '@forgezero/providers/email'
 providerId: 'smtp'
-methods: send
-credentials: user, password
-config: host, port, secure, from, transport
+methods:
+  - send
+credentials:
+  - user
+  - password
+config:
+  - host
+  - port
+  - secure
+  - from
+  - transport
 ```
 
 ## ArangoDB (arangodb)
 
-Import: @forgezero/providers/database. Methods: query. Credential fields: password. Nonsecret config: url, urls, readPreferredUrls, readPreferredFallback, clusterId, database, username. Failover is OFF by default. Writing to a different database because the first was slow is data loss with extra steps; this is here for credential rotation and health.
+Import: @forgezero/providers/database. Each method below is a provider capability that a service attaches by exact version. Failover is OFF by default. Writing to a different database because the first was slow is data loss with extra steps; this is here for credential rotation and health.
 
 ```text
 importPath: '@forgezero/providers/database'
 providerId: 'arangodb'
-methods: query
-credentials: password
-config: url, urls, readPreferredUrls, readPreferredFallback, clusterId, database, username
+methods:
+  - query
+credentials:
+  - password
+config:
+  - url
+  - urls
+  - readPreferredUrls
+  - readPreferredFallback
+  - clusterId
+  - database
+  - username
 ```
 
 ## HTTP (http)
 
-Import: @forgezero/providers/http. Methods: request. Credential fields: apiKey, apiSecret. Nonsecret config: baseUrl, limit, windowMs, headroom. 418 and 429 back off rather than falling through. 418 is a venue saying "you ignored a 429 and are now banned", and hammering makes the ban longer.
+Import: @forgezero/providers/http. Each method below is a provider capability that a service attaches by exact version. 418 and 429 back off rather than falling through. 418 is a venue saying "you ignored a 429 and are now banned", and hammering makes the ban longer.
 
 ```text
 importPath: '@forgezero/providers/http'
 providerId: 'http'
-methods: request
-credentials: apiKey, apiSecret
-config: baseUrl, limit, windowMs, headroom
+methods:
+  - request
+credentials:
+  - apiKey
+  - apiSecret
+config:
+  - baseUrl
+  - limit
+  - windowMs
+  - headroom
 ```
 
 ## S3-compatible storage (s3)
 
-Import: @forgezero/providers/storage. Methods: request. Credential fields: accessKeyId, secretAccessKey, sessionToken. Nonsecret config: endpoint, region, bucket, addressing. A 403 is retryable because on S3 it usually means this key lacks a permission, not that the key is invalid. Works against AWS, R2, MinIO, Garage and Backblaze — path-style addressing by default, because that is what everything except AWS expects.
+Import: @forgezero/providers/storage. Each method below is a provider capability that a service attaches by exact version. A 403 is retryable because on S3 it usually means this key lacks a permission, not that the key is invalid. Works against AWS, R2, MinIO, Garage and Backblaze — path-style addressing by default, because that is what everything except AWS expects.
 
 ```text
 importPath: '@forgezero/providers/storage'
 providerId: 's3'
-methods: request
-credentials: accessKeyId, secretAccessKey, sessionToken
-config: endpoint, region, bucket, addressing
+methods:
+  - request
+credentials:
+  - accessKeyId
+  - secretAccessKey
+  - sessionToken
+config:
+  - endpoint
+  - region
+  - bucket
+  - addressing
 ```
 
 ## Google AI Studio (google-ai-studio)
 
-Import: @forgezero/providers/translation. Methods: translate. Credential fields: apiKey. Nonsecret config: model. Machine translation for a tenant that wants it — ForgeZero translates nothing at runtime. Chosen as the first adapter because the free tier needs no billing account, so the feature can be tried without a procurement conversation. A 429 is a BACKOFF rather than a failure: on the free tier it is expected traffic, and treating it as terminal abandons a catalogue most of the way through. A short answer is terminal, because one translation missing from a batch shifts every later string onto the wrong source and nothing about the result looks broken afterwards.
+Import: @forgezero/providers/translation. Each method below is a provider capability that a service attaches by exact version. Machine translation for a tenant that wants it — ForgeZero translates nothing at runtime. Chosen as the first adapter because the free tier needs no billing account, so the feature can be tried without a procurement conversation. A 429 is a BACKOFF rather than a failure: on the free tier it is expected traffic, and treating it as terminal abandons a catalogue most of the way through. A short answer is terminal, because one translation missing from a batch shifts every later string onto the wrong source and nothing about the result looks broken afterwards.
 
 ```text
 importPath: '@forgezero/providers/translation'
 providerId: 'google-ai-studio'
-methods: translate
-credentials: apiKey
-config: model
+methods:
+  - translate
+credentials:
+  - apiKey
+config:
+  - model
 ```
 
 Full rendered documentation: https://www.forgezero.net/docs/providers

package/dist/binance.js

@@ -75,25 +75,55 @@ function staticConfig(config) {
     async list(serviceKey, methodKey) {
       return (config.services[serviceKey]?.[methodKey] ?? []).map((attachment) => ({
         ...attachment,
-        health: health.get(`${serviceKey}:${methodKey}:${attachment.instanceKey}:${attachment.providerMethod}`) ?? attachment.health
+        health: health.get(`${serviceKey}:${methodKey}:${attachment.instanceKey}:${attachment.providerMethod}:${attachment.providerMethodVersion ?? "current"}`) ?? (attachment.providerMethodVersion === undefined ? [...health.entries()].find(([key]) => key.startsWith(`${serviceKey}:${methodKey}:${attachment.instanceKey}:${attachment.providerMethod}:`))?.[1] : undefined) ?? attachment.health
       }));
     },
-    async recordHealth(serviceKey, methodKey, instanceKey, providerMethod, next) {
-      health.set(`${serviceKey}:${methodKey}:${instanceKey}:${providerMethod}`, next);
+    async recordHealth(serviceKey, methodKey, instanceKey, providerMethod, providerMethodVersion, next) {
+      health.set(`${serviceKey}:${methodKey}:${instanceKey}:${providerMethod}:${providerMethodVersion}`, next);
     }
   };
 }
 function defineProviderMethod(method) {
   return method;
 }
+function defineProviderMethodBranches(branches) {
+  const entries = Object.entries(branches.versions);
+  if (entries.length === 0 || !branches.versions[branches.currentVersion]) {
+    throw new ProviderError("PROVIDER_METHOD_VERSION", "A versioned provider method needs a current branch.");
+  }
+  for (const [version, method] of entries) {
+    if (method.version !== version) {
+      throw new ProviderError("PROVIDER_METHOD_VERSION", `Provider method branch "${version}" declares version "${method.version}".`);
+    }
+    if (version === branches.currentVersion && method.lifecycle !== "current") {
+      throw new ProviderError("PROVIDER_METHOD_VERSION", `Current provider method branch "${version}" must have lifecycle current.`);
+    }
+  }
+  return branches;
+}
+var methodBranch = (provider, methodName, version) => {
+  const entry = provider?.methods[methodName];
+  if (!entry)
+    return;
+  if ("versions" in entry)
+    return entry.versions[version ?? entry.currentVersion];
+  return version === undefined || version === entry.version ? entry : undefined;
+};
 function defineProvider(spec) {
+  for (const [name, entry] of Object.entries(spec.methods)) {
+    if ("versions" in entry)
+      defineProviderMethodBranches(entry);
+    else if (!entry.version || !["current", "legacy", "deprecated", "retired"].includes(entry.lifecycle)) {
+      throw new ProviderError("PROVIDER_METHOD_VERSION", `Provider method "${spec.id}.${name}" needs a version and lifecycle.`);
+    }
+  }
   return spec;
 }
 function defineSingleMethodProvider(spec) {
-  const { method, invoke, classify, ...identity } = spec;
+  const { method, version = "v1", lifecycle = "current", invoke, classify, ...identity } = spec;
   return defineProvider({
     ...identity,
-    methods: { [method]: defineProviderMethod({ invoke, classify }) }
+    methods: { [method]: defineProviderMethod({ version, lifecycle, invoke, classify }) }
   });
 }
 var STRIKES_TO_OFFLINE = 3;
@@ -121,6 +151,7 @@ function createRegistry(options) {
     const configured = [...await options.config.list(serviceKey, methodKey)].filter((attachment) => attachment.enabled).sort((a, b) => a.priority - b.priority);
     const attempts = [];
     for (const attachment of configured) {
+      const requestedVersion = attachment.providerMethodVersion;
       if (callOptions.signal?.aborted) {
         const cancelled = {
           ok: false,
@@ -133,21 +164,25 @@ function createRegistry(options) {
       }
       const instance = await options.config.provider(attachment.instanceKey);
       if (!instance) {
-        attempts.push({ providerId: "unknown", instanceKey: attachment.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance not registered" });
+        attempts.push({ providerId: "unknown", instanceKey: attachment.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: requestedVersion ?? "current", outcome: "skipped", error: "instance not registered" });
         continue;
       }
       const spec = byId.get(instance.providerId);
-      const method = spec?.methods[attachment.providerMethod];
+      const method = methodBranch(spec, attachment.providerMethod, requestedVersion);
       if (!spec || !method) {
-        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: !spec ? "provider not registered" : "method not supported" });
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: requestedVersion ?? "current", outcome: "skipped", error: !spec ? "provider not registered" : "method version not supported" });
+        continue;
+      }
+      if (method.lifecycle === "retired") {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version, outcome: "skipped", error: "method version retired" });
         continue;
       }
       if (!instance.enabled) {
-        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance disabled" });
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version, outcome: "skipped", error: "instance disabled" });
         continue;
       }
       if (attachment.health?.status === "offline") {
-        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "offline" });
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version, outcome: "skipped", error: "offline" });
         continue;
       }
       await options.before?.({ service: serviceKey, method: methodKey, provider: instance.providerId, instance: instance.instanceKey });
@@ -158,15 +193,15 @@ function createRegistry(options) {
           secret: (field) => options.credentials.get(instance.secretRef, field),
           signal: callOptions.signal
         }, args);
-        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "sent", durationMs: performance.now() - startedAt });
-        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, nextHealth(attachment.health, "success"));
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version, outcome: "sent", durationMs: performance.now() - startedAt });
+        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, method.version, nextHealth(attachment.health, "success"));
         const sent = {
           ok: true,
           result,
           provider: instance.providerId,
           instance: instance.instanceKey,
           method: attachment.providerMethod,
-          selected: { providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod },
+          selected: { providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version },
           fallbackUsed: attempts.length > 1,
           attempts
         };
@@ -190,13 +225,14 @@ function createRegistry(options) {
           providerId: instance.providerId,
           instanceKey: instance.instanceKey,
           providerMethod: attachment.providerMethod,
+          providerMethodVersion: method.version,
           outcome: "failed",
           kind,
           durationMs: performance.now() - startedAt,
           failure: { kind, ...code ? { code } : {}, message },
           error: message
         });
-        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, nextHealth(attachment.health, kind));
+        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, method.version, nextHealth(attachment.health, kind));
         if (kind === "terminal") {
           const refused = {
             ok: false,
@@ -246,8 +282,9 @@ function createService(definition, methods, options = {}) {
         throw new ProviderError("CONFIG_PRIORITY_DUPLICATE", `Priorities for "${definition.key}.${methodKey}" must be unique.`);
       }
       priorities.add(attachment.priority);
-      if (!attachment.provider.methods[attachment.method]) {
-        throw new ProviderError("CONFIG_METHOD_UNSUPPORTED", `Provider "${attachment.provider.id}" does not support "${attachment.method}".`);
+      const branch = methodBranch(attachment.provider, attachment.method, attachment.version);
+      if (!branch || branch.lifecycle === "retired") {
+        throw new ProviderError("CONFIG_METHOD_UNSUPPORTED", `Provider "${attachment.provider.id}" does not support active method "${attachment.method}@${attachment.version ?? "current"}".`);
       }
       const existing = providers.get(attachment.provider.id);
       if (existing && existing !== attachment.provider) {
@@ -266,6 +303,7 @@ function createService(definition, methods, options = {}) {
       return {
         instanceKey: internalKey,
         providerMethod: attachment.method,
+        providerMethodVersion: branch.version,
         priority: attachment.priority,
         enabled: attachment.enabled ?? true
       };
@@ -292,13 +330,13 @@ function createService(definition, methods, options = {}) {
       const { instance: _instance, selected, attempts, ...rest } = result;
       return {
         ...rest,
-        ...selected ? { selected: { providerId: selected.providerId, providerMethod: selected.providerMethod } } : {},
+        ...selected ? { selected: { providerId: selected.providerId, providerMethod: selected.providerMethod, providerMethodVersion: selected.providerMethodVersion } } : {},
         attempts: attempts.map(({ instanceKey: _instanceKey, ...attempt }) => attempt)
       };
     }
   };
 }
-var VERSION = "0.1.18";
+var VERSION = "0.1.20";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/chain.js

@@ -75,25 +75,55 @@ function staticConfig(config) {
     async list(serviceKey, methodKey) {
       return (config.services[serviceKey]?.[methodKey] ?? []).map((attachment) => ({
         ...attachment,
-        health: health.get(`${serviceKey}:${methodKey}:${attachment.instanceKey}:${attachment.providerMethod}`) ?? attachment.health
+        health: health.get(`${serviceKey}:${methodKey}:${attachment.instanceKey}:${attachment.providerMethod}:${attachment.providerMethodVersion ?? "current"}`) ?? (attachment.providerMethodVersion === undefined ? [...health.entries()].find(([key]) => key.startsWith(`${serviceKey}:${methodKey}:${attachment.instanceKey}:${attachment.providerMethod}:`))?.[1] : undefined) ?? attachment.health
       }));
     },
-    async recordHealth(serviceKey, methodKey, instanceKey, providerMethod, next) {
-      health.set(`${serviceKey}:${methodKey}:${instanceKey}:${providerMethod}`, next);
+    async recordHealth(serviceKey, methodKey, instanceKey, providerMethod, providerMethodVersion, next) {
+      health.set(`${serviceKey}:${methodKey}:${instanceKey}:${providerMethod}:${providerMethodVersion}`, next);
     }
   };
 }
 function defineProviderMethod(method) {
   return method;
 }
+function defineProviderMethodBranches(branches) {
+  const entries = Object.entries(branches.versions);
+  if (entries.length === 0 || !branches.versions[branches.currentVersion]) {
+    throw new ProviderError("PROVIDER_METHOD_VERSION", "A versioned provider method needs a current branch.");
+  }
+  for (const [version, method] of entries) {
+    if (method.version !== version) {
+      throw new ProviderError("PROVIDER_METHOD_VERSION", `Provider method branch "${version}" declares version "${method.version}".`);
+    }
+    if (version === branches.currentVersion && method.lifecycle !== "current") {
+      throw new ProviderError("PROVIDER_METHOD_VERSION", `Current provider method branch "${version}" must have lifecycle current.`);
+    }
+  }
+  return branches;
+}
+var methodBranch = (provider, methodName, version) => {
+  const entry = provider?.methods[methodName];
+  if (!entry)
+    return;
+  if ("versions" in entry)
+    return entry.versions[version ?? entry.currentVersion];
+  return version === undefined || version === entry.version ? entry : undefined;
+};
 function defineProvider(spec) {
+  for (const [name, entry] of Object.entries(spec.methods)) {
+    if ("versions" in entry)
+      defineProviderMethodBranches(entry);
+    else if (!entry.version || !["current", "legacy", "deprecated", "retired"].includes(entry.lifecycle)) {
+      throw new ProviderError("PROVIDER_METHOD_VERSION", `Provider method "${spec.id}.${name}" needs a version and lifecycle.`);
+    }
+  }
   return spec;
 }
 function defineSingleMethodProvider(spec) {
-  const { method, invoke, classify, ...identity } = spec;
+  const { method, version = "v1", lifecycle = "current", invoke, classify, ...identity } = spec;
   return defineProvider({
     ...identity,
-    methods: { [method]: defineProviderMethod({ invoke, classify }) }
+    methods: { [method]: defineProviderMethod({ version, lifecycle, invoke, classify }) }
   });
 }
 var STRIKES_TO_OFFLINE = 3;
@@ -121,6 +151,7 @@ function createRegistry(options) {
     const configured = [...await options.config.list(serviceKey, methodKey)].filter((attachment) => attachment.enabled).sort((a, b) => a.priority - b.priority);
     const attempts = [];
     for (const attachment of configured) {
+      const requestedVersion = attachment.providerMethodVersion;
       if (callOptions.signal?.aborted) {
         const cancelled = {
           ok: false,
@@ -133,21 +164,25 @@ function createRegistry(options) {
       }
       const instance = await options.config.provider(attachment.instanceKey);
       if (!instance) {
-        attempts.push({ providerId: "unknown", instanceKey: attachment.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance not registered" });
+        attempts.push({ providerId: "unknown", instanceKey: attachment.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: requestedVersion ?? "current", outcome: "skipped", error: "instance not registered" });
         continue;
       }
       const spec = byId.get(instance.providerId);
-      const method = spec?.methods[attachment.providerMethod];
+      const method = methodBranch(spec, attachment.providerMethod, requestedVersion);
       if (!spec || !method) {
-        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: !spec ? "provider not registered" : "method not supported" });
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: requestedVersion ?? "current", outcome: "skipped", error: !spec ? "provider not registered" : "method version not supported" });
+        continue;
+      }
+      if (method.lifecycle === "retired") {
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version, outcome: "skipped", error: "method version retired" });
         continue;
       }
       if (!instance.enabled) {
-        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "instance disabled" });
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version, outcome: "skipped", error: "instance disabled" });
         continue;
       }
       if (attachment.health?.status === "offline") {
-        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "skipped", error: "offline" });
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version, outcome: "skipped", error: "offline" });
         continue;
       }
       await options.before?.({ service: serviceKey, method: methodKey, provider: instance.providerId, instance: instance.instanceKey });
@@ -158,15 +193,15 @@ function createRegistry(options) {
           secret: (field) => options.credentials.get(instance.secretRef, field),
           signal: callOptions.signal
         }, args);
-        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, outcome: "sent", durationMs: performance.now() - startedAt });
-        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, nextHealth(attachment.health, "success"));
+        attempts.push({ providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version, outcome: "sent", durationMs: performance.now() - startedAt });
+        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, method.version, nextHealth(attachment.health, "success"));
         const sent = {
           ok: true,
           result,
           provider: instance.providerId,
           instance: instance.instanceKey,
           method: attachment.providerMethod,
-          selected: { providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod },
+          selected: { providerId: instance.providerId, instanceKey: instance.instanceKey, providerMethod: attachment.providerMethod, providerMethodVersion: method.version },
           fallbackUsed: attempts.length > 1,
           attempts
         };
@@ -190,13 +225,14 @@ function createRegistry(options) {
           providerId: instance.providerId,
           instanceKey: instance.instanceKey,
           providerMethod: attachment.providerMethod,
+          providerMethodVersion: method.version,
           outcome: "failed",
           kind,
           durationMs: performance.now() - startedAt,
           failure: { kind, ...code ? { code } : {}, message },
           error: message
         });
-        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, nextHealth(attachment.health, kind));
+        await options.config.recordHealth(serviceKey, methodKey, instance.instanceKey, attachment.providerMethod, method.version, nextHealth(attachment.health, kind));
         if (kind === "terminal") {
           const refused = {
             ok: false,
@@ -246,8 +282,9 @@ function createService(definition, methods, options = {}) {
         throw new ProviderError("CONFIG_PRIORITY_DUPLICATE", `Priorities for "${definition.key}.${methodKey}" must be unique.`);
       }
       priorities.add(attachment.priority);
-      if (!attachment.provider.methods[attachment.method]) {
-        throw new ProviderError("CONFIG_METHOD_UNSUPPORTED", `Provider "${attachment.provider.id}" does not support "${attachment.method}".`);
+      const branch = methodBranch(attachment.provider, attachment.method, attachment.version);
+      if (!branch || branch.lifecycle === "retired") {
+        throw new ProviderError("CONFIG_METHOD_UNSUPPORTED", `Provider "${attachment.provider.id}" does not support active method "${attachment.method}@${attachment.version ?? "current"}".`);
       }
       const existing = providers.get(attachment.provider.id);
       if (existing && existing !== attachment.provider) {
@@ -266,6 +303,7 @@ function createService(definition, methods, options = {}) {
       return {
         instanceKey: internalKey,
         providerMethod: attachment.method,
+        providerMethodVersion: branch.version,
         priority: attachment.priority,
         enabled: attachment.enabled ?? true
       };
@@ -292,13 +330,13 @@ function createService(definition, methods, options = {}) {
       const { instance: _instance, selected, attempts, ...rest } = result;
       return {
         ...rest,
-        ...selected ? { selected: { providerId: selected.providerId, providerMethod: selected.providerMethod } } : {},
+        ...selected ? { selected: { providerId: selected.providerId, providerMethod: selected.providerMethod, providerMethodVersion: selected.providerMethodVersion } } : {},
         attempts: attempts.map(({ instanceKey: _instanceKey, ...attempt }) => attempt)
       };
     }
   };
 }
-var VERSION = "0.1.18";
+var VERSION = "0.1.20";
 
 // src/chain.ts
 var hexToNumber = (value) => Number(BigInt(value));