@lmzhen/dsh-evolution-io 0.22.0 → 0.24.0

package/lib/index.js

@@ -58,5 +58,28 @@ var EvolutionIoRegistry = class extends Service {
 		return first;
 	}
 };
+/**
+* Resolve the seam implementation for a consumer, preferring a backend the deployment mounted.
+*
+* Contract C2 (declared gaps) has no other shape: a consumer that can work on either medium asks for
+* its preference and the DEPLOYMENT decides which backends exist. The lookup is contained here because
+* the registry deliberately has no presence probe (v20 A-3 removed `hasProvider`; a presence probe goes
+* through `provider(name)`, which fails loud) — so this function is the ONE sanctioned place that turns
+* that failure into a fallback. A caller that needs a SPECIFIC backend must call `provider(name)` and
+* take the error.
+* @param registry - the seam registry (`ctx.evolutionIo`).
+* @param names - preferred provider names, most preferred first.
+* @returns the first registered preference, else the registry default.
+*/
+/**
+* @typeParam T - the seam implementation type the caller works with (`EvolutionIo` or the wider
+*   `EvolutionIoLike`), so the same helper serves every consumer shape.
+*/
+function preferProvider(registry, names) {
+	for (const name of names) try {
+		return registry.provider(name);
+	} catch {}
+	return registry.provider();
+}
 //#endregion
-export { EvolutionIoRegistry, EvolutionIoRegistry as default };
+export { EvolutionIoRegistry, EvolutionIoRegistry as default, preferProvider };

package/lib/types/index.d.ts

@@ -51,5 +51,25 @@ export declare class EvolutionIoRegistry extends Service {
     }): () => void;
     provider(name?: string): EvolutionIo;
 }
+/**
+ * Resolve the seam implementation for a consumer, preferring a backend the deployment mounted.
+ *
+ * Contract C2 (declared gaps) has no other shape: a consumer that can work on either medium asks for
+ * its preference and the DEPLOYMENT decides which backends exist. The lookup is contained here because
+ * the registry deliberately has no presence probe (v20 A-3 removed `hasProvider`; a presence probe goes
+ * through `provider(name)`, which fails loud) — so this function is the ONE sanctioned place that turns
+ * that failure into a fallback. A caller that needs a SPECIFIC backend must call `provider(name)` and
+ * take the error.
+ * @param registry - the seam registry (`ctx.evolutionIo`).
+ * @param names - preferred provider names, most preferred first.
+ * @returns the first registered preference, else the registry default.
+ */
+/**
+ * @typeParam T - the seam implementation type the caller works with (`EvolutionIo` or the wider
+ *   `EvolutionIoLike`), so the same helper serves every consumer shape.
+ */
+export declare function preferProvider<T>(registry: {
+    provider(name?: string): T;
+}, names: readonly string[]): T;
 export default EvolutionIoRegistry;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-io",
   "description": "IO seam for evolution providers (community build)",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "publishConfig": {
     "access": "public"
   },
@@ -26,7 +26,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@lmzhen/dsh-evolution-core": "^0.22.0"
+    "@lmzhen/dsh-evolution-core": "^0.24.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"