@forgezero/providers 0.1.19 → 0.1.20

package/dist/database.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/database.ts
 var pools = new Map;

package/dist/email.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/email.ts
 var recipients = (to) => Array.isArray(to) ? [...to] : [to];
@@ -332,6 +370,8 @@ var jetemailConfig = {
   }
 };
 var jetemailSend = defineProviderMethod({
+  version: "v1",
+  lifecycle: "current",
   async invoke(context, message) {
     assertMessage(message);
     const config = context.config;
@@ -382,6 +422,8 @@ function assertBatch(batch) {
     assertMessage(message);
 }
 var jetemailSendBatch = defineProviderMethod({
+  version: "v1",
+  lifecycle: "current",
   async invoke(context, batch) {
     assertBatch(batch);
     const config = context.config;
@@ -446,6 +488,8 @@ var jetemail = defineProvider({
   }
 });
 var smtpSend = defineProviderMethod({
+  version: "rfc5321",
+  lifecycle: "current",
   async invoke(context, message) {
     assertMessage(message);
     const config = context.config;

package/dist/http.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/index.d.ts

@@ -80,6 +80,8 @@ export interface ServiceMethodAttachment {
     instanceKey: string;
     /** Explicit provider capability; it is never inferred from the service name. */
     providerMethod: string;
+    /** Exact provider API/contract branch. Omit only to select the provider's declared current branch. */
+    providerMethodVersion?: string;
     priority: number;
     enabled: boolean;
     health?: ProviderHealth;
@@ -90,7 +92,7 @@ export interface ConfigSource {
     provider(instanceKey: string): Promise<ProviderInstanceConfig | undefined>;
     list(serviceKey: string, methodKey: string): Promise<readonly ServiceMethodAttachment[]>;
     /** Persisted, because strikes that reset on restart retry a dead provider forever. */
-    recordHealth(serviceKey: string, methodKey: string, instanceKey: string, providerMethod: string, health: ProviderHealth): Promise<void>;
+    recordHealth(serviceKey: string, methodKey: string, instanceKey: string, providerMethod: string, providerMethodVersion: string, health: ProviderHealth): Promise<void>;
 }
 export interface StaticRegistryConfig {
     providers: readonly ProviderInstanceConfig[];
@@ -116,12 +118,21 @@ export interface InvokeContext {
     signal?: AbortSignal;
 }
 export interface ProviderMethodSpec<Args = never, Result = never> {
+    /** Provider-owned contract/API branch, such as `v1` or `2026-08-01`. */
+    version: string;
+    lifecycle: 'current' | 'legacy' | 'deprecated' | 'retired';
     invoke(context: InvokeContext, args: Args): Promise<Result>;
     classify(error: unknown): FailureKind;
 }
 export declare function defineProviderMethod<Args, Result>(method: ProviderMethodSpec<Args, Result>): ProviderMethodSpec<Args, Result>;
 export type AnyProviderMethod = ProviderMethodSpec<any, any>;
-export type ProviderMethods = Record<string, AnyProviderMethod>;
+export interface ProviderMethodBranches<Args = any, Result = any> {
+    currentVersion: string;
+    versions: Readonly<Record<string, ProviderMethodSpec<Args, Result>>>;
+}
+export declare function defineProviderMethodBranches<Args, Result>(branches: ProviderMethodBranches<Args, Result>): ProviderMethodBranches<Args, Result>;
+export type ProviderMethodEntry = AnyProviderMethod | ProviderMethodBranches;
+export type ProviderMethods = Record<string, ProviderMethodEntry>;
 /** A vendor/provider identity with named capabilities, independent of services. */
 export interface ProviderDefinition<Methods extends ProviderMethods = ProviderMethods> {
     id: string;
@@ -136,6 +147,8 @@ export declare function defineProvider<Methods extends ProviderMethods>(spec: Pr
 /** Convenience for a provider that exposes exactly one named method. */
 export declare function defineSingleMethodProvider<Method extends string, Args, Result>(spec: Omit<ProviderDefinition<Record<Method, ProviderMethodSpec<Args, Result>>>, 'methods'> & {
     method: Method;
+    version?: string;
+    lifecycle?: ProviderMethodSpec['lifecycle'];
     invoke(context: InvokeContext, args: Args): Promise<Result>;
     classify(error: unknown): FailureKind;
 }): ProviderDefinition<Record<Method, ProviderMethodSpec<Args, Result>>>;
@@ -144,6 +157,7 @@ export interface Attempt {
     providerId: string;
     instanceKey: string;
     providerMethod: string;
+    providerMethodVersion: string;
     outcome: 'sent' | 'skipped' | 'failed';
     kind?: FailureKind;
     durationMs?: number;
@@ -165,6 +179,7 @@ export interface CallResult<Result> {
         providerId: string;
         instanceKey: string;
         providerMethod: string;
+        providerMethodVersion: string;
     };
     fallbackUsed: boolean;
     attempts: readonly Attempt[];
@@ -196,6 +211,8 @@ type ServiceResult<T> = T extends ServiceMethodContract<unknown, infer Result> ?
 export interface DirectServiceAttachment {
     provider: ProviderDefinition;
     method: string;
+    /** Select an exact legacy/current branch. Omit to use the provider's declared currentVersion. */
+    version?: string;
     credentials: ScopedCredentialSource;
     config?: Record<string, unknown>;
     priority: number;
@@ -213,6 +230,7 @@ export type DirectCallResult<Result> = Omit<CallResult<Result>, 'instance' | 'se
     selected?: {
         providerId: string;
         providerMethod: string;
+        providerMethodVersion: string;
     };
     attempts: readonly DirectAttempt[];
 };
@@ -285,5 +303,5 @@ export interface EmailBatchResult {
     };
     results: readonly EmailBatchItemResult[];
 }
-export declare const VERSION = "0.1.19";
+export declare const VERSION = "0.1.20";
 export {};