@forgezero/providers 0.1.19 → 0.1.21

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.21";
 
 // src/database.ts
 var pools = new Map;

package/dist/email.d.ts

@@ -2,6 +2,10 @@ import { type EmailBatch, type EmailBatchResult, type EmailMessage } from './ind
 export interface JetEmailConfig {
     /** EU residency endpoint. */
     eu?: boolean;
+    /** Bare sender mailbox. JetEmail's wire API receives it as `Name <mailbox>`. */
+    from?: string;
+    /** Optional display name. Defaults to the sender mailbox local part. */
+    fromName?: string;
     endpoint?: string;
     batchEndpoint?: string;
     fetch?: typeof globalThis.fetch;

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.21";
 
 // src/email.ts
 var recipients = (to) => Array.isArray(to) ? [...to] : [to];
@@ -310,6 +348,19 @@ function assertMessage(message) {
     throw new ProviderError("EMAIL_NO_BODY", "An email needs html, text, or both.");
   }
 }
+var JETEMAIL_MAILBOX = /^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/;
+function jetemailSender(config, override) {
+  const mailbox = (override ?? config.from ?? "").trim();
+  if (!JETEMAIL_MAILBOX.test(mailbox)) {
+    throw new ProviderError("JETEMAIL_FROM", "JetEmail needs a valid sender mailbox.");
+  }
+  const fallbackName = mailbox.slice(0, mailbox.indexOf("@"));
+  const name = (config.fromName ?? fallbackName).trim();
+  if (!name || /[\r\n<>]/.test(name)) {
+    throw new ProviderError("JETEMAIL_FROM_NAME", "JetEmail sender name must be non-empty and header-safe.");
+  }
+  return `${name} <${mailbox}>`;
+}
 var jetemailCredentials = {
   type: "object",
   additionalProperties: false,
@@ -328,10 +379,13 @@ var jetemailConfig = {
   additionalProperties: false,
   properties: {
     eu: { type: "boolean", default: false, title: "EU residency" },
-    from: { type: "string", format: "email", title: "Default from address" }
+    from: { type: "string", format: "email", title: "Default from address" },
+    fromName: { type: "string", minLength: 1, maxLength: 120, title: "Sender name" }
   }
 };
 var jetemailSend = defineProviderMethod({
+  version: "v1",
+  lifecycle: "current",
   async invoke(context, message) {
     assertMessage(message);
     const config = context.config;
@@ -346,7 +400,7 @@ var jetemailSend = defineProviderMethod({
         ...message.idempotencyKey ? { "idempotency-key": message.idempotencyKey } : {}
       },
       body: JSON.stringify({
-        from: message.from ?? config.from,
+        from: jetemailSender(config, message.from),
         to: recipients(message.to),
         subject: message.subject,
         html: message.html,
@@ -355,7 +409,7 @@ var jetemailSend = defineProviderMethod({
         eu: config.eu ?? false
       })
     });
-    if (response.status === 201 || response.status === 202) {
+    if (response.status === 200 || response.status === 201 || response.status === 202) {
       const payload = await response.json().catch(() => ({}));
       return { id: payload.id ?? "" };
     }
@@ -382,6 +436,8 @@ function assertBatch(batch) {
     assertMessage(message);
 }
 var jetemailSendBatch = defineProviderMethod({
+  version: "v1",
+  lifecycle: "current",
   async invoke(context, batch) {
     assertBatch(batch);
     const config = context.config;
@@ -395,7 +451,7 @@ var jetemailSendBatch = defineProviderMethod({
       },
       body: JSON.stringify({
         emails: batch.emails.map((message) => ({
-          from: message.from ?? config.from,
+          from: jetemailSender(config, message.from),
           to: recipients(message.to),
           subject: message.subject,
           html: message.html,
@@ -446,6 +502,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.21";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {