@forgezero/providers 0.1.21 → 0.1.23

package/README.md

@@ -11,7 +11,7 @@ Send through whichever provider is up. Priority and failover, reordered live.
 
 ## Package overview
 
-Anyone calling somebody else's API who needs the failure classified rather than guessed. Provider capabilities stay independent from application-owned services, which attach named methods by priority with health tracking. Supported runtimes: bun, node, workers, deno. Package root: @forgezero/providers. The sections below show the actual named imports emitted by each declaration entry point; wildcard imports are intentionally not used in the documentation.
+Anyone calling somebody else's API who needs the failure classified rather than guessed. Provider capabilities stay independent from application-owned services, which attach named methods by priority with health tracking. Supported runtimes: bun, node, workers, deno. Package root: @forgezero/providers. Consumer documentation is curated with each module's explicit public flag; the complete internal/export inventory remains in the typed SSOT and declaration files.
 
 ```text
 bun add @forgezero/providers
@@ -29,9 +29,9 @@ The five packages are installation boundaries. Choose a package by who installs
 | @forgezero/runtime | Portable runtime primitives for queries, jobs, events, schemas and finance. | bun, node | [Open](https://www.forgezero.net/docs/runtime) |
 | @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | bun, node | [Open](https://www.forgezero.net/docs/agent) |
 
-## @forgezero/providers public imports and commands
+## @forgezero/providers supported imports and commands
 
-Every row links to the detailed explanation and named-import/example area below. This table and those details are generated from the package inventory and emitted declarations.
+These are supported consumer entry points, not every internal module shipped for ForgeZero managed installation. Each row links to its task-oriented usage.
 
 | public entry | short description | runtime | details |
 |---|---|---|---|
@@ -45,6 +45,7 @@ Every row links to the detailed explanation and named-import/example area below.
 | @forgezero/providers/storage | S3-compatible object storage, SigV4 signed with Web Crypto and no vendor SDK. | portable | [Reference + usage](#forgezero-providers-storage) |
 | @forgezero/providers/translation | Google AI Studio translation with strict batch alignment and classified quota failures. | portable | [Reference + usage](#forgezero-providers-translation) |
 | @forgezero/providers/realtime | Cloudflare KV node-directory and Durable Object fan-out clients for project-defined realtime services. | portable | [Reference + usage](#forgezero-providers-realtime) |
+| @forgezero/providers/git | Versioned Git Connect contracts for accounts, repositories, branches, webhooks and short-lived clone credentials; GitHub, GitLab and private forges attach without changing the service. | portable | [Reference + usage](#forgezero-providers-git) |
 
 ## Commands
 
@@ -59,61 +60,11 @@ bun test
 <a id="forgezero-providers"></a>
 ## @forgezero/providers
 
-The registry: priority, health, and a terminal-versus-retryable verdict per failure. This entry exposes 17 named value exports and 31 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+The registry: priority, health, and a terminal-versus-retryable verdict per failure. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   ProviderError,
-  STRIKES_TO_OFFLINE,
-  VERSION,
-  chainCredentials,
-  chainScopedCredentials,
-  createRegistry,
-  createService,
-  defineProvider,
-  defineProviderMethod,
-  defineProviderMethodBranches,
-  defineService,
-  defineSingleMethodProvider,
-  envCredentials,
-  nextHealth,
-  scopeCredentials,
-  serviceMethod,
-  staticConfig,
-} from '@forgezero/providers';
-
-import type {
-  AnyProviderMethod,
-  Attempt,
-  CallOptions,
-  CallResult,
-  ConfigSource,
-  CredentialSource,
-  DirectAttempt,
-  DirectCallResult,
-  DirectServiceAttachment,
-  DirectServiceConfig,
-  DirectServiceOptions,
-  EmailBatch,
-  EmailBatchItemResult,
-  EmailBatchResult,
-  EmailMessage,
-  FailureKind,
-  InvokeContext,
-  ProviderDefinition,
-  ProviderHealth,
-  ProviderInstanceConfig,
-  ProviderMethodBranches,
-  ProviderMethodEntry,
-  ProviderMethodSpec,
-  ProviderMethods,
-  RegistryOptions,
-  ScopedCredentialSource,
-  ServiceDefinition,
-  ServiceMethodAttachment,
-  ServiceMethodContract,
-  ServiceMethods,
-  StaticRegistryConfig,
 } from '@forgezero/providers';
 ```
 
@@ -189,19 +140,11 @@ const credentials = chainScopedCredentials(
 <a id="forgezero-providers-email"></a>
 ## @forgezero/providers/email
 
-JetEmail (`send`, `sendBatch`), SMTP (`send` only), and the typed email service contract; SMTP transport is injected. This entry exposes 4 named value exports and 2 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+JetEmail (`send`, `sendBatch`), SMTP (`send` only), and the typed email service contract; SMTP transport is injected. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   emailProviders,
-  emailService,
-  jetemail,
-  smtp,
-} from '@forgezero/providers/email';
-
-import type {
-  JetEmailConfig,
-  SmtpTransport,
 } from '@forgezero/providers/email';
 ```
 
@@ -250,27 +193,11 @@ console.log(outcome.result, outcome.attempts);
 <a id="forgezero-providers-database"></a>
 ## @forgezero/providers/database
 
-ArangoDB in the registry for credential rotation and health — with failover off by default. This entry exposes 7 named value exports and 7 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+ArangoDB in the registry for credential rotation and health — with failover off by default. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   ARANGO_COMMUNITY_VERSION,
-  ARANGO_SERVER_MODE_PATH,
-  MAX_ARANGO_COORDINATORS,
-  arangoCoordinatorUrls,
-  arangodb,
-  databaseProviders,
-  resetPools,
-} from '@forgezero/providers/database';
-
-import type {
-  ArangoConfig,
-  ArangoConnectOptions,
-  ArangoCoordinatorMember,
-  ArangoLike,
-  ArangoMembershipSnapshot,
-  ArangoMembershipVerifier,
-  Query,
 } from '@forgezero/providers/database';
 ```
 
@@ -289,27 +216,11 @@ export const selectedCapability = ARANGO_COMMUNITY_VERSION;
 <a id="forgezero-providers-http"></a>
 ## @forgezero/providers/http
 
-Outbound HTTP with a per-host weight budget reserved before the call and settled from the response. This entry exposes 9 named value exports and 5 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Outbound HTTP with a per-host weight budget reserved before the call and settled from the response. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   BudgetExhausted,
-  binanceWeight,
-  budgetState,
-  createHttpClient,
-  http,
-  httpProviders,
-  resetBudgets,
-  settle,
-  spend,
-} from '@forgezero/providers/http';
-
-import type {
-  HostBudget,
-  HttpClient,
-  HttpConfig,
-  HttpRequest,
-  HttpResponse,
 } from '@forgezero/providers/http';
 ```
 
@@ -328,20 +239,11 @@ export const selectedCapability = BudgetExhausted;
 <a id="forgezero-providers-pool"></a>
 ## @forgezero/providers/pool
 
-Which outbound address a request leaves by, sticky per key, over the same budget as everything else. This entry exposes 3 named value exports and 4 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Which outbound address a request leaves by, sticky per key, over the same budget as everything else. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   PoolEmpty,
-  PoolExhausted,
-  createAddressPool,
-} from '@forgezero/providers/pool';
-
-import type {
-  AddressPool,
-  Lease,
-  PoolAddress,
-  PoolOptions,
 } from '@forgezero/providers/pool';
 ```
 
@@ -360,19 +262,12 @@ export const selectedCapability = PoolEmpty;
 <a id="forgezero-providers-chain"></a>
 ## @forgezero/providers/chain
 
-An EVM node behind the same failover as any other service: read logs, broadcast, and never stop scanning because one endpoint rate-limited. This entry exposes 1 named value export and 4 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+An EVM node behind the same failover as any other service: read logs, broadcast, and never stop scanning because one endpoint rate-limited. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   evmRpc,
 } from '@forgezero/providers/chain';
-
-import type {
-  ChainCall,
-  ChainLog,
-  ChainReceipt,
-  ChainResult,
-} from '@forgezero/providers/chain';
 ```
 
 ## @forgezero/providers/chain — Use this entry point
@@ -390,19 +285,11 @@ export const selectedCapability = evmRpc;
 <a id="forgezero-providers-binance"></a>
 ## @forgezero/providers/binance
 
-Binance behind the venue adapter: three hosts, one weight budget, signed over the exact string that is sent. This entry exposes 4 named value exports and 2 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Binance behind the venue adapter: three hosts, one weight budget, signed over the exact string that is sent. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   binanceSymbol,
-  createBinanceAdapter,
-  readBinanceError,
-  toOrderStatus,
-} from '@forgezero/providers/binance';
-
-import type {
-  BinanceCredentials,
-  BinanceOptions,
 } from '@forgezero/providers/binance';
 ```
 
@@ -421,29 +308,11 @@ export const selectedCapability = binanceSymbol;
 <a id="forgezero-providers-storage"></a>
 ## @forgezero/providers/storage
 
-S3-compatible object storage, SigV4 signed with Web Crypto and no vendor SDK. This entry exposes 9 named value exports and 7 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+S3-compatible object storage, SigV4 signed with Web Crypto and no vendor SDK. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   MAX_SINGLE_PUT_BYTES,
-  StorageError,
-  amzDate,
-  createS3Client,
-  encodeSegment,
-  parseListXml,
-  s3,
-  signRequest,
-  storageProviders,
-} from '@forgezero/providers/storage';
-
-import type {
-  ObjectSummary,
-  PutObjectArgs,
-  S3Client,
-  S3Config,
-  S3Credentials,
-  SignedRequest,
-  StorageRequest,
 } from '@forgezero/providers/storage';
 ```
 
@@ -462,20 +331,11 @@ export const selectedCapability = MAX_SINGLE_PUT_BYTES;
 <a id="forgezero-providers-translation"></a>
 ## @forgezero/providers/translation
 
-Google AI Studio translation with strict batch alignment and classified quota failures. This entry exposes 4 named value exports and 3 named type exports. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Google AI Studio translation with strict batch alignment and classified quota failures. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   TranslationError,
-  googleAiStudio,
-  parseStrings,
-  translationProviders,
-} from '@forgezero/providers/translation';
-
-import type {
-  TranslateRequest,
-  TranslateResult,
-  TranslationProvider,
 } from '@forgezero/providers/translation';
 ```
 
@@ -494,16 +354,11 @@ export const selectedCapability = TranslationError;
 <a id="forgezero-providers-realtime"></a>
 ## @forgezero/providers/realtime
 
-Cloudflare KV node-directory and Durable Object fan-out clients for project-defined realtime services. This entry exposes 2 named value exports and 1 named type export. The generated import block lists one name per line for scanning and copying; keep only the names used by your file.
+Cloudflare KV node-directory and Durable Object fan-out clients for project-defined realtime services. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
 
 ```text
 import {
   RealtimeProviderError,
-  cloudflareRealtime,
-} from '@forgezero/providers/realtime';
-
-import type {
-  RealtimeProviderOptions,
 } from '@forgezero/providers/realtime';
 ```
 
@@ -519,11 +374,40 @@ import {
 export const selectedCapability = RealtimeProviderError;
 ```
 
+<a id="forgezero-providers-git"></a>
+## @forgezero/providers/git
+
+Versioned Git Connect contracts for accounts, repositories, branches, webhooks and short-lived clone credentials; GitHub, GitLab and private forges attach without changing the service. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
+
+```text
+import {
+  defineGitConnectProvider,
+} from '@forgezero/providers/git';
+```
+
+## @forgezero/providers/git — Use this entry point
+
+This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
+
+```text
+import {
+  defineGitConnectProvider,
+} from '@forgezero/providers/git';
+
+export const selectedCapability = defineGitConnectProvider;
+```
+
 ## Built-in provider capabilities
 
 A provider owns versioned capabilities; it does not own a service. A service method attaches an exact provider, method and version in an ordered array. Current, legacy and deprecated branches can coexist; retired branches never run.
 
 ```text
+github-app
+  - listAccounts
+  - listRepositories
+  - listBranches
+  - ensureWebhook
+  - cloneCredential
 evm-rpc
   - request
 jetemail
@@ -541,6 +425,29 @@ google-ai-studio
   - translate
 ```
 
+## GitHub App (github-app)
+
+Import: @forgezero/providers/git. Each method below is a provider capability that a service attaches by exact version. User OAuth verifies an email and is discarded before the mandatory passkey. App installation credentials are minted on demand, limited to one selected repository, and expire rather than being stored. GitLab or a private forge implements the same Git Connect service without pretending to be GitHub.
+
+```text
+importPath: '@forgezero/providers/git'
+providerId: 'github-app'
+methods:
+  - listAccounts
+  - listRepositories
+  - listBranches
+  - ensureWebhook
+  - cloneCredential
+credentials:
+  - clientSecret
+  - privateKey
+  - webhookSecret
+config:
+  - clientId
+  - appId
+  - slug
+```
+
 ## EVM JSON-RPC node (evm-rpc)
 
 Import: @forgezero/providers/chain. Each method below is a provider capability that a service attaches by exact version. Several endpoints per chain is the normal case, not a luxury: public RPC is rate-limited and paid gateways have outages, and a scanner that stops when one is down stops crediting deposits while the money sits on the chain. "Already known" and "nonce too low" are TERMINAL — the transaction is already in flight, so rebroadcasting through another node is how a sweep gets sent twice.

package/dist/binance.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/chain.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/chain.ts
 var hexToNumber = (value) => Number(BigInt(value));

package/dist/database.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/database.ts
 var pools = new Map;

package/dist/email.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/email.ts
 var recipients = (to) => Array.isArray(to) ? [...to] : [to];

package/dist/git.d.ts

@@ -0,0 +1,124 @@
+import { type FailureKind, type InvokeContext, type ProviderDefinition } from './index';
+export interface GitAccount {
+    id: string;
+    label: string;
+    kind: 'user' | 'organization' | 'group' | 'other';
+}
+export interface GitRepository {
+    id: string;
+    fullName: string;
+    private: boolean;
+    defaultBranch: string;
+    cloneUrl: string;
+}
+export interface GitBranch {
+    name: string;
+    protected?: boolean;
+}
+export interface GitCloneCredential {
+    username: string;
+    token: string;
+    expiresAtTs: number;
+}
+export interface GitAccountRequest {
+    cursor?: string;
+}
+export interface GitRepositoryRequest {
+    accountId: string;
+    cursor?: string;
+}
+export interface GitBranchRequest {
+    accountId: string;
+    repository: string;
+    cursor?: string;
+}
+export interface GitWebhookRequest {
+    accountId: string;
+    repository: string;
+    callbackUrl: string;
+    secret: string;
+    events: readonly ['push'];
+}
+export interface GitCloneCredentialRequest {
+    accountId: string;
+    repository: string;
+}
+export declare const githubAppConfigSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly clientId: {
+            readonly type: "string";
+            readonly minLength: 10;
+            readonly maxLength: 128;
+        };
+        readonly appId: {
+            readonly type: "string";
+            readonly pattern: "^[1-9][0-9]{0,19}$";
+        };
+        readonly slug: {
+            readonly type: "string";
+            readonly pattern: "^[a-z0-9][a-z0-9-]{0,99}$";
+        };
+    };
+    readonly required: readonly ["clientId", "appId", "slug"];
+    readonly additionalProperties: false;
+};
+export declare const githubAppCredentialSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly clientSecret: {
+            readonly type: "string";
+            readonly minLength: 20;
+            readonly maxLength: 512;
+            readonly writeOnly: true;
+        };
+        readonly privateKey: {
+            readonly type: "string";
+            readonly minLength: 800;
+            readonly maxLength: 32768;
+            readonly writeOnly: true;
+        };
+        readonly webhookSecret: {
+            readonly type: "string";
+            readonly minLength: 32;
+            readonly maxLength: 256;
+            readonly writeOnly: true;
+        };
+    };
+    readonly required: readonly ["clientSecret", "privateKey", "webhookSecret"];
+    readonly additionalProperties: false;
+};
+export declare const gitConnectService: import("./index").ServiceDefinition<"git-connect", {
+    listAccounts: import("./index").ServiceMethodContract<GitAccountRequest, readonly GitAccount[]>;
+    listRepositories: import("./index").ServiceMethodContract<GitRepositoryRequest, readonly GitRepository[]>;
+    listBranches: import("./index").ServiceMethodContract<GitBranchRequest, readonly GitBranch[]>;
+    ensureWebhook: import("./index").ServiceMethodContract<GitWebhookRequest, {
+        webhookId: string;
+        created: boolean;
+    }>;
+    cloneCredential: import("./index").ServiceMethodContract<GitCloneCredentialRequest, GitCloneCredential>;
+}>;
+export interface GitConnectAdapter {
+    listAccounts(context: InvokeContext, args: GitAccountRequest): Promise<readonly GitAccount[]>;
+    listRepositories(context: InvokeContext, args: GitRepositoryRequest): Promise<readonly GitRepository[]>;
+    listBranches(context: InvokeContext, args: GitBranchRequest): Promise<readonly GitBranch[]>;
+    ensureWebhook(context: InvokeContext, args: GitWebhookRequest): Promise<{
+        webhookId: string;
+        created: boolean;
+    }>;
+    cloneCredential(context: InvokeContext, args: GitCloneCredentialRequest): Promise<GitCloneCredential>;
+}
+/**
+ * Define one Git forge without coupling it to ForgeZero Vault or API storage.
+ * A GitHub App, GitLab OAuth application, self-hosted forge, or future provider
+ * supplies this adapter; the service keeps the same five typed operations.
+ */
+export declare function defineGitConnectProvider(args: {
+    id: string;
+    label: string;
+    version: string;
+    adapter: GitConnectAdapter;
+    credentials?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+    classify?: (error: unknown) => FailureKind;
+}): ProviderDefinition;

package/dist/git.js

@@ -0,0 +1,400 @@
+// src/index.ts
+class ProviderError extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "ProviderError";
+  }
+}
+function envCredentials(env) {
+  return {
+    name: "env",
+    async get(reference, field) {
+      const key = `${reference}_${field}`.replace(/[.-]/g, "_").toUpperCase();
+      const value = env[key];
+      if (value === undefined) {
+        throw new ProviderError("CREDENTIAL_MISSING", `Set ${key} in the environment.`);
+      }
+      return value;
+    }
+  };
+}
+function chainCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(reference, field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(reference, field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No source held ${reference}.${field}.`);
+    }
+  };
+}
+function scopeCredentials(source, reference) {
+  return {
+    name: `${source.name}:${reference}`,
+    get: (field) => source.get(reference, field)
+  };
+}
+function chainScopedCredentials(...sources) {
+  return {
+    name: sources.map((source) => source.name).join("+"),
+    async get(field) {
+      let last;
+      for (const source of sources) {
+        try {
+          return await source.get(field);
+        } catch (error) {
+          last = error;
+        }
+      }
+      throw last instanceof Error ? last : new ProviderError("CREDENTIAL_MISSING", `No scoped source held field "${field}".`);
+    }
+  };
+}
+function staticConfig(config) {
+  const providers = new Map(config.providers.map((provider) => [provider.instanceKey, provider]));
+  if (providers.size !== config.providers.length) {
+    throw new ProviderError("CONFIG_DUPLICATE_INSTANCE", "Provider instance keys must be unique.");
+  }
+  const health = new Map;
+  return {
+    name: "static",
+    async provider(instanceKey) {
+      const provider = providers.get(instanceKey);
+      return provider ? { ...provider, config: { ...provider.config } } : undefined;
+    },
+    async list(serviceKey, methodKey) {
+      return (config.services[serviceKey]?.[methodKey] ?? []).map((attachment) => ({
+        ...attachment,
+        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, 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, version = "v1", lifecycle = "current", invoke, classify, ...identity } = spec;
+  return defineProvider({
+    ...identity,
+    methods: { [method]: defineProviderMethod({ version, lifecycle, invoke, classify }) }
+  });
+}
+var STRIKES_TO_OFFLINE = 3;
+function serviceMethod() {
+  return Object.freeze({});
+}
+function defineService(definition) {
+  return definition;
+}
+function nextHealth(current, kind) {
+  if (kind === "success")
+    return { strikes: 0, status: "ok" };
+  if (kind === "backoff")
+    return current ?? { strikes: 0, status: "ok" };
+  const strikes = (current?.strikes ?? 0) + 1;
+  return {
+    strikes,
+    status: strikes >= STRIKES_TO_OFFLINE ? "offline" : "degraded",
+    lastFailureAtTs: Date.now()
+  };
+}
+function createRegistry(options) {
+  const byId = new Map(options.providers.map((provider) => [provider.id, provider]));
+  async function call(serviceKey, methodKey, args, callOptions = {}) {
+    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,
+          fallbackUsed: attempts.length > 0,
+          attempts,
+          error: new ProviderError("CALL_ABORTED", `The "${serviceKey}.${methodKey}" call was cancelled.`)
+        };
+        await options.after?.(cancelled);
+        return cancelled;
+      }
+      const instance = await options.config.provider(attachment.instanceKey);
+      if (!instance) {
+        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 = methodBranch(spec, attachment.providerMethod, requestedVersion);
+      if (!spec || !method) {
+        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, 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, providerMethodVersion: method.version, outcome: "skipped", error: "offline" });
+        continue;
+      }
+      await options.before?.({ service: serviceKey, method: methodKey, provider: instance.providerId, instance: instance.instanceKey });
+      const startedAt = performance.now();
+      try {
+        const result = await method.invoke({
+          config: instance.config,
+          secret: (field) => options.credentials.get(instance.secretRef, field),
+          signal: callOptions.signal
+        }, args);
+        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, providerMethodVersion: method.version },
+          fallbackUsed: attempts.length > 1,
+          attempts
+        };
+        await options.after?.(sent);
+        return sent;
+      } catch (error) {
+        if (callOptions.signal?.aborted) {
+          const cancelled = {
+            ok: false,
+            fallbackUsed: attempts.length > 0,
+            attempts,
+            error: new ProviderError("CALL_ABORTED", `The "${serviceKey}.${methodKey}" call was cancelled.`)
+          };
+          await options.after?.(cancelled);
+          return cancelled;
+        }
+        const kind = method.classify(error);
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof ProviderError ? error.code : typeof error?.code === "string" ? error.code : undefined;
+        attempts.push({
+          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, method.version, nextHealth(attachment.health, kind));
+        if (kind === "terminal") {
+          const refused = {
+            ok: false,
+            fallbackUsed: attempts.length > 1,
+            attempts,
+            error: new ProviderError("PAYLOAD_REJECTED", "The request was refused as malformed; no provider will accept it.")
+          };
+          await options.after?.(refused);
+          return refused;
+        }
+      }
+    }
+    const failed = {
+      ok: false,
+      fallbackUsed: attempts.length > 1,
+      attempts,
+      error: new ProviderError(attempts.length === 0 ? "NO_PROVIDER" : "ALL_PROVIDERS_FAILED", attempts.length === 0 ? `No provider method is configured for "${serviceKey}.${methodKey}".` : `Every provider method for "${serviceKey}.${methodKey}" failed or was skipped.`)
+    };
+    await options.after?.(failed);
+    return failed;
+  }
+  function service(definition) {
+    return {
+      call(method, args, callOptions) {
+        return call(definition.key, method, args, callOptions);
+      }
+    };
+  }
+  return { call, service };
+}
+function createService(definition, methods, options = {}) {
+  const providers = new Map;
+  const credentials = new Map;
+  const instances = [];
+  const serviceMethods = {};
+  for (const methodKey of Object.keys(definition.methods)) {
+    const attachments = methods[methodKey];
+    if (!Array.isArray(attachments)) {
+      throw new ProviderError("CONFIG_METHOD_MISSING", `Service method "${definition.key}.${methodKey}" needs an attachment array.`);
+    }
+    const priorities = new Set;
+    serviceMethods[methodKey] = attachments.map((attachment, index) => {
+      if (!Number.isInteger(attachment.priority) || attachment.priority < 1 || attachment.priority > 1000) {
+        throw new ProviderError("CONFIG_PRIORITY", `Priority for "${definition.key}.${methodKey}" must be an integer from 1 to 1000.`);
+      }
+      if (priorities.has(attachment.priority)) {
+        throw new ProviderError("CONFIG_PRIORITY_DUPLICATE", `Priorities for "${definition.key}.${methodKey}" must be unique.`);
+      }
+      priorities.add(attachment.priority);
+      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) {
+        throw new ProviderError("CONFIG_PROVIDER_DUPLICATE", `Provider id "${attachment.provider.id}" has more than one definition.`);
+      }
+      providers.set(attachment.provider.id, attachment.provider);
+      const internalKey = `${definition.key}:${methodKey}:${index}`;
+      credentials.set(internalKey, attachment.credentials);
+      instances.push({
+        instanceKey: internalKey,
+        providerId: attachment.provider.id,
+        enabled: attachment.enabled ?? true,
+        config: { ...attachment.config ?? {} },
+        secretRef: internalKey
+      });
+      return {
+        instanceKey: internalKey,
+        providerMethod: attachment.method,
+        providerMethodVersion: branch.version,
+        priority: attachment.priority,
+        enabled: attachment.enabled ?? true
+      };
+    });
+  }
+  const registry = createRegistry({
+    providers: [...providers.values()],
+    config: staticConfig({ providers: instances, services: { [definition.key]: serviceMethods } }),
+    credentials: {
+      name: [...new Set([...credentials.values()].map((source) => source.name))].join("+"),
+      async get(reference, field) {
+        const source = credentials.get(reference);
+        if (!source)
+          throw new ProviderError("CREDENTIAL_SOURCE_MISSING", "The provider credential source is unavailable.");
+        return source.get(field);
+      }
+    },
+    ...options
+  });
+  const dynamic = registry.service(definition);
+  return {
+    async call(method, args, callOptions) {
+      const result = await dynamic.call(method, args, callOptions);
+      const { instance: _instance, selected, attempts, ...rest } = result;
+      return {
+        ...rest,
+        ...selected ? { selected: { providerId: selected.providerId, providerMethod: selected.providerMethod, providerMethodVersion: selected.providerMethodVersion } } : {},
+        attempts: attempts.map(({ instanceKey: _instanceKey, ...attempt }) => attempt)
+      };
+    }
+  };
+}
+var VERSION = "0.1.23";
+
+// src/git.ts
+var githubAppConfigSchema = {
+  type: "object",
+  properties: {
+    clientId: { type: "string", minLength: 10, maxLength: 128 },
+    appId: { type: "string", pattern: "^[1-9][0-9]{0,19}$" },
+    slug: { type: "string", pattern: "^[a-z0-9][a-z0-9-]{0,99}$" }
+  },
+  required: ["clientId", "appId", "slug"],
+  additionalProperties: false
+};
+var githubAppCredentialSchema = {
+  type: "object",
+  properties: {
+    clientSecret: { type: "string", minLength: 20, maxLength: 512, writeOnly: true },
+    privateKey: { type: "string", minLength: 800, maxLength: 32768, writeOnly: true },
+    webhookSecret: { type: "string", minLength: 32, maxLength: 256, writeOnly: true }
+  },
+  required: ["clientSecret", "privateKey", "webhookSecret"],
+  additionalProperties: false
+};
+var gitConnectService = defineService({
+  key: "git-connect",
+  methods: {
+    listAccounts: serviceMethod(),
+    listRepositories: serviceMethod(),
+    listBranches: serviceMethod(),
+    ensureWebhook: serviceMethod(),
+    cloneCredential: serviceMethod()
+  }
+});
+function defineGitConnectProvider(args) {
+  const classify = args.classify ?? (() => "retryable");
+  const branch = (invoke) => defineProviderMethodBranches({
+    currentVersion: args.version,
+    versions: {
+      [args.version]: { version: args.version, lifecycle: "current", invoke, classify }
+    }
+  });
+  return defineProvider({
+    id: args.id,
+    label: args.label,
+    multiInstance: true,
+    credentials: args.credentials,
+    config: args.config,
+    methods: {
+      listAccounts: branch(args.adapter.listAccounts),
+      listRepositories: branch(args.adapter.listRepositories),
+      listBranches: branch(args.adapter.listBranches),
+      ensureWebhook: branch(args.adapter.ensureWebhook),
+      cloneCredential: branch(args.adapter.cloneCredential)
+    }
+  });
+}
+export {
+  githubAppCredentialSchema,
+  githubAppConfigSchema,
+  gitConnectService,
+  defineGitConnectProvider
+};

package/dist/http.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/index.d.ts

@@ -303,5 +303,5 @@ export interface EmailBatchResult {
     };
     results: readonly EmailBatchItemResult[];
 }
-export declare const VERSION = "0.1.21";
+export declare const VERSION = "0.1.23";
 export {};

package/dist/index.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 export {
   staticConfig,
   serviceMethod,

package/dist/pool.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/storage.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/storage.ts
 var encoder = new TextEncoder;

package/dist/translation.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.21";
+var VERSION = "0.1.23";
 
 // src/translation.ts
 var GOOGLE_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/providers",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -46,6 +46,10 @@
     "./realtime": {
       "types": "./dist/realtime.d.ts",
       "default": "./dist/realtime.js"
+    },
+    "./git": {
+      "types": "./dist/git.d.ts",
+      "default": "./dist/git.js"
     }
   },
   "scripts": {
@@ -85,6 +89,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgezero/runtime": "^0.1.13"
+    "@forgezero/runtime": "^0.1.14"
   }
 }