@forgezero/providers 0.1.19 → 0.1.20

package/dist/index.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.19";
+var VERSION = "0.1.20";
 export {
   staticConfig,
   serviceMethod,
@@ -307,6 +345,7 @@ export {
   envCredentials,
   defineSingleMethodProvider,
   defineService,
+  defineProviderMethodBranches,
   defineProviderMethod,
   defineProvider,
   createService,

package/dist/pool.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.19";
+var VERSION = "0.1.20";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/storage.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.19";
+var VERSION = "0.1.20";
 
 // src/storage.ts
 var encoder = new TextEncoder;